Calls APIs
Overview
Voice calls let your clients call your WhatsApp business number and talk to an agent, or to an AI assistant, from the inbox. Calls work on WhatsApp Channels connected through the WhatsApp Cloud API (WhatsApp on Meta). Bread Crumbs bridges the WhatsApp call into an audio room, and the agent’s browser or app joins that room.
Availability
Voice calls are enabled per workspace. While they are off for your workspace, the APIs on this page fail with Calls are not enabled for this workspace and the conversation activeCall field is always null. Calling also has to be turned on for the WhatsApp Channel: set callingEnabled to true in the Channel properties with the Patch Channel API. properties replaces the stored object, so send the Channel’s other properties too.
How a call flows
- The client calls your WhatsApp number. A call with status
RINGINGis created on the client’s open conversation (a conversation is opened if needed). While the call rings or is in progress, the conversation’sactiveCallfield returns it. - If the conversation is assigned to an AI assistant, the AI answers right away: the call becomes
ACTIVEwithhandler: AI, and the call transcript is saved as text messages in the conversation. The AI can hand the call over to a human. The call then goes back toRINGINGwithhandler: AGENT, and the conversation is handed over to an agent. - Otherwise, if the conversation has an assigned agent, that agent gets an
Incoming voice callpush notification. An agent answers with Answer Call, gets an access token and joins the call audio. A call that nobody answers within about 45 seconds becomesMISSED. - The call ends when the client hangs up, when an agent uses Hang Up Call or Reject Call, or when the AI ends it. Every finished call adds a note to the conversation, for example
Missed voice callorVoice call answered by an agent - 2m 5s.
Call properties
| Property | Type | Description |
|---|---|---|
id | string | The call ID. |
workspaceId | number | The workspace ID. |
integrationId | string | The WhatsApp Channel ID that received the call. |
convId | string | The conversation the call belongs to. |
clientId | string | The client on the call. |
status | CallStatus |
|
handler | CallHandler | Who handles the call: |
direction | CallDirection |
|
roomName | string | The audio room bridged to the WhatsApp call, |
startedAt | DateTime | When the call reached Bread Crumbs. |
answeredAt | DateTime | When an agent or an AI assistant answered. Null for calls that were never answered. |
endedAt | DateTime | When the call ended. |
duration | number | Call length in seconds, as reported by WhatsApp when the call ends on the client's side. Null for calls ended from Bread Crumbs. |
assigneeId | string | The agent the call is assigned to. Copied from the conversation assignee when the call arrives, then set to the agent who answers. |
aiId | string | The AI assistant handling the call, when |
List Active Calls API
List the calls in the workspace that are ringing or in progress (RINGING, CONNECTING or ACTIVE), newest first. Use it to show incoming calls or to find the callId for the call mutations. For one conversation, read its activeCall field with the Conversations APIs instead.
Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) see every active call; Agent and Agent+ users see calls on conversations assigned to them or unassigned. Works with workspace API keys (all calls) and agent API keys (calls on conversations assigned to the linked agent, plus unassigned ones).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery activeCalls($input: ActiveCallsInput!) {
activeCalls(input: $input) {
id
convId
clientId
integrationId
status
handler
direction
assigneeId
aiId
startedAt
answeredAt
}
}
input ActiveCallsInput {
workspaceId: Int! # Workspace ID.
}The query above returns JSON structured like this:
{
"data": {
"activeCalls": [
{
"id": "call_123",
"convId": "conv_123",
"clientId": "client_123",
"integrationId": "integration_123",
"status": "RINGING",
"handler": "AGENT",
"direction": "USER_INITIATED",
"assigneeId": "agent_123",
"aiId": null,
"startedAt": "2026-10-17T09:30:00.000Z",
"answeredAt": null
},
{
"id": "call_456",
"convId": "conv_456",
"clientId": "client_456",
"integrationId": "integration_123",
"status": "ACTIVE",
"handler": "AI",
"direction": "USER_INITIATED",
"assigneeId": null,
"aiId": "ai_123",
"startedAt": "2026-10-17T09:27:41.000Z",
"answeredAt": "2026-10-17T09:27:42.000Z"
}
]
}
}| Error | Cause |
|---|---|
Calls are not enabled for this workspace | Voice calls are not enabled for the workspace. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"activeCalls","variables":{"input":{"workspaceId":12}},"query":"query activeCalls($input: ActiveCallsInput!) {\n activeCalls(input: $input) {\n id\n convId\n clientId\n integrationId\n status\n handler\n direction\n assigneeId\n aiId\n startedAt\n answeredAt\n }\n}"}'Answer Call API
Answer a ringing call, or join a call that is already active, and get what you need to join its audio. If the WhatsApp call has not been picked up yet, Bread Crumbs accepts it on WhatsApp and bridges it into an audio room named call-<callId>. If the call already has a room (for example a call the AI assistant handed over), the agent joins that room.
The call becomes ACTIVE with handler: AGENT and is assigned to the answering agent. The conversation is also assigned to that agent if it was assigned to someone else or to an AI assistant, which fires the CONVERSATION_ASSIGNED webhook event.
Access: Signed-in users only (portal session token). Owner, Admin and Manager can act on any call. Agent+ and Agent need an agent profile in the workspace and can act on calls assigned to them or unassigned. Workspace API keys and agent API keys are rejected with You cannot answer a call assigned to another agent, because the call is matched to the caller’s user account. Owner, Admin and Manager also need an agent profile to answer.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
callId | string | Required. The call ID, from List Active Calls or the conversation |
CallJoinPayload fields
The response holds the updated call and the credentials this agent uses to join the call audio.
| Field | Type | Description |
|---|---|---|
call | Call | The updated call, see Call properties above. |
roomName | string | The audio room bridged to the WhatsApp call. |
token | string | An access token (JWT) for this agent. It only allows joining this room, to publish and hear audio. The participant identity is |
url | string | The audio server URL ( |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation answerCall($input: CallActionInput!) {
answerCall(input: $input) {
roomName
token
url
call {
id
convId
status
handler
assigneeId
answeredAt
}
}
}
input CallActionInput {
workspaceId: Int! # Workspace ID.
callId: ID! # Call ID.
}The mutation above returns JSON structured like this:
{
"data": {
"answerCall": {
"roomName": "call-call_123",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9pbiI6dHJ1ZX19.signature",
"url": "wss://media.example.com",
"call": {
"id": "call_123",
"convId": "conv_123",
"status": "ACTIVE",
"handler": "AGENT",
"assigneeId": "agent_123",
"answeredAt": "2026-10-17T09:30:08.000Z"
}
}
}
}The Bread Crumbs inbox uses url and token to join the call audio, play the client’s voice and turn on the agent’s microphone. The token only allows joining this call.
To finish, call Hang Up Call, then leave the call audio.
| Error | Cause |
|---|---|
Calls are not enabled for this workspace | Voice calls are not enabled for the workspace. |
Call does not exist | No call with this ID in the workspace. |
This call can no longer be answered | The call is not RINGING or ACTIVE (it ended, was missed, rejected or failed). |
You cannot answer a call assigned to another agent | The call is assigned to another agent and you are not Owner, Admin or Manager, or you have no agent profile in the workspace (always the case for API keys). |
Call is missing the WhatsApp SDP offer | The call can no longer be accepted on WhatsApp. |
WhatsApp channel is missing phone id or token | The WhatsApp Channel is not fully connected. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"answerCall","variables":{"input":{"workspaceId":12,"callId":"call_123"}},"query":"mutation answerCall($input: CallActionInput!) {\n answerCall(input: $input) {\n roomName\n token\n url\n call {\n id\n convId\n status\n handler\n assigneeId\n answeredAt\n }\n }\n}"}'Reject Call API
Decline a call. The call becomes REJECTED and a Voice call rejected note is added to the conversation.
If the WhatsApp call was already picked up (it has a roomName, for example a call handed over by the AI assistant), it is disconnected on WhatsApp. A ringing call that was never picked up is only marked as rejected in Bread Crumbs: nothing is sent to WhatsApp, so the client’s phone keeps ringing until the client hangs up or the call times out. The status is not checked first, so rejecting an ACTIVE call also marks it REJECTED; use Hang Up Call to end a call in progress. On a call that has already finished, the call is returned unchanged.
Access: Signed-in users only (portal session token). Owner, Admin and Manager can act on any call. Agent+ and Agent need an agent profile in the workspace and can act on calls assigned to them or unassigned. Workspace API keys and agent API keys are rejected with You cannot answer a call assigned to another agent, because the call is matched to the caller’s user account.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
callId | string | Required. The call ID, from List Active Calls or the conversation |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation rejectCall($input: CallActionInput!) {
rejectCall(input: $input) {
id
status
endedAt
}
}
input CallActionInput {
workspaceId: Int! # Workspace ID.
callId: ID! # Call ID.
}The mutation above returns JSON structured like this:
{
"data": {
"rejectCall": {
"id": "call_123",
"status": "REJECTED",
"endedAt": "2026-10-17T09:30:05.000Z"
}
}
}| Error | Cause |
|---|---|
Calls are not enabled for this workspace | Voice calls are not enabled for the workspace. |
Call does not exist | No call with this ID in the workspace. |
You cannot answer a call assigned to another agent | The call is assigned to another agent and you are not Owner, Admin or Manager, or you have no agent profile in the workspace (always the case for API keys). |
WhatsApp channel is missing phone id or token | The call has a room but the WhatsApp Channel is not fully connected, so it cannot be disconnected. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"rejectCall","variables":{"input":{"workspaceId":12,"callId":"call_123"}},"query":"mutation rejectCall($input: CallActionInput!) {\n rejectCall(input: $input) {\n id\n status\n endedAt\n }\n}"}'Hang Up Call API
End a call in progress. If the WhatsApp call was picked up (it has a roomName), it is disconnected on WhatsApp. The call becomes ENDED and a note such as Voice call answered by an agent is added to the conversation. duration stays null for calls ended this way. On a call that has already finished, the call is returned unchanged. Leave the call audio afterwards.
Access: Signed-in users only (portal session token). Owner, Admin and Manager can act on any call. Agent+ and Agent need an agent profile in the workspace and can act on calls assigned to them or unassigned. Workspace API keys and agent API keys are rejected with You cannot answer a call assigned to another agent, because the call is matched to the caller’s user account.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
callId | string | Required. The call ID, from List Active Calls or the conversation |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation hangupCall($input: CallActionInput!) {
hangupCall(input: $input) {
id
status
answeredAt
endedAt
duration
}
}
input CallActionInput {
workspaceId: Int! # Workspace ID.
callId: ID! # Call ID.
}The mutation above returns JSON structured like this:
{
"data": {
"hangupCall": {
"id": "call_123",
"status": "ENDED",
"answeredAt": "2026-10-17T09:30:08.000Z",
"endedAt": "2026-10-17T09:34:51.000Z",
"duration": null
}
}
}| Error | Cause |
|---|---|
Calls are not enabled for this workspace | Voice calls are not enabled for the workspace. |
Call does not exist | No call with this ID in the workspace. |
You cannot answer a call assigned to another agent | The call is assigned to another agent and you are not Owner, Admin or Manager, or you have no agent profile in the workspace (always the case for API keys). |
WhatsApp channel is missing phone id or token | The WhatsApp Channel is not fully connected, so the call cannot be disconnected. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"hangupCall","variables":{"input":{"workspaceId":12,"callId":"call_123"}},"query":"mutation hangupCall($input: CallActionInput!) {\n hangupCall(input: $input) {\n id\n status\n answeredAt\n endedAt\n duration\n }\n}"}'