Textify Voice: Product & Functional Specification

Status: draft for implementation · Owner: Joshua Saimon Sakweli (QBIT SPARK) Companion doc: ARCHITECTURE.md (components, data model, APIs, infra). This file is written so a new engineer, or a new AI coding session, can pick up the work with no prior context.

1. Background

Textify Africa (textify.africa) is an existing bulk SMS + WhatsApp platform, written in Go, live in Tanzania, Uganda and Nigeria. Its main model is white-label: agencies and resellers ("partners") brand the platform as their own, set their own prices, and onboard their own customers. Customers top up a prepaid wallet with mobile money or card.

We are adding a third channel: a call center / business phone line product, similar in spirit to SemaCall (semacall.com): "One business. One number. Every team." Customers call one number; the call reaches the right person (or an AI answers) in the customer's language.

The voice capability is built as a separate service ("Voice Service") in Java Spring Boot. Textify consumes it as a client. The Voice Service must not know about Textify's users, auth or money.

2. Goals

1. A Textify customer can get a Tanzanian phone number and have every incoming call answered, by an AI receptionist (Swahili first, English supported) or by human agents in the browser.
2. AI can hand the caller over to a human when needed.
3. Every call is logged, optionally recorded, transcribed and summarized.
4. Missed calls trigger an automatic SMS/WhatsApp follow-up (Textify already does messaging).
5. Usage is billed per minute from the existing Textify wallet.
6. The Voice Service is reusable by other QBIT SPARK products later (JikoXpress, Mauzodukani, NexGate) without changes.

3. Non-goals (for now)

• No video calls over phone lines (LiveKit SIP does not support video over SIP anyway).
• No user accounts, roles, plans or pricing inside the Voice Service.
• No approval workflows anywhere. Keep everything self-service and simple.
• Countries other than Tanzania (Uganda/Nigeria later, using the same design).
• Building our own telco connection. We use Africa's Talking for numbers and the PSTN.

4. Key terms (plain language)

5. Providers we use and why

6. Costs (Africa's Talking Tanzania, as published on africastalking.com/pricing, Oct 2026)

6.1 How the costs combine

Every call has leg 1 (customer ⇄ our AT number) and, if someone answers, leg 2 (our number ⇄ whoever answers).

Customer ──leg 1──> AT number ──leg 2──> answerer
          17 in / 60 out          SIP trunk to LiveKit: 8.61
                                  forward to a mobile: 60   (avoid)

Key facts already agreed:

• Cost follows call minutes, not the number of agents. Idle agents cost nothing, so customers can add unlimited agents.
• Avoid forwarding to mobiles. Agents answer in the browser/app.
• Design decision: money is not the constraint, so all calls go through the SIP trunk into LiveKit (one call path, simpler code). We don't split IVR onto AT XML to save the 8.61.

6.2 AI cost (on top of telco)

An AI-answered minute adds OpenAI cost (Realtime, or STT + LLM + TTS). This is several times the telco cost per minute. Exact per-minute figures must be measured during the PoC from real calls (token/audio usage logged per call).

6.3 Indicative selling prices (suggestion, to be finalized after PoC)

Pricing lives in Textify only. The Voice Service only reports usage.

7. Users & personas

• Business owner / admin (Textify customer): gets a number, sets the AI greeting and business info, adds agents, sees calls, recordings and summaries.
• Human agent: logs into the Textify web app, sets themselves available, answers calls in the browser, makes click-to-call outbound calls.
• Caller: a member of the public calling the business number from any TZ network.
• Partner (reseller): later phase. Resells voice under their own brand (same white-label model as SMS).

8. Functional requirements

8.1 Numbers

• FR-N1: Textify admin (QBIT/Textify ops) obtains numbers from AT and registers them in the Voice Service.
• FR-N2: A number is assigned to exactly one account (Textify's tenant id, opaque to the Voice Service).
• FR-N3: Each number has an answer mode: AI_FIRST (AI answers, can hand over), HUMAN_ONLY (ring agents), AI_ONLY.
• FR-N4: Reassigning or releasing a number is a single API call. No approval.

8.2 Inbound calls

• FR-I1: Caller dials the number → call arrives over the SIP trunk → LiveKit creates a room → Voice Service records a call RINGING.
• FR-I2: Before answering, the Voice Service asks Textify "can this account take a call?" (prepaid balance). If Textify is unreachable, allow the call (fail-open) and bill later.
• FR-I3: If the account can't pay: play a short polite message and end the call (no AI cost).
• FR-I4: Play a recording consent notice when recording is on ("Simu hii inaweza kurekodiwa kwa ajili ya ubora wa huduma"; in English: "This call may be recorded for quality of service").
• FR-I5: AI_FIRST / AI_ONLY → AI receptionist joins and greets with the account's greeting.
• FR-I6: HUMAN_ONLY → ring the account's available agents (ring group). If nobody answers within N seconds (default 30) → voicemail or AI fallback (configurable) → mark MISSED if nobody handled it.
• FR-I7: Caller keypresses (DTMF) are supported for simple menus ("press 1 for sales").

8.3 AI receptionist

• FR-A1: Speaks Swahili first, switches to English if the caller does. Handles code-switching (Swahili and English mixed).
• FR-A2: Uses the account's instructions (business info, FAQs, hours, tone) supplied by Textify.
• FR-A3: Short, spoken-style answers. Never invents prices or policies. If unsure → offer a human.
• FR-A4: Tools the AI can use (v1): transfer_to_human, take_message, end_call. Later: account-defined tools (check order, book appointment) via webhooks to the client app.
• FR-A5: Handover: AI calls transfer_to_human → Voice Service rings available agents → first to accept joins the room → AI briefly introduces the context (warm transfer), then leaves.
• FR-A6: If no agent is available: AI takes a message (name, number, reason) → stored on the call → event to Textify.
• FR-A7: Barge-in/interruptions and turn detection are handled by LiveKit Agents.

8.4 Human agents (browser)

• FR-H1: Agents are identified only by an opaque agentRef from Textify. Textify owns the user, login and role.
• FR-H2: Agent sets status AVAILABLE / BUSY / OFFLINE through Textify, which forwards it to the Voice Service.
• FR-H3: Incoming call → available agents in the group get a ring in the browser (data message over LiveKit). Accept → join the call room. Reject or timeout → next.
• FR-H4: Ring strategy: ALL_AT_ONCE (default) or ROUND_ROBIN.
• FR-H5: Agent can mute, hold, hang up, and transfer to another agent.
• FR-H6: Click-to-call outbound from the dashboard: agent clicks a number → Voice Service dials out via the trunk → agent and customer in one room.
• FR-H7: Fallback transfer to an external mobile is allowed (costs about TZS 60/min). Off by default.

8.5 Recording, transcription, summary

• FR-R1: Recording on/off per number (default on, with consent notice).
• FR-R2: After the call: audio file stored in our object storage (never rely on provider links).
• FR-R3: Transcription (Swahili/English) → summary containing:
  • 2–3 line summary
  • customer intent, resolved yes/no
  • follow-up actions
  • sentiment (positive / neutral / negative)
  • topic tag (sales, support, complaint, inquiry, other)
• FR-R4: Transcript + summary attached to the call record; event summary.ready sent to the client app.
• FR-R5: Retention: recordings deleted after 90 days by default (configurable per account). Tanzania Personal Data Protection Act applies.
• FR-R6: Summary is a billable add-on (Textify decides price; Voice Service reports summaryMinutes).

8.6 Missed calls & follow-ups

• FR-M1: A call is MISSED if no human or AI handled it (e.g. HUMAN_ONLY with nobody answering and no fallback, or the caller hung up while ringing).
• FR-M2: Voice Service emits call.missed with the caller number. Textify sends the SMS/WhatsApp follow-up ("Samahani tumekukosa, tutakupigia tena"; in English: "Sorry we missed you, we'll call you back") using its existing messaging.

8.7 Usage & billing

• FR-B1: On every call end, the Voice Service emits call.ended with usage broken down by leg (seconds): inboundSeconds, outboundSeconds, trunkSeconds, aiSeconds, externalTransferSeconds, recorded (bool), summarySeconds.
• FR-B2: Textify prices and deducts from the wallet. The Voice Service never deals with money.
• FR-B3: Events are idempotent (event id) and retried until Textify returns 2xx.

8.8 Dashboard (built in Textify, data from the Voice Service)

• Call log: time, direction, caller, number, handled by (AI / agent), duration, status, cost (Textify-computed).
• Call detail: audio player, transcript, summary, AI message taken.
• Number settings: answer mode, greeting, AI instructions, recording on/off, ring group, timeout, fallback.
• Agents: availability, calls handled.
• Simple stats: calls per day, answered vs missed, AI-handled vs human, average duration.

9. Non-functional requirements

10. Phases

Phase 0: Proof of concept (goal: one real call end-to-end)

1. Confirm with AT (see §11). Get one TZ number + SIP trunk.
2. Dedicated box: LiveKit server + LiveKit SIP + Redis. Firewall restricted to AT.
3. Inbound trunk + dispatch rule → Spring Boot dials OpenAI Realtime into the room over SIP → AI greets in Swahili.
4. Measure: latency, audio quality, OpenAI cost per minute.
5. Swahili test: 10–20 real people (Swahili, English, mixed). Judge understanding and voice. Swap TTS if the voice is weak.

Phase 1: MVP (sellable)

• Spring Boot Voice Service: accounts, numbers, config, calls, events, LiveKit integration.
• AI receptionist with handover to browser agents.
• Browser agent client (in Textify's web app) + ring groups + click-to-call.
• Recording + storage + retention.
• Balance check + call.ended usage events → wallet deduction in Textify.
• Missed-call SMS/WhatsApp.

Phase 2

• Transcripts + AI summaries (if not already in MVP).
• Account-defined AI tools (webhooks to the client app: check order, booking).
• Voicemail, business hours / after-hours behaviour.
• Stats dashboard.

Phase 3

• Voice broadcast (recorded message to a contact list: "bulk voice", fits Textify's bulk DNA). Check TZ calls-per-second limits.
• AI outbound campaigns (reminders that talk back).
• White-label voice for partners.
• Other countries (Uganda/Nigeria) through AT.
• Other QBIT products as clients of the Voice Service.

11. Open questions for Africa's Talking (must answer before Phase 1)

1. Can the TZ SIP trunk route inbound calls for our number to an external SIP URI (our LiveKit SIP endpoint)? Note: LiveKit SIP does not support SIP REGISTER, so AT must send calls to us directly.
2. Can it accept outbound calls from our server IP (and what auth: IP allowlist or username/password)?
3. What are AT's SIP signalling and media IP addresses (for our firewall allowlist)?
4. Exact billing for inbound to trunk: 17 + 8.61? Any extra?
5. Exact billing for outbound via trunk: 60 + 8.61? Any extra?
6. Is the SIP agent TZS 4.30 charged on inbound calls too? Any setup/monthly fee for SIP agents?
7. Are unanswered rings to SIP endpoints billed? 7b. The listed regular number is Airtel. How do callers on Vodacom, Yas, Halotel and TTCL reach it, and at what cost to them and to us?
8. Calls-per-second (CPS) limits and pricing in Tanzania (needed for broadcast).
9. Supported codecs (G.711 PCMU/PCMA expected) and DTMF method (RFC 2833/4733).
10. Does reselling voice to our customers need any TCRA licence on our side, or is AT's licence enough? Get it in writing.
11. Number porting / getting several numbers quickly; toll-free availability.

AT is not on LiveKit's list of tested SIP providers (Twilio, Telnyx, Exotel, Plivo, Wavix, Sinch, didlogic). LiveKit is designed to work with any SIP provider, so the PoC must prove compatibility.

12. Risks

13. Decisions log