Voice notes, groups and calling
How inbound voice notes are transcribed, when the assistant replies with a voice note, how it behaves in WhatsApp groups, and why live calls are not supported.
Message bursts
Customers often split one thought across several messages. Storing a message is immediate, but the answer runs about 3 seconds later through /jobs/answer. If a newer answerable message from the same customer arrives first, the older answer job skips itself, and the newest one answers every unanswered message together. Reactions, stickers and system messages never trigger or cancel an answer. In groups this merging is off: each addressed message is answered on its own, so one member's text is never attributed to another.
Voice notes
| Step | Behavior |
|---|---|
| Inbound voice note | Downloaded from the OpenWA gateway and transcribed in the answer job. The transcript is stored on the message, so retries reuse it. |
| Transcription provider | Per assistant: Sarvam saaras:v4 (Indian languages, accepts WhatsApp OGG/Opus as-is, about 30 s per request), ElevenLabs Scribe, or off. Notes over about 120 KB go to ElevenLabs first. If one provider fails, the other is tried. |
| No transcript | The customer gets the assistant's fallback message asking them to type. |
| Spoken reply | Only when the customer's latest message was a voice note and "Reply with a voice note" is on. ElevenLabs renders Opus at 32 kbps; the engine checks the bytes are an Ogg file and sends them base64 through send-audio with ptt: true and mimetype audio/ogg; codecs=opus. While rendering and sending, the chat shows the recording state. |
| Spoken reply fails | Any failure (rendering, wrong format, send) falls back to the text reply. A speech outage never blocks an answer. |
Provider keys
Transcription needs SARVAM_API_KEY or ELEVENLABS_API_KEY on the engine;
spoken replies need ELEVENLABS_API_KEY. An empty balance (HTTP 402) is not
retried. The engine falls back to the other provider or to text.
Not yet supported
Spoken replies through Sarvam need an Opus encoder in the Worker (Sarvam
returns WAV). Voice notes longer than the sync limits need the providers'
batch APIs. Both are documented in docs/voice-and-groups.md.
Groups
Groups are ordinary WhatsApp groups that the linked account belongs to. There is no Official Business Account requirement and no 8-member cap, and members join the normal way (the linked account is added, or it creates the group with phone numbers). Because this is a linked personal-style account, group behavior is what keeps the number safe, so it is conservative.
| Rule | Why |
|---|---|
| Off by default; enable per assistant with "Only when addressed" | An unprompted bot in a group is the fastest way to get reported and restricted. |
Answers only when a member replies to the assistant's message or uses a trigger word (for example @Asha, whole words, any case, any script) | The assistant should never interrupt a conversation it was not asked into. |
| One reply per addressed message, no burst merging | One member's text is never attributed to another. |
| Group history is loaded only from that group, labeled with member names | Private conversations never leak into a group, and group talk never enters a private chat. |
| Replies are plain text, quoting the addressed message, and quick replies are omitted | Linked accounts have no buttons, and a list in a group is noise. |
| No typing indicator while a group message is waiting to be answered | It would show to every member for every message. Inbound messages are still marked read. |
| A leaving member's rights to group memory end | group.leave events mark the participant as having left. |
From the Groups page admins create a group (name and phone numbers), list groups, view group info, get an invite link, add or remove participants, and leave a group. Groups also appear in the inbox from group.join, group.update and group.leave events or when their first message arrives. Group replies serialize per group so two members cannot get overlapping answers.
Live calls
Not supported. OpenWA gives a linked account text, media and voice notes; it does not expose live call audio, and answering calls would also need a media service that terminates WebRTC, which a Worker cannot do. Incoming call events are stored as system messages and the assistant does not respond to them. Ask customers to send a voice note or text instead.
Knowledge and answers
Ingestion and chunking, full-text retrieval, citation enforcement, handoff rules, prompt caching, model and effort configuration, cost, and refusal fallbacks.
Security
The unofficial-API risk, tenant isolation with forced row level security, webhook and queue signatures, admin bearer auth, and the prompt-injection stance.