> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Call Assistant: A Voice Agent for WhatsApp Business Calls
> Build a voice AI agent that answers WhatsApp business calls, holds a real spoken conversation, runs your APIs mid-call as skills, and logs every call for review.
The **AI Call Assistant** is a voice agent that answers WhatsApp business phone calls, holds a real spoken conversation with the caller, can look things up or take actions mid-call (its *skills*), and records every call in [Call Logs](/features/call-logs). You build and manage assistants under **More → AI Call Assistant**.
You use this page to set up the assistant and review its calls. The live conversation itself — turning the caller's voice into text, sending it to the AI, turning the AI's reply into speech, and playing it back — runs automatically in the background once a call comes in.
Each assistant belongs to one workspace and is built with a five-step wizard: **Identity → AI Brain → Skills → Voice → Routing**. Every assistant has a status (Live, Draft, or Paused) and an on/off switch; it only answers calls when it's switched on **and** set to Live.
**Prerequisite — the admin sets the provider keys.** The AI provider keys (OpenAI, Anthropic Claude, Google Gemini) and voice keys (ElevenLabs for the spoken voice, Deepgram for transcription) are configured once by the platform admin under **Admin → AI & API Keys**. You don't paste a key — every assistant uses the admin's keys automatically. Add a per-assistant key only if you want this one assistant billed to your own account.
**Plan-gated — three features.** Building assistants needs the **AI Voice Agent** plan feature. The calls those assistants answer, plus [Call Logs](/features/call-logs), need **WhatsApp Calling** (see [WhatsApp Calling](/features/whatsapp-calling)). Playing back call recordings needs a third feature, **Call Recording**. If your plan doesn't include these, the menu items are hidden.
## How a live call works
Knowing what happens during a call makes every wizard field easier to understand. Each call runs through these steps:
An incoming call arrives for your number, tagged with the caller's details and which assistant should answer.
It pulls in the assistant's configuration and the voice keys for your workspace. If either the transcription key (Deepgram) or the speech key (ElevenLabs) is missing, the call is **declined up front** so the voicemail fallback handles it — rather than leaving the caller in silence.
The audio link to the caller is set up and answered.
As soon as the line is live, the agent speaks a greeting — picked at random from your greeting variations — so the caller never hears dead air.
The caller's speech is transcribed to text in real time (Deepgram). The agent takes the recent \~12 turns plus your behaviour brief and asks the AI model for a reply. That reply is turned into a natural voice (ElevenLabs) and played back. Repeat until the caller says a hangup keyword — then the agent speaks the goodbye line and ends the call.
Transcript turns are saved as the call happens, so a call in progress already shows a growing transcript in [Call Logs](/features/call-logs).
## Creating an assistant
From the AI Call Assistant list, click **New assistant**. The wizard saves the full assistant state at once, so you can jump between steps freely and click **Save** at any time.
Either click **New assistant** or open an existing assistant to edit it.
The side panel shows a live, text-only preview of how a call would read, plus the chosen AI provider and voice.
Leave it as *Draft* while building; flip the Live switch in Step 1 when you're ready for it to answer real calls.
The assistant is saved to your workspace, and all skills are saved exactly as shown in the form.
Do this before relying on it — the in-app preview is text-only and doesn't test the voice or the actual phone call.
## Step 1 · Identity & persona
| Field | Required | Default | What it does |
| ------------------------------ | ------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| **Agent name** | Yes (max 120) | — | Shown in call logs and transcripts, e.g. "Riley · Acme Support". |
| **Languages the agent speaks** | No | English | One or more languages. The *first* is used to transcribe the caller's speech for that call. |
| **Starting persona** | No | Support | A preset that sets the tone — see below. Override the wording in Step 2. |
| **Greeting variations** | No (max 5) | One default line | Several opening lines; one is picked at random per call so it doesn't sound robotic. |
| **Live switch** | No | On | Together with the status, controls whether the agent answers calls. |
### Persona presets
| Persona | Character |
| ------------- | ------------------------------------------------ |
| **Support** | Patient, helpful, resolves issues calmly. |
| **Sales** | Friendly, persuasive, qualifies before pitching. |
| **Scheduler** | Crisp, calendar-aware, books slots end-to-end. |
| **Concierge** | Warm, contextual, remembers prior callers. |
## Step 2 · AI Brain
Choose which AI model powers the agent and how it behaves.
| Field | Required | Default | Notes |
| ----------------------------- | -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Provider** | Yes | Gemini | Gemini (Google), OpenAI, or Anthropic. |
| **Model** | Yes (max 80) | `gemini-2.5-flash-lite` | The exact model name, typed in free-text, so you can switch to a newer model without waiting for an app update. |
| **Your own key** | No (max 500) | blank | Optional; leave blank to use the admin's key. |
| **Behaviour brief** | No (max 6000) | blank | Instructions that shape every reply. |
| **Knowledge source URL** | No (max 500, must be a web link) | blank | A web page the agent can draw on for your own content. |
| **Warmth / Formality / Pace** | No | 60 / 50 / 50 | Sliders from 0–100. Pace controls how concise the agent is. |
### Model reference
The default for a new voice agent is `gemini-2.5-flash-lite` — chosen because Gemini responds fastest on voice calls.
| Provider | Suggested models | Use it for |
| ------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Gemini · Google | `gemini-2.5-flash-lite` (default), `gemini-2.5-flash`, `gemini-2.5-pro` | Fastest on voice; flash-lite for high call volume, pro for the hardest reasoning. |
| GPT · OpenAI | `gpt-4o-mini`, `gpt-4o`, `gpt-4.1` | Best reasoning and use of skills. |
| Claude · Anthropic | `claude-haiku-4-5-20251001`, `claude-sonnet-4-6`, `claude-opus-4-7` | Steadiest tone; haiku for fast cheap calls, opus for complex policy. |
### Behaviour brief & personality tips
* **Behaviour brief.** State who the agent is, what to ask for, which skills to use, and when to hand off to a human. Left blank, the agent falls back to "you are a helpful voice assistant on a phone call — reply with one short sentence at a time so the caller can interject."
* **Knowledge source (web link).** An optional page the agent can reference so it answers from your own content.
* **Warmth / Formality / Pace.** Fine-tune the delivery. Pace also keeps the agent concise so it doesn't over-talk.
* **Your own key.** Leave blank to use the admin's key. A saved key shows "saved · leave blank to keep"; an empty box never erases it.
## Step 3 · Skills (tools)
A **skill** lets the agent call one of your web services mid-conversation — to look up an order, book a slot, or create a ticket. The agent is told "call this if the caller asks about X"; when it decides to, it sends a request to your web address with details it picked up from the conversation, then uses the response in its reply. Each assistant can have up to **25** skills.
| Skill field | Required | What it does |
| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Function name** | Yes (max 80) | How the agent refers to the skill, e.g. `track_order`. |
| **Trigger keywords** | No | Phrases the agent listens for; when heard, it pulls details from the caller's words and runs the skill. |
| **Request method** | Yes | GET, POST, PUT, PATCH, or DELETE (matching your service). |
| **URL** | Yes (max 600, must be a web link) | The web address to call. |
| **Headers** | No | Optional sign-in headers, as name/value pairs. |
| **Parameters** | No | The data to send with the request. |
Skills can chain: the agent calls one, reads the response, then calls another in the same turn. Use `@placeholder` tokens in skill values that are auto-filled from the caller's history. Every skill the agent uses is recorded in the tool-call timeline in [Call Logs](/features/call-logs) with its details and the time into the call.
**Save behaviour.** Saving stores the skills exactly as shown in the form — removing a skill in the form removes it on save. There are never leftover entries.
## Step 4 · Voice & listening
Controls how the agent sounds (text-to-speech) and how it hears the caller (speech-to-text).
### Text-to-speech engine (the voice)
| Engine | Character |
| -------------------- | ----------------------------------------------------- |
| ElevenLabs (default) | Premium, natural-sounding — the most lifelike voices. |
| OpenAI | Fast, six built-in voices. |
| Deepgram Aura | Ultra-fast responses. |
### Speech-to-text engine (the listening)
| Engine | Character |
| ------------------------------------ | ------------------------------------------------- |
| ElevenLabs · Deep Analysis (default) | Deep-analysis transcription. |
| Deepgram Nova-2 | Fastest — the engine used for the live call loop. |
| OpenAI Whisper | Most accurate. |
| Google Speech | Google's speech recognition. |
### Extras
* **Voice ID** (max 80) — optional specific voice. Blank falls back to the provider's default (ElevenLabs uses "Rachel").
* **Your own voice key** (max 500) — optional; "blank keeps the saved key" behaviour as with the AI key.
* **Background noise suppression** (default on) — strips traffic, fan, and keyboard sounds before transcription, improving accuracy on noisy lines.
## Step 5 · Routing & recording
Decides what gets recorded, what happens on voicemail, and when to hand off to a person.
| Field | Default | What it does |
| ----------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Record agent audio** | On | Saves the AI voice side of the call. |
| **Record caller audio** | On | Saves the caller's side. Also needs the **Call Recording** plan feature. |
| **Auto transcript** | On | Saves the turn-by-turn transcript. |
| **Voicemail / no-answer behaviour** | Leave message | See table below. |
| **Hangup keywords** | bye, goodbye | Words that end the call; the agent speaks the goodbye line, then hangs up after \~1.5 seconds. |
| **Hand off to team** | blank | When the AI is unsure, send the conversation to a [Team Inbox](/features/team-inbox) queue. Blank means no handoff. |
| **Goodbye line** | "Thank you for calling. Goodbye!" | The closing message the agent speaks before hanging up (max 500). |
### Voicemail / no-answer behaviour
| Option | What happens |
| ------------------- | ----------------------------------- |
| **Leave message** | Speaks the greeting and hangs up. |
| **Retry in 1 hour** | Schedules a callback automatically. |
| **Silent log** | Hangs up; only logs the attempt. |
The three recording switches are independent — a call can have a transcript but no audio, or one side of the audio but not the other.
## Your own keys vs admin keys
Both the AI key and voice key are **optional** and stored securely. Soneka picks which key to use in this order:
1. **Your workspace's own key.** If your plan allows your own keys *and* your workspace has an active key for that provider, your key is used and usage bills to you.
2. **Admin's key.** Otherwise the admin's key is used, and usage counts toward your workspace's monthly AI usage limit.
3. **Neither.** You'll see a clear error — and on a live call, the call is declined so voicemail handles it rather than the caller hearing silence.
In practice: leave both key fields blank and the assistant uses the admin keys automatically. Add a key only when this specific assistant needs a different voice or its own quota.
## Managing assistants
* **Pause / Go live** — switch an assistant between Live and Paused without opening the wizard.
* **Duplicate** — copies the full configuration and all skills into a new *draft* named "(copy)", handy for spinning up a variant.
* **Delete** — removes the assistant but keeps its call logs readable. Calls already in progress continue; new calls go unanswered.
The list shows per-status counts (all, live, draft, paused) and, for each assistant, its model, voice provider, skill count, and how many calls it handled in the last 24 hours. A "Call logs" shortcut sits next to "New assistant".
## Cost cautions
**A live voice agent bills three AI meters per call** — the AI model (tokens in and out), speech-to-text (seconds of audio transcribed), and text-to-speech (characters spoken) — on top of your WhatsApp/WABA calling minutes. Premium voices and larger models cost noticeably more per minute.
* **Keep assistants in Draft until tested.** A badly written brief that makes the agent ramble inflates both AI and voice spend on every call.
* **Prefer lite / mini / haiku models** and a concise Pace for high call volume.
* **Watch per-call cost** on the call detail page in [Call Logs](/features/call-logs), which breaks out the three metered parts: AI usage, transcription, and spoken voice.
* When you use admin keys, AI usage counts toward your plan's monthly usage limit; hitting it blocks further AI calls until you upgrade or switch to your own key.
## Troubleshooting
| Symptom | Likely cause & fix |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The assistant never answers calls | It must be switched on *and* set to Live. Check the Step 1 Live switch and the status badge. Confirm your plan includes **WhatsApp Calling** and a number is routed to this assistant. |
| Caller hears a click then silence, or the call is declined | The call is declined when the Deepgram or ElevenLabs key is missing for your workspace. Have the admin set both under AI & API Keys; the voicemail fallback handles the caller meanwhile. |
| The agent talks but cannot hear the caller | Transcription key missing or the line is very noisy. Check the Deepgram key and turn on Background noise suppression in Step 4. |
| A skill never fires | Tighten the trigger keywords and confirm the web address can be reached. Check the tool-call timeline in [Call Logs](/features/call-logs) to see whether the agent tried the call. |
| The menu item is missing entirely | Your plan lacks the **AI Voice Agent** feature. Upgrade or move to a plan that includes it. |
| A saved key seems to disappear | Keys are stored securely and never shown back — the field reads "saved · leave blank to keep". An empty box keeps the saved key; type a new value only to replace it. |