Skip to Content
API ReferenceConversations

Conversations APIs

Overview

Manage conversations, messages, and assignment. A conversation is a support thread that opens when a client sends a message, and ends when an agent or AI assistant has finished resolving or responding to that client.

ℹ️

Messaging window note
WhatsApp and Instagram have a default 24-hour messaging window for free-form replies after a client message.
For WhatsApp, if you need to send a message outside that 24-hour window, you must use an approved template message.

Conversation properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The conversation ID.

integrationIdstring

The integration (Channel) ID.

integrationTypestring

The integration type, it can be 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM' or 'CUSTOM'.

clientIdstring

The client ID.

messagesjson

An array of messages in the conversation.

clientjson

The client of the conversation, it will contain the client data coming with the conversation, it's explained in the next section.

stageIdstring

The conversation stage ID, stages in conversation are used to group conversations by a specific category.

orderNostring

The conversation order number, it can be used when there is an order, shipment, invoice, etc. related to the conversation.

endedboolean

Indicates whether the conversation is ended or still open.

endedBystring

The user ID or SYSTEM that ended the conversation.

endedAtDateTime

The ended timestamp.

assigneeIdstring

The current live agent assignee ID.

aiIdstring

The assigned AI ID, when applicable.

aiAssigneedboolean

Indicates whether the conversation is assigned to an AI.

broadcastIdstring

The broadcast ID linked to the conversation.

broadcastNamestring

The name of the broadcast linked to the conversation.

tagsstring[]

The conversation tags.

externalConversationIdstring

The external conversation ID.

createdAtDateTime

The created timestamp.

Conversation client properties

PropertyTypeDescription
namestring

The name of the client.

surnamestring

The surname of the client.

codestring

The code of the client.

phonestring

The phone of the client.

isDeletedboolean

Indicates whether the client is archived (soft-deleted).

List Conversations API

Get the list of conversations for a workspace. That list can be filtered by various criteria. Next are the available filters and their descriptions:

This endpoint supports pagination. See Pagination for more information.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

The integration (Channel) ID.

clientIdstring

The client ID.

endedboolean

Filter by open/ended conversations.

tagsstring[]

Filter by conversation tags.

assigneeIdstring

Filter by assignee ID.

stageIdstring

Filter by stage ID.

nameOrPhonestring

Filter by name or phone.

externalConversationIdstring

Filter by external conversation ID.

aiIdstring

Filter by AI ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convs($input: ConvsInput!) { convs(input: $input) { nodes { id integrationId clientId ended assigneeId createdAt } pageInfo { hasNextPage endCursor count } } } input ConvsInput { workspaceId: Int! # Workspace ID. integrationId: ID # Integration/channel ID. clientId: ID # Client ID filter. ended: Boolean # Filter by open/ended conversations. tags: [String!] # Tags filter. assigneeId: ID # Assignee filter. stageId: String # Stage filter. nameOrPhone: String # Name or phone filter. externalConversationId: String # External conversation ID filter. aiId: ID # AI filter. }

The query above returns JSON structured like this:

{ "data": { "convs": { "nodes": [ { "id": "conv_123", "integrationId": "integration_123", "clientId": "client_123", "ended": false, "assigneeId": "agent_123", "createdAt": "2026-03-16T10:15:00.000Z" } ], "pageInfo": { "hasNextPage": false, "endCursor": "2026-03-16T10:15:00.000Z", "count": 1 } } } }
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":"convs","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","ended":false,"tags":["vip"],"assigneeId":"agent_123","stageId":"stage_123","nameOrPhone":"Omar"}},"query":"query convs($input: ConvsInput!) {\n convs(input: $input) {\n nodes {\n id\n integrationId\n clientId\n ended\n assigneeId\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'

Messages API

Get the messages of a conversation.

This endpoint supports pagination. See Pagination for more information..

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

clientIdstring

The client ID.

assigneeIdstring

Assignee filter.

tagsstring[]

The tags.

typeMessageType

Message type filter.

startDateDateTime

The start date.

endDateDateTime

The end date.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query messages($input: MessagesInput!) { messages(input: $input) { nodes { messageId content type isAgent status createdAt } pageInfo { hasNextPage endCursor count } } } input MessagesInput { workspaceId: Int! # Workspace ID. clientId: ID # Client filter. assigneeId: ID # Assignee filter. tags: [String!] # Tags filter. type: MessageType # Message type filter. startDate: DateTime # Start date filter. endDate: DateTime # End date filter. }

The query above returns JSON structured like this:

{ "data": { "messages": { "nodes": [ { "messageId": "msg_123", "content": "Hi Omar, your order ORD-1042 has shipped.", "type": "text", "isAgent": true, "status": "sent", "createdAt": "2026-03-16T00:00:00.000Z" } ], "pageInfo": { "hasNextPage": false, "endCursor": "2026-03-16T10:15:00.000Z", "count": 1 } } } }
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":"messages","variables":{"input":{"workspaceId":12,"clientId":"client_123","type":"text","startDate":"2026-03-01T00:00:00.000Z","endDate":"2026-03-31T23:59:59.999Z"}},"query":"query messages($input: MessagesInput!) {\n messages(input: $input) {\n nodes {\n messageId\n content\n type\n isAgent\n status\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'

Start Conv API

Start a conversation.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The integration (Channel) ID.

clientIdstring

The client ID.

phonestring

The client phone number.

templateNamestring

Required. The template name.

templateLangstring

The template language.

templateComponentsJSON

The template component variables.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation startConv($input: ConvStartInput!) { startConv(input: $input) { id integrationId clientId ended createdAt assigneeId } } input ConvStartInput { workspaceId: Int! # Workspace ID. integrationId: ID! # Integration/channel ID. clientId: ID # Client ID. phone: String # Client phone number. templateName: String! # Template name. templateLang: String # Template language. templateComponents: JSON # Template component variables. }

The mutation above returns JSON structured like this:

{ "data": { "startConv": { "id": "conv_123", "integrationId": "integration_123", "clientId": "client_123", "ended": false, "createdAt": "2026-03-16T10:15:00.000Z", "assigneeId": null } } }
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":"startConv","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","phone":"12025550123","templateName":"order_update","templateLang":"en","templateComponents":[{"type":"body","parameters":[{"type":"text","text":"{{name}}"},{"type":"text","text":"ORD-1042"}]}]}},"query":"mutation startConv($input: ConvStartInput!) {\n startConv(input: $input) {\n id\n integrationId\n clientId\n ended\n createdAt\n assigneeId\n }\n}"}'

Assign Conv API

Assign a conversation to an agent or an AI, or unassign it (omit agentId).

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can assign or reassign any conversation. Agent and Agent+ users can assign a conversation that is unassigned or assigned to them to anyone: another agent, an AI, or nobody. A conversation handled by an AI counts as unassigned. They can’t reassign or take over a conversation assigned to another agent. Workspace API keys work on any conversation; agent API keys follow the rules of their role (Manager, Agent+ or Agent). See Workspace roles.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The integration (Channel) ID.

convIdstring

Required. The conversation ID.

agentIdstring

The agent or AI ID. Omit it to unassign the conversation.

isAiboolean

Assign to AI when true.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation assignConv($input: ConvAssignInput!) { assignConv(input: $input) { id assigneeId aiId aiAssigneed ended createdAt } } input ConvAssignInput { workspaceId: Int! # Workspace ID. integrationId: ID! # Integration/channel ID. convId: ID! # Conversation ID. agentId: ID # Agent to assign. isAi: Boolean # Assign to AI when true. }

The mutation above returns JSON structured like this:

{ "data": { "assignConv": { "id": "conv_123", "assigneeId": "agent_123", "aiId": null, "aiAssigneed": false, "ended": false, "createdAt": "2026-03-16T10:15:00.000Z" } } }
ErrorCause
Target conversation does not existNo conversation with this convId in the workspace.
Target agent does not existagentId isn’t an agent of the workspace, or the agent was deleted.
This agent is already assigned to this conversationThe conversation is already assigned to agentId.
You can only reassign conversations that are unassigned or assigned to you for your current roleThe caller is an Agent or Agent+ (user or agent API key) and the conversation is assigned to another agent.
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":"assignConv","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","agentId":"agent_123","isAi":false}},"query":"mutation assignConv($input: ConvAssignInput!) {\n assignConv(input: $input) {\n id\n assigneeId\n aiId\n aiAssigneed\n ended\n createdAt\n }\n}"}'

Get Conversation API

Get a single conversation by ID, with its client and all of its messages, oldest first. The messages include internal notes (type: note).

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can use it on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query conv($input: ConvInput!) { conv(input: $input) { id integrationId integrationType clientId client { name surname phone isDeleted } assigneeId aiAssigneed ended stageId orderNo tags ratingFlowInProgress createdAt messages { messageId content type isAgent createdAt } } } input ConvInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. }

The query above returns JSON structured like this:

{ "data": { "conv": { "id": "conv_123", "integrationId": "integration_123", "integrationType": "WHATSAPP", "clientId": "client_123", "client": { "name": "Sara", "surname": "Khalil", "phone": "+12025550123", "isDeleted": false }, "assigneeId": "agent_123", "aiAssigneed": false, "ended": false, "stageId": null, "orderNo": "ORD-1042", "tags": [ "vip" ], "ratingFlowInProgress": false, "createdAt": "2026-10-17T09:30:00.000Z", "messages": [ { "messageId": "msg_123", "content": "Hi, where is my order ORD-1042?", "type": "text", "isAgent": false, "createdAt": "2026-10-17T09:30:00.000Z" }, { "messageId": "msg_124", "content": "It shipped yesterday and should arrive in 2-3 days.", "type": "text", "isAgent": true, "createdAt": "2026-10-17T09:32:10.000Z" } ] } } }

ratingFlowInProgress is true while the Channel’s rating AI assistant is collecting feedback after the conversation was ended (see End Conversation API).

ErrorCause
Target conversation does not existNo conversation with this convId in the workspace.
You cannot access this conversation for your current role assignmentThe caller doesn’t have MANAGE_CONVS (or uses an agent API key) and the conversation is assigned to another agent.
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":"conv","variables":{"input":{"workspaceId":12,"convId":"conv_123"}},"query":"query conv($input: ConvInput!) {\n conv(input: $input) {\n id\n integrationId\n integrationType\n clientId\n client {\n name\n surname\n phone\n isDeleted\n }\n assigneeId\n aiAssigneed\n ended\n stageId\n orderNo\n tags\n ratingFlowInProgress\n createdAt\n messages {\n messageId\n content\n type\n isAgent\n createdAt\n }\n }\n}"}'

Get Last Message API

Get the most recent message of an open conversation. It can be a client message, an agent or AI reply, or an internal note. Returns null, not an error, when the conversation is ended or does not exist.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can use it on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convLastMessage($input: ConvLastMessageInput!) { convLastMessage(input: $input) { messageId content type isAgent status createdAt } } input ConvLastMessageInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. }

The query above returns JSON structured like this:

{ "data": { "convLastMessage": { "messageId": "msg_124", "content": "It shipped yesterday and should arrive in 2-3 days.", "type": "text", "isAgent": true, "status": "delivered", "createdAt": "2026-10-17T09:32:10.000Z" } } }
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":"convLastMessage","variables":{"input":{"workspaceId":12,"convId":"conv_123"}},"query":"query convLastMessage($input: ConvLastMessageInput!) {\n convLastMessage(input: $input) {\n messageId\n content\n type\n isAgent\n status\n createdAt\n }\n}"}'

Count Conversations Needing Response API

Count the open conversations that are waiting for a reply: those whose latest message, ignoring internal notes, is from the client. Replies from an AI assistant count as replies, and conversations without messages are not counted. Optionally filter by Channel or assignee.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can count any agent’s conversations; Agent and Agent+ users are limited to their own conversations plus unassigned ones. Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

assigneeIdstring

Only count conversations assigned to this agent.

integrationIdstring

Only count conversations on this integration (Channel).

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query openConversationsNeedResponseCount($input: OpenConversationsNeedResponseInput!) { openConversationsNeedResponseCount(input: $input) } input OpenConversationsNeedResponseInput { workspaceId: Int! # Workspace ID. assigneeId: ID # Assignee (agent) filter. integrationId: ID # Integration/channel filter. }

The query above returns JSON structured like this:

{ "data": { "openConversationsNeedResponseCount": 7 } }
ErrorCause
You cannot query conversations for other agents for your current roleA user without MANAGE_CONVS passed another agent’s assigneeId.
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":"openConversationsNeedResponseCount","variables":{"input":{"workspaceId":12,"integrationId":"integration_123"}},"query":"query openConversationsNeedResponseCount($input: OpenConversationsNeedResponseInput!) {\n openConversationsNeedResponseCount(input: $input)\n}"}'

End Conversation API

End a conversation. If the Channel has the post-conversation rating flow enabled and the client hasn’t given feedback yet, the conversation is not ended right away: it is handed to the Channel’s rating AI assistant, which asks the client for feedback on the channel. Pass forceEndDespiteRating: true to skip the rating flow and end the conversation immediately.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

integrationIdstring

Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel.

forceEndDespiteRatingboolean

When true, ends the conversation immediately even if the Channel's rating flow is enabled and no feedback was collected. Use it to close a conversation while the rating assistant is still waiting for feedback. Default false.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation endConv($input: ConvEndInput!) { endConv(input: $input) { id ended endedAt endedBy aiAssigneed aiId ratingFlowInProgress } } input ConvEndInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. integrationId: ID! # Integration/channel ID of the conversation. forceEndDespiteRating: Boolean # Skip the rating flow and end now. }

The mutation above returns JSON structured like this:

{ "data": { "endConv": { "id": "conv_123", "ended": true, "endedAt": "2026-10-17T10:05:00.000Z", "endedBy": "apikey_123", "aiAssigneed": false, "aiId": null, "ratingFlowInProgress": false } } }

When the conversation ends right away (rating flow disabled, feedback already recorded, or forceEndDespiteRating: true):

  • ended becomes true, endedAt is set and endedBy is the caller: the user ID for a portal session, the key ID for a workspace API key, or the linked agent ID for an agent API key.
  • The ENDING_CONV webhook fires, with content: "END" and type: "note" in the payload.
  • The agent, conversation, tag and stage reports are updated.
  • Nothing is sent to the client on the channel.

When the rating flow starts:

  • The conversation stays open (ended: false) and is assigned to the Channel’s rating AI assistant (aiAssigneed: true, ratingFlowInProgress: true). If it wasn’t already assigned to that assistant, the CONVERSATION_ASSIGNED webhook fires.
  • About one minute later the rating assistant sends a feedback request to the client on the channel. It is skipped if, by then, the conversation was ended, feedback was recorded, or the conversation was assigned to someone else.

Ending a conversation that is already ended is not rejected: endedAt and endedBy are overwritten and ENDING_CONV fires again, so check ended first.

ErrorCause
Target conversation does not existNo conversation matches convId and integrationId in 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":"endConv","variables":{"input":{"workspaceId":12,"convId":"conv_123","integrationId":"integration_123"}},"query":"mutation endConv($input: ConvEndInput!) {\n endConv(input: $input) {\n id\n ended\n endedAt\n endedBy\n aiAssigneed\n aiId\n ratingFlowInProgress\n }\n}"}'

Patch Conversation API

Set the stage or the order number of a conversation. A stage name that doesn’t exist yet is created as a conversation stage (a convStage tag) in the workspace. No webhook fires and nothing is sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

integrationIdstring

Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel.

orderNostring

The order, shipment or invoice number linked to the conversation. An empty value is ignored, so this API can't clear it.

stagestring

The stage name (not its ID). Send an empty string or null to remove the stage; leave it out to keep the current stage.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation patchConv($input: ConvPatchInput!) { patchConv(input: $input) { id stageId orderNo } } input ConvPatchInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. integrationId: ID! # Integration/channel ID of the conversation. orderNo: String # Order number. stage: String # Stage name; "" or null removes the stage. }

The mutation above returns JSON structured like this:

{ "data": { "patchConv": { "id": "conv_123", "stageId": "stage_123", "orderNo": "ORD-1042" } } }

stageId in the response is the ID of the stage tag; list stages with the Tags API (type convStage). The conversation is matched by convId, workspaceId and integrationId together, so the call fails if integrationId is not the conversation’s current Channel.

ErrorCause
Tags starting with "bc:" are reserved and cannot be created or appliedstage starts with the reserved bc: prefix.
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":"patchConv","variables":{"input":{"workspaceId":12,"convId":"conv_123","integrationId":"integration_123","stage":"Qualified","orderNo":"ORD-1042"}},"query":"mutation patchConv($input: ConvPatchInput!) {\n patchConv(input: $input) {\n id\n stageId\n orderNo\n }\n}"}'

Handover Conversation API

Hand a conversation over to a live agent picked by the Channel’s handover strategy, for example when an AI assistant is handling it. The AI assistant is removed (aiAssigneed: false), the picked agent becomes the assignee, and an entry is added to the assignment history (assignees).

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

Handover strategies

The strategy comes from the conversation’s Channel settings (handoverStartWith in the Channel properties) and defaults to AUTO. AI and AI_BY_COUNTRY_CODE are not supported for handover. An assignable agent is one whose assignable flag is not false.

StrategyTypeHow the agent is picked
AUTOStartWithType

Default. The client's default agent (defaultAgentId) if that agent still exists. Otherwise the assignable agent in the workspace with the fewest open conversations assigned, or a random assignable agent when no open conversation is assigned yet.

AGENTStartWithType

Picks from the Channel's handover agents. A single handover agent is always used; with several, the assignable one with the fewest open conversations assigned.

AGENT_BY_COUNTRY_CODEStartWithType

Like AGENT, but uses the handover agents of the first country code rule that matches the start of the client's phone number, falling back to the Channel's handover agents.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation handoverConv($input: ConvHandoverInput!) { handoverConv(input: $input) { id assigneeId aiAssigneed aiId assignees { assigneeId isAi assignDate } } } input ConvHandoverInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. }

The mutation above returns JSON structured like this:

{ "data": { "handoverConv": { "id": "conv_123", "assigneeId": "agent_123", "aiAssigneed": false, "aiId": null, "assignees": [ { "assigneeId": "ai_123", "isAi": true, "assignDate": "2026-10-17T09:30:00.000Z" }, { "assigneeId": "agent_123", "isAi": false, "assignDate": "2026-10-17T09:41:00.000Z" } ] } } }

Side effects:

  • The CONVERSATION_ASSIGNED webhook fires with the new assignee (agentId, isAi) and the previous one (previousAgentId, previousIsAi).
  • The picked agent gets a new-message notification.
  • If an AI assistant was handling the conversation and today is one of the workspace’s holiday weekdays, the workspace holiday message is sent to the client on the channel (at most once a day per client). Otherwise nothing is sent to the client.
ErrorCause
Target conversation does not existNo conversation with this convId in the workspace.
You cannot hand over an ended conversationThe conversation is already ended.
No available agent to assign the conversationThe strategy found no agent, for example no assignable agent or an empty handover pool.
This conversation is already assigned to this agentThe picked agent is already the conversation’s assignee.
Unsupported handover assignment strategyThe Channel’s handover strategy is AI or AI_BY_COUNTRY_CODE.
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":"handoverConv","variables":{"input":{"workspaceId":12,"convId":"conv_123"}},"query":"mutation handoverConv($input: ConvHandoverInput!) {\n handoverConv(input: $input) {\n id\n assigneeId\n aiAssigneed\n aiId\n assignees {\n assigneeId\n isAi\n assignDate\n }\n }\n}"}'

Continue Conversation On Channel API

Move an open conversation to another Channel of the workspace. The conversation keeps its ID, messages, assignee and tags; its integrationId and integrationType change to the target Channel, and the switch is appended to the conversation’s switch history (integrationSwitches). No webhook fires and nothing is sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

integrationIdstring

Required. The target integration (Channel) ID to continue the conversation on. It must differ from the current one.

Switch history properties

Each switch adds one entry to integrationSwitches, oldest first.

PropertyTypeDescription
fromIntegrationIdstring

The Channel ID before the switch.

fromIntegrationTypeIntegrationType

The Channel type before the switch.

toIntegrationIdstring

The Channel ID after the switch.

toIntegrationTypeIntegrationType

The Channel type after the switch.

switchedAtDateTime

When the switch happened.

switchedBystring

Who made the switch: the user ID for a portal session, the key ID for a workspace API key, or the linked agent ID for an agent API key.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation continueConvOn($input: ConvContinueOnInput!) { continueConvOn(input: $input) { id integrationId integrationType integrationSwitches { fromIntegrationId fromIntegrationType toIntegrationId toIntegrationType switchedAt switchedBy } } } input ConvContinueOnInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. integrationId: ID! # Target integration/channel ID. }

The mutation above returns JSON structured like this:

{ "data": { "continueConvOn": { "id": "conv_123", "integrationId": "integration_456", "integrationType": "WHATSAPP", "integrationSwitches": [ { "fromIntegrationId": "integration_123", "fromIntegrationType": "WHATSAPP", "toIntegrationId": "integration_456", "toIntegrationType": "WHATSAPP", "switchedAt": "2026-10-17T09:45:00.000Z", "switchedBy": "apikey_123" } ] } } }

After the switch, use the new integrationId in later calls: End, Patch, Tag and Untag Conversation match the conversation by its current Channel, and messages you send go out through the Channel you pass.

ErrorCause
Target conversation does not existNo conversation with this convId in the workspace.
You cannot continue an ended conversation on another integrationThe conversation is already ended.
Target conversation is already on this integrationintegrationId is the conversation’s current Channel.
Target integration does not existNo Channel with this integrationId in 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":"continueConvOn","variables":{"input":{"workspaceId":12,"convId":"conv_123","integrationId":"integration_456"}},"query":"mutation continueConvOn($input: ConvContinueOnInput!) {\n continueConvOn(input: $input) {\n id\n integrationId\n integrationType\n integrationSwitches {\n fromIntegrationId\n fromIntegrationType\n toIntegrationId\n toIntegrationType\n switchedAt\n switchedBy\n }\n }\n}"}'

Tag Conversation API

Add a tag to a conversation. A tag that doesn’t exist yet is also saved to the workspace’s conversation tags (type conversation, see Tags API). No webhook fires and nothing is sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

integrationIdstring

Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel.

tagstring

Required. The tag to add. Tags starting with bc: are reserved.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation tagConv($input: ConvTagInput!) { tagConv(input: $input) { id tags } } input ConvTagInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. integrationId: ID! # Integration/channel ID of the conversation. tag: String! # Tag to add. }

The mutation above returns JSON structured like this:

{ "data": { "tagConv": { "id": "conv_123", "tags": [ "new-lead", "vip" ] } } }

The tag is saved to the workspace tag list before the conversation is checked, so it stays in the list even when the call then fails.

ErrorCause
Tags starting with "bc:" are reserved and cannot be created or appliedThe tag starts with the reserved bc: prefix.
Target conversation does not existNo conversation with this convId.
Target conversation is already tagged with <tag>The conversation already has this tag.
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":"tagConv","variables":{"input":{"workspaceId":12,"convId":"conv_123","integrationId":"integration_123","tag":"vip"}},"query":"mutation tagConv($input: ConvTagInput!) {\n tagConv(input: $input) {\n id\n tags\n }\n}"}'

Untag Conversation API

Remove a tag from a conversation. Removing a tag the conversation doesn’t have is not an error: the conversation is returned unchanged. The tag stays in the workspace tag list, and reserved bc: tags such as bc:spam can be removed too. No webhook fires and nothing is sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

integrationIdstring

Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel.

tagstring

Required. The tag to remove.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation untagConv($input: ConvTagInput!) { untagConv(input: $input) { id tags } } input ConvTagInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. integrationId: ID! # Integration/channel ID of the conversation. tag: String! # Tag to remove. }

The mutation above returns JSON structured like this:

{ "data": { "untagConv": { "id": "conv_123", "tags": [ "vip" ] } } }
ErrorCause
Target conversation does not existNo conversation with this convId.
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":"untagConv","variables":{"input":{"workspaceId":12,"convId":"conv_123","integrationId":"integration_123","tag":"new-lead"}},"query":"mutation untagConv($input: ConvTagInput!) {\n untagConv(input: $input) {\n id\n tags\n }\n}"}'

Patch Conversation Feedback API

Record the client’s feedback on a conversation: rating, reason, comment and sentiment. It also marks the feedback as received, so End Conversation API no longer starts the Channel’s rating flow for this conversation and a pending rating request is not sent. It doesn’t end the conversation, and works on open and ended conversations. No webhook fires and nothing is sent to the client.

Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

ratingnumber

The rating, from 1 to 5.

reasonFeedbackReason

The feedback reason: resolved, not_resolved, fast_response, slow_response, friendly, bug, ux_issue or other.

commentstring

A free-text comment from the client.

sentimentstring

A free-text sentiment label, such as positive.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation patchConvFeedback($input: ConvFeedbackPatchInput!) { patchConvFeedback(input: $input) { id ratingFlowInProgress feedback { rating reason comment sentiment } } } input ConvFeedbackPatchInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. rating: Int # Rating from 1 to 5. reason: FeedbackReason # Feedback reason. comment: String # Free-text comment. sentiment: String # Free-text sentiment label. } enum FeedbackReason { bug fast_response friendly not_resolved other resolved slow_response ux_issue }

The mutation above returns JSON structured like this:

{ "data": { "patchConvFeedback": { "id": "conv_123", "ratingFlowInProgress": false, "feedback": { "rating": 5, "reason": "resolved", "comment": "Quick and helpful, thanks!", "sentiment": "positive" } } } }

The feedback object is replaced as a whole: fields you leave out are cleared, so send every field you want to keep. The rating is added to the conversation reports when the conversation ends, so feedback patched after the end doesn’t change existing reports.

ErrorCause
Rating must be between 1 and 5rating is outside 1 to 5.
You do not have permission to access this resource with your current role assignmentThe caller’s role is below Admin, or the caller uses an agent API key.
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":"patchConvFeedback","variables":{"input":{"workspaceId":12,"convId":"conv_123","rating":5,"reason":"resolved","comment":"Quick and helpful, thanks!","sentiment":"positive"}},"query":"mutation patchConvFeedback($input: ConvFeedbackPatchInput!) {\n patchConvFeedback(input: $input) {\n id\n ratingFlowInProgress\n feedback {\n rating\n reason\n comment\n sentiment\n }\n }\n}"}'

Conversation Summary API

Get an AI-generated summary of a conversation: key topics, decisions and follow-ups as short bullet points, written in the conversation’s language. The summary is generated on each call and is not stored; nothing is sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can use it on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convSummary($input: ConvAssistInput!) { convSummary(input: $input) { text usage } } input ConvAssistInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. }

The query above returns JSON structured like this:

{ "data": { "convSummary": { "text": "- The client asked where order ORD-1042 is.\n- The agent confirmed it shipped yesterday and should arrive in 2-3 days.\n- The client asked to be told if the delivery date changes.", "usage": { "inputTokens": 412, "outputTokens": 47, "totalTokens": 459 } } } }
  • Input: every text message of the conversation, oldest first, labeled as client or agent (AI replies count as agent). Media, template, interactive and internal note messages are left out.
  • Output: text is the summary, up to 600 output tokens. usage is the token usage reported by the AI model (for example inputTokens, outputTokens, totalTokens).
  • If the AI service fails, the call is retried up to 3 times and then fails with Internal server error.
ErrorCause
Target conversation does not existNo conversation with this convId in 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":"convSummary","variables":{"input":{"workspaceId":12,"convId":"conv_123"}},"query":"query convSummary($input: ConvAssistInput!) {\n convSummary(input: $input) {\n text\n usage\n }\n}"}'

Auto-Complete Message API

Get an AI suggestion that continues the reply an agent is typing. text is only the part to append to the draft (one line, up to 160 characters), not the full message. Nothing is stored or sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can use it on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

currentMessagestring

Required. The reply draft being typed. Leading and trailing spaces are trimmed.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convAutoComplete($input: ConvAutoCompleteInput!) { convAutoComplete(input: $input) { text usage } } input ConvAutoCompleteInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. currentMessage: String! # Reply draft being typed. }

The query above returns JSON structured like this:

{ "data": { "convAutoComplete": { "text": "within 2-3 business days.", "usage": { "inputTokens": 236, "outputTokens": 9, "totalTokens": 245 } } } }
  • Context: the last 10 text messages of the conversation (internal notes and media left out), then the draft.
  • text is empty and usage is null, with no AI call, when the draft is empty, ends with sentence punctuation (., !, ?, the Arabic Řź or their full-width forms), or is a short complete reply such as Thanks or OK.
  • text is trimmed, so add a space between the draft and the suggestion when needed.
  • If the AI model fails, or its answer isn’t a clean one-line continuation of 160 characters or less, text is empty instead of an error.
ErrorCause
Target conversation does not existNo conversation with this convId in 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":"convAutoComplete","variables":{"input":{"workspaceId":12,"convId":"conv_123","currentMessage":"Your order shipped yesterday and should arrive"}},"query":"query convAutoComplete($input: ConvAutoCompleteInput!) {\n convAutoComplete(input: $input) {\n text\n usage\n }\n}"}'

Enhance Message API

Get an AI rewrite of the reply an agent is typing: grammar, spelling, clearer wording and tone, in the same language and with the same meaning. text is the full rewritten message. Nothing is stored or sent to the client.

Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can use it on any conversation; Agent and Agent+ users only on conversations assigned to them or unassigned. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

convIdstring

Required. The conversation ID.

currentMessagestring

Required. The reply draft to rewrite. Leading and trailing spaces are trimmed.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convEnhanceMessage($input: ConvEnhanceMessageInput!) { convEnhanceMessage(input: $input) { text usage } } input ConvEnhanceMessageInput { workspaceId: Int! # Workspace ID. convId: ID! # Conversation ID. currentMessage: String! # Reply draft to rewrite. }

The query above returns JSON structured like this:

{ "data": { "convEnhanceMessage": { "text": "Hi! Your order shipped yesterday and will arrive in 2-3 days.", "usage": { "inputTokens": 845, "outputTokens": 17, "totalTokens": 862 } } } }
  • Writing settings: the tone follows the workspace writingBrandVoice (CONCISE, EMPATHETIC, ENTHUSIASTIC, FORMAL, FRIENDLY or PLAYFUL; default FRIENDLY) and the wording follows writingReadingLevel (SIMPLE, STANDARD or TECHNICAL; default STANDARD). Set them with the Patch Workspace Settings API.
  • Only the draft is rewritten. The AI is instructed not to add information, greetings or content from earlier messages, and not to translate.
  • The output is limited to 400 tokens. usage is the token usage reported by the AI model.
  • text is empty and usage is null when the draft is empty. text is also empty if the AI model fails.
ErrorCause
Target conversation does not existNo conversation with this convId in 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":"convEnhanceMessage","variables":{"input":{"workspaceId":12,"convId":"conv_123","currentMessage":"hi, ur order shipped yesterday, it will arrive in 2-3 days"}},"query":"query convEnhanceMessage($input: ConvEnhanceMessageInput!) {\n convEnhanceMessage(input: $input) {\n text\n usage\n }\n}"}'