Voice agent calls · Beta

Let your AI voice agent answer the calls to your WhatsApp number

When someone calls the number of your instance, WaAPI can answer the call and connect its audio to your voice agent. The agent hears the caller, the caller hears the agent, both ways in real time.

Beta

Voice agent calls are in beta and have to be enabled for your account. Ask support to switch them on. Until then the option does not appear in the dashboard, and the API refuses it with a 422.

What it is for and how it compares with Meta’s Calling API: calling API alternative.

Three ways to reach your agent

sip

We dial your agent's SIP address.

Vapi, Retell, ElevenLabs, OpenAI Realtime, any SIP endpoint

websocket

We open a WebSocket to your URL and stream the call in the Twilio Media Streams format.

Your own server, or any agent that accepts Twilio Media Streams

websocket_inbound

We send you a webhook with a stream address, and your agent connects to us.

Your own server, when it cannot accept incoming connections

How a call works

  1. A call comes in. If your instance webhook subscribes to call, that event is sent as before.
  2. WaAPI contacts your agent. The call keeps ringing for the caller until your agent is ready.
  3. As soon as your agent answers (SIP) or the stream is open (WebSocket), the call is answered and the audio flows.
  4. The call ends when the caller hangs up, when your agent hangs up, or after 60 minutes.

Good to know

  • Only answered when your agent is reachable. If your agent is not ready within about 20 seconds of the call coming in, the call is not answered. It keeps ringing for the caller, exactly as without a call setting. A caller never ends up in an answered call with nobody on the other end.
  • One call per instance at a time. While a call is connected to your agent, a second call to the same number is not answered and keeps ringing.
  • Maximum length 60 minutes. After 60 minutes the call is ended.
  • Incoming calls only, voice only. Video calls are answered as voice calls. There are no outgoing agent calls, no keypad tones (DTMF) and no recording in this beta.
  • No audio is stored. WaAPI passes the audio through and keeps none of it.
  • Your other webhooks stay as they are. The call and call_ended events keep arriving if your webhook subscribes to them.

Set it up in the dashboard

  1. Open the instance in your account.
  2. Go to the tab Sending & calls, section Call settings.
  3. Under Incoming calls, choose Connect to a voice agent.
  4. Under Voice agent, choose one of:
    • SIP: we dial your agent's SIP address
    • WebSocket: we stream the call to your URL
    • WebSocket: your agent connects to us
  5. Fill in the fields for that type (below) and click Save call settings.
Agent typeFields
SIPSIP URI, SIP username (optional), SIP password
WebSocket, we stream to your URLWebSocket URL, Audio format
WebSocket, your agent connects to usAudio format (your instance also needs a webhook URL, tab Webhooks)

Audio format offers μ-law, 8 kHz (mulaw_8000, the default) and PCM 16-bit, 16 kHz (pcm_16000). SIP agents negotiate their codec themselves and have no audio format setting.

If the instance is offline when you save, you see “Call settings saved. The instance is not reachable right now — they will apply when it reconnects.”

Set it up through the API

Send the call settings as call_policy with an instance update:

PUT https://waapi.app/api/v1/instances/{id}
Authorization: Bearer <your API token>
Content-Type: application/json
Accept: application/json

call_policy is replaced as a whole on every update that contains it. Leave it out to keep the current settings, send null to switch back to the default (calls are left alone, only the call webhook fires if you subscribed to it).

One request body per agent type:

{
  "call_policy": {
    "mode": "connect_agent",
    "agent": {
      "type": "sip",
      "sip_uri": "sip:[email protected]",
      "sip_username": "my-user",
      "sip_password": "my-secret"
    }
  }
}
{
  "call_policy": {
    "mode": "connect_agent",
    "agent": {
      "type": "websocket",
      "websocket_url": "wss://agent.example.com/stream",
      "audio_format": "mulaw_8000"
    }
  }
}
{
  "webhook": {
    "url": "https://example.com/waapi/webhook"
  },
  "call_policy": {
    "mode": "connect_agent",
    "agent": {
      "type": "websocket_inbound",
      "audio_format": "pcm_16000"
    }
  }
}

For websocket_inbound, the webhook part is only needed if the instance has no webhook URL yet: the stream address reaches you through it.

Field rules

FieldRule
agent.typesip, websocket or websocket_inbound; required
agent.sip_uriRequired for sip. Starts with sip: or sips:, has a user part and a host (sip:user@host), at most 512 characters. It must not contain a password (sip:user:password@host is refused): use sip_password.
agent.sip_usernameOptional, at most 128 characters
agent.sip_passwordOptional, at most 256 characters (see below)
agent.websocket_urlRequired for websocket. Starts with wss://, at most 2048 characters, must be reachable from the internet: localhost, private network addresses and local names are refused.
agent.audio_formatmulaw_8000 (default) or pcm_16000; used by both WebSocket types
webhook URLRequired for websocket_inbound, either already stored on the instance or sent in the same request

The SIP password

  • It is stored encrypted and never shown again. Responses carry "sip_password": null and "has_sip_password": true or false. The dashboard shows “•••• saved” in the empty field.
  • To keep it, leave it out (or leave the field empty in the dashboard). It is kept only while the SIP URI stays exactly the same: change anything in the SIP URI and you have to send the password again.
  • Switching to another agent type discards it.

Errors when saving (422)

MessageMeaning
Voice agent calls are in beta and not enabled for this account.Ask support to enable the beta.
Voice agent calls are not available right now.Temporarily unavailable on our side. Try again later or contact support.
Voice agent calls need a newer node; try again after the next update.The server your instance runs on has not been updated yet.
A webhook URL is required for agent type websocket_inbound, it is how you learn the stream address.Set a webhook URL first, or send it in the same request.
The SIP URI must not contain a password; the password has its own field.Move the password to sip_password.

SIP agents

Most hosted voice agent platforms (Vapi, Retell, ElevenLabs, OpenAI Realtime and others) can take calls over SIP. In your provider's settings, look for the option to receive calls over SIP (often called “SIP trunk”, “inbound SIP” or “custom telephony”) and copy the SIP address it gives you. If the provider asks for authentication, also set up a username and password there. During the beta we have tested the connection live with Vapi; other providers that accept standard SIP should work the same way. If one does not connect, tell us and we look into it.

Using Vapi? Connect Vapi step by step.

What WaAPI needs:

  • SIP URI: the address your provider gave you, for example sip:[email protected].
  • SIP username and password: only if your provider requires authentication for incoming calls.

What our side does, in case you configure your own SIP endpoint or a firewall:

  • TLS by default. We connect over TLS, also for a sip: URI, on the port in the URI, otherwise 5061. Only ;transport=tcp or ;transport=udp in the URI selects an unencrypted connection. The server certificate must be valid.
  • Authentication: username and password answer a digest challenge (401 or 407) to our INVITE.
  • Codecs: the first INVITE offers G.722 (16 kHz wideband) only. If your agent declines it with 488, 415, 603 or 606, we send one more INVITE offering PCMU and PCMA (G.711). The media is plain RTP with 20 ms packets.
  • Timing: your agent has 15 seconds to answer the INVITE. Without an answer we cancel it.
  • During the call we send an in-dialog OPTIONS request every 10 seconds. Two unanswered in a row end the call; your agent should answer them (most SIP stacks do so automatically).
  • Hang-up: your agent ends the call with a BYE.
  • Public addresses only. The SIP address, the signalling address in your answer and the media address in your SDP must be public. Private network addresses and localhost are refused.

What the INVITE carries:

WhereValue
Request URIYour SIP URI
From<sip:[email protected]>, with CALLER the caller's number as digits, or anonymous
X-WaAPI-CallerThe caller's number as digits, or anonymous
X-WaAPI-Instance-IdYour instance id
X-WaAPI-Call-IdThe id of the call
User-Agentwaapi-call-relay

WebSocket agents (Twilio Media Streams format)

Both WebSocket types use the message format of Twilio Media Streams (bidirectional). WaAPI plays Twilio's part, so code written for Twilio Media Streams works with few or no changes.

websocket: we connect to your URL

  • Your URL must start with wss:// and be reachable from the internet with a valid TLS certificate.
  • We must be connected within 5 seconds. Redirects are not followed.
  • If your server answers the upgrade with an HTTP status instead of opening the WebSocket (for example 401, 404 or a redirect), the call is not answered.

websocket_inbound: your agent connects to us

When a call comes in, WaAPI sends the webhook event call_stream_ready to your instance's webhook URL:

{
  "event": "call_stream_ready",
  "instanceId": "123",
  "data": {
    "callId": "<call id>",
    "caller": "491701234567",
    "streamUrl": "wss://stream.waapi.app/v1/stream?token=…",
    "expiresInSeconds": 15
  }
}
  • Your agent opens a WebSocket to streamUrl within 15 seconds. Use the URL exactly as received.
  • The URL works once. A second connection for the same call is refused.
  • The URL contains a one-time credential: do not log it or pass it on.
  • The event goes to the instance's own webhook URL in this mode, whatever events it subscribes to. Webhook subscriptions (POST /instances/{id}/webhooks) receive it only if they list call_stream_ready.
  • It is signed and carries the same headers as your other webhook events, but it is sent only once, without retries: a retry would come after the 15 seconds. Answer the webhook quickly and connect right away.
  • Without a webhook URL on the instance, calls are not answered.

If we close your connection, the close code tells you why:

CodeMeaning
1000Normal end of the call
1001Our side is shutting down
1011Internal error on our side
4401Unknown, expired or already used stream URL, or the call is over
4403The token does not belong to this endpoint
4409Your agent is already connected for this call
4429Too many connections from your address, or too many unknown tokens

Messages we send

The first two messages arrive as soon as the connection is open, before the caller is connected.

connected

{"event": "connected", "protocol": "Call", "version": "1.0.0"}

start

{
  "event": "start",
  "sequenceNumber": "1",
  "start": {
    "accountSid": "WA123",
    "streamSid": "WS0f6c0e2d4b9a4c1e8a7b3d5f6e9c2a10",
    "callSid": "WC<call id>",
    "tracks": ["inbound"],
    "customParameters": {
      "instanceId": "123",
      "callId": "<call id>",
      "caller": "491701234567"
    },
    "mediaFormat": {"encoding": "audio/x-mulaw", "sampleRate": 8000, "channels": 1}
  },
  "streamSid": "WS0f6c0e2d4b9a4c1e8a7b3d5f6e9c2a10"
}
  • accountSid is WA followed by your instance id, callSid is WC followed by the call id, streamSid is WS followed by the id of this stream.
  • customParameters.caller is the caller's number as digits, or an empty string when it is not known.
  • mediaFormat follows your audio format:
audio_formatmediaFormatBytes per message (20 ms)
mulaw_8000{"encoding": "audio/x-mulaw", "sampleRate": 8000, "channels": 1}160
pcm_16000{"encoding": "audio/x-pcm-s16le", "sampleRate": 16000, "channels": 1}640

pcm_16000 is our extension of the format: 16-bit signed samples, little-endian, mono.

media

The caller's voice, one message per 20 ms.

{
  "event": "media",
  "sequenceNumber": "3",
  "media": {"track": "inbound", "chunk": "1", "timestamp": "2140", "payload": "<base64 audio>"},
  "streamSid": "WS0f6c0e2d4b9a4c1e8a7b3d5f6e9c2a10"
}
  • sequenceNumber counts every message we send from "1" (the start message), chunk counts the media messages from "1". Both are strings.
  • timestamp is milliseconds since start was sent, as a string. The caller's audio only begins once the call is connected, so the first timestamp is usually well above 0.

mark

The echo of a mark you sent, once the audio you sent before it has been played to the caller.

{"event": "mark", "sequenceNumber": "57", "streamSid": "WS0f6c0e2d4b9a4c1e8a7b3d5f6e9c2a10", "mark": {"name": "greeting-done"}}

stop

The call is over (caller hung up, maximum length reached, or an error). We close the connection right after it.

{"event": "stop", "sequenceNumber": "812", "stop": {"accountSid": "WA123", "callSid": "WC<call id>"}, "streamSid": "WS0f6c0e2d4b9a4c1e8a7b3d5f6e9c2a10"}

Messages you send

media

Your agent's voice, base64, in the same format as mediaFormat.

{"event": "media", "media": {"payload": "<base64 audio>"}}
  • Any length works; we cut the audio into 20 ms pieces. A single message may be up to 1 MiB of JSON.
  • You can send faster than real time: we play it at normal speed and hold up to 60 seconds of it. Beyond that the oldest audio is dropped.
  • Audio you send before the caller is connected (a greeting right after start) is held and played once the call is connected. The first 5 seconds of it are kept, anything beyond is dropped.
  • A streamSid field, as Twilio clients add it, is accepted and not checked.

mark

A marker behind the audio you sent so far. We echo it once that audio has been played. Names may be up to 256 bytes.

{"event": "mark", "mark": {"name": "greeting-done"}}

clear

Drop all your audio that has not been played yet, for example when the caller interrupts. Every mark still waiting is echoed at once.

{"event": "clear"}

Other events are ignored.

Hanging up, and staying connected

  • To hang up, close the WebSocket normally (close code 1000 or 1001). The audio you already sent is played first, then the call ends. A stop message from your side does not end the call.
  • If the connection breaks or closes with another code, the call ends at once.
  • We send a WebSocket ping every 10 seconds. Two pings without a pong end the call. Standard WebSocket libraries answer pings on their own.

Example: connect to the stream (Node.js)

// Called by your webhook handler for the event "call_stream_ready".
import WebSocket from 'ws';

function onCallStreamReady(payload) {
  const ws = new WebSocket(payload.data.streamUrl); // never log this URL

  ws.on('message', (raw) => {
    const msg = JSON.parse(raw);
    switch (msg.event) {
      case 'start':
        // msg.start.mediaFormat says how to read and write the audio
        break;
      case 'media': {
        const callerAudio = Buffer.from(msg.media.payload, 'base64');
        // hand callerAudio to your speech pipeline ...
        break;
      }
      case 'stop':
        // the call is over
        break;
    }
  });

  // Send your agent's audio (same format) like this:
  // ws.send(JSON.stringify({ event: 'media', media: { payload: agentAudio.toString('base64') } }));
}

For the websocket type, the same messages arrive on the connection your server accepted.

What your agent learns about the caller

WhereField
SIPFrom user part and X-WaAPI-Caller: digits, or anonymous
WebSocketstart.customParameters.caller: digits, or an empty string
Webhook call_stream_readydata.caller: digits, or null

The caller's number is only passed on when the platform tells us the number. Currently it often identifies the caller only by an internal id, and then your agent gets no number (anonymous, an empty string or null). Build your agent so it works without the caller's number, for example by asking for it.

Call results and troubleshooting

Each call connected to your agent is recorded in the instance's status log:

EventMeaning
call_stream_startedThe call was answered and connected to your agent.
call_stream_endedA connected call ended, with a reason (usually caller_hung_up or agent_hung_up) and its length.
call_stream_failedThe call could not be connected, or broke off, with a reason.

During the beta the status log is not shown in your dashboard. If a call did not reach your agent, contact support with the instance id and the time of the call, and we look up the reason for you.

ReasonWhat happenedWhat to check
caller_hung_upThe caller hung up.Nothing, this is a normal end.
agent_hung_upYour agent ended the call (SIP BYE, or the WebSocket closed normally).Nothing, unless your agent hangs up too early.
agent_unreachableYour agent could not be reached in time, or stopped answering during the call.SIP: is the SIP URI right, does your agent answer within 15 seconds, is the certificate valid, does it answer OPTIONS? WebSocket: is the URL public and reachable within 5 seconds with a valid certificate, does your server answer pings?
agent_rejectedYour agent refused the call.SIP: the agent answered with an error, often wrong credentials, an unknown address, or no common codec (G.722, PCMU, PCMA). It also happens when its answer names a private address. WebSocket: your server answered with an HTTP status instead of opening the connection.
agent_not_connectedYour agent did not connect to the stream address within 15 seconds (websocket_inbound).Does your webhook URL receive call_stream_ready? Does your agent connect right away, to the exact streamUrl?
stream_activeAnother call was already connected to your agent on this instance.Only one call per instance at a time.
max_durationThe call reached 60 minutes.Nothing.
beta_disabledThe beta is not enabled for your account.Contact support.
policy_not_connect_agentThe call setting changed while the call came in, or (websocket_inbound) the instance has no webhook URL.Check the call settings and the webhook URL.
relay_unreachable, relay_closed, relay_not_configured, not_connected, node_shutdown, errorA problem on our side.Contact support if it happens more than once.

When a call fails before it is answered, it keeps ringing for the caller, as without a call setting.

Laravel SDK

Older versions of waapi/waapi-laravel-sdk answer webhook events they do not know with an HTTP 500, and call_stream_ready is new. If you use the SDK's webhook route with websocket_inbound, update to the first version that includes CallStreamReadyEvent once it is released, or handle call_stream_ready in a route of your own.

Try it on your own number

Voice agent calls are in beta and have to be enabled for your account. Ask support to switch them on.