Skip to main content
A voice channel is one WhatsApp call in progress. It is the connection’s unit of concurrency: with 3 channels, the connection can have up to 3 calls at the same time, outbound and inbound combined.
Every unofficial WhatsApp connection includes 1 channel. Official API connections (cloud_api) don’t place calls through this API.

Limits and price

Channels are per connection: each number has its own. On the invoice, the extras of all the account’s connections are summed in one line.

Get the connection’s channels

integer
The connection’s current channels (including the included one).
integer
Maximum channels per connection.
number
Monthly price of each extra channel, in BRL.
string | null
How the account pays: stripe (card) or internal_pix (Pix invoice). null when there is no Scale subscription.
boolean
true when the account is not on the Scale plan and therefore can’t add extra channels.

Change the number of channels

PUT /sessions/{sessionId}/voice-channels sets the connection’s total channels. Send the final number you want, not the increment: to go from 1 to 3 channels, send 3. Repeating the same call doesn’t charge again nor restart the connection.
integer
required
Total channels for the connection, from 1 to 5.
integer
Extra channels billed on this connection after the change.

Billing

1

Increase

On a card, the prorated amount until the end of the cycle is charged right away. If the card is declined, the change is undone and the API returns 402. On a Pix invoice, the prorated amount goes on the next invoice.
2

Decrease

Takes effect immediately and gives no credit for the period already paid.
3

Applying

The connection restarts to apply the new number. Calls in progress on that connection drop; messages are not lost.

Errors

Calls with more than one channel

With more than one channel, each call is independent and identified by its callId.
  • New calls (POST /calls/place, POST /calls/stream) and answering an incoming one (POST /calls/accept) take a channel. When all are busy, the API refuses with the error a call is already in progress — treat it as “busy” and retry when a call ends.
  • Incoming offers only take a channel once you answer. A ringing offer doesn’t block new calls.
  • End, mute and get state (POST /calls/end, POST /calls/mute, POST /calls/state) require the callId when more than one call is active. Without it the API returns callId is required: N calls active instead of acting on the wrong call. With a single call, callId stays optional.
  • Real-time audio: each call has its own media WebSocket (wsUrl), exactly as in Stream Calls. Closing the WebSocket ends only that call.
  • call.* webhooks don’t change: each event already carries the callId of the call it belongs to. Use it to tell the conversations apart.
Store the callId returned by place, stream or accept with your conversation. It’s what addresses the right call when several are active.