Skip to Content

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

  1. The client calls your WhatsApp number. A call with status RINGING is created on the client’s open conversation (a conversation is opened if needed). While the call rings or is in progress, the conversation’s activeCall field returns it.
  2. If the conversation is assigned to an AI assistant, the AI answers right away: the call becomes ACTIVE with handler: 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 to RINGING with handler: AGENT, and the conversation is handed over to an agent.
  3. Otherwise, if the conversation has an assigned agent, that agent gets an Incoming voice call push 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 becomes MISSED.
  4. 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 call or Voice call answered by an agent - 2m 5s.

Call properties

PropertyTypeDescription
idstring

The call ID.

workspaceIdnumber

The workspace ID.

integrationIdstring

The WhatsApp Channel ID that received the call.

convIdstring

The conversation the call belongs to.

clientIdstring

The client on the call.

statusCallStatus

RINGING: waiting to be answered. CONNECTING: counted as an active call. ACTIVE: answered and in progress. ENDED: the call finished after it was answered, or was hung up with hangupCall. MISSED: nobody answered before the ring timeout, or the client hung up first. REJECTED: rejected with rejectCall. FAILED: the AI assistant could not pick up the call.

handlerCallHandler

Who handles the call: AI (an AI assistant) or AGENT (a human agent).

directionCallDirection

USER_INITIATED when the client called your business, BUSINESS_INITIATED for a call started by the business.

roomNamestring

The audio room bridged to the WhatsApp call, call- followed by the call ID. Null until the call is picked up by an agent or an AI assistant.

startedAtDateTime

When the call reached Bread Crumbs.

answeredAtDateTime

When an agent or an AI assistant answered. Null for calls that were never answered.

endedAtDateTime

When the call ended.

durationnumber

Call length in seconds, as reported by WhatsApp when the call ends on the client's side. Null for calls ended from Bread Crumbs.

assigneeIdstring

The agent the call is assigned to. Copied from the conversation assignee when the call arrives, then set to the agent who answers.

aiIdstring

The AI assistant handling the call, when handler is AI.

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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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" } ] } }
ErrorCause
Calls are not enabled for this workspaceVoice calls are not enabled for the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

callIdstring

Required. The call ID, from List Active Calls or the conversation activeCall field.

CallJoinPayload fields

The response holds the updated call and the credentials this agent uses to join the call audio.

FieldTypeDescription
callCall

The updated call, see Call properties above.

roomNamestring

The audio room bridged to the WhatsApp call.

tokenstring

An access token (JWT) for this agent. It only allows joining this room, to publish and hear audio. The participant identity is agent: followed by the user ID, and the display name is the agent's name.

urlstring

The audio server URL (wss://...) to connect to with the token.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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.

ErrorCause
Calls are not enabled for this workspaceVoice calls are not enabled for the workspace.
Call does not existNo call with this ID in the workspace.
This call can no longer be answeredThe call is not RINGING or ACTIVE (it ended, was missed, rejected or failed).
You cannot answer a call assigned to another agentThe 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 offerThe call can no longer be accepted on WhatsApp.
WhatsApp channel is missing phone id or tokenThe WhatsApp Channel is not fully connected.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

callIdstring

Required. The call ID, from List Active Calls or the conversation activeCall field.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
ErrorCause
Calls are not enabled for this workspaceVoice calls are not enabled for the workspace.
Call does not existNo call with this ID in the workspace.
You cannot answer a call assigned to another agentThe 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 tokenThe call has a room but the WhatsApp Channel is not fully connected, so it cannot be disconnected.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

callIdstring

Required. The call ID, from List Active Calls or the conversation activeCall field.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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 } } }
ErrorCause
Calls are not enabled for this workspaceVoice calls are not enabled for the workspace.
Call does not existNo call with this ID in the workspace.
You cannot answer a call assigned to another agentThe 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 tokenThe WhatsApp Channel is not fully connected, so the call cannot be disconnected.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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}"}'