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
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The conversation ID. |
integrationId | string | The integration (Channel) ID. |
integrationType | string | The integration type, it can be 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM' or 'CUSTOM'. |
clientId | string | The client ID. |
messages | json | An array of messages in the conversation. |
client | json | The client of the conversation, it will contain the client data coming with the conversation, it's explained in the next section. |
stageId | string | The conversation stage ID, stages in conversation are used to group conversations by a specific category. |
orderNo | string | The conversation order number, it can be used when there is an order, shipment, invoice, etc. related to the conversation. |
ended | boolean | Indicates whether the conversation is ended or still open. |
endedBy | string | The user ID or SYSTEM that ended the conversation. |
endedAt | DateTime | The ended timestamp. |
assigneeId | string | The current live agent assignee ID. |
aiId | string | The assigned AI ID, when applicable. |
aiAssigneed | boolean | Indicates whether the conversation is assigned to an AI. |
broadcastId | string | The broadcast ID linked to the conversation. |
broadcastName | string | The name of the broadcast linked to the conversation. |
tags | string[] | The conversation tags. |
externalConversationId | string | The external conversation ID. |
createdAt | DateTime | The created timestamp. |
Conversation client properties
| Property | Type | Description |
|---|---|---|
name | string | The name of the client. |
surname | string | The surname of the client. |
code | string | The code of the client. |
phone | string | The phone of the client. |
isDeleted | boolean | 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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | The integration (Channel) ID. |
clientId | string | The client ID. |
ended | boolean | Filter by open/ended conversations. |
tags | string[] | Filter by conversation tags. |
assigneeId | string | Filter by assignee ID. |
stageId | string | Filter by stage ID. |
nameOrPhone | string | Filter by name or phone. |
externalConversationId | string | Filter by external conversation ID. |
aiId | string | Filter by AI ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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
}
}
}
}Programming language examples
cURL
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..
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
clientId | string | The client ID. |
assigneeId | string | Assignee filter. |
tags | string[] | The tags. |
type | MessageType | Message type filter. |
startDate | DateTime | The start date. |
endDate | DateTime | The end date. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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
}
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The integration (Channel) ID. |
clientId | string | The client ID. |
phone | string | The client phone number. |
templateName | string | Required. The template name. |
templateLang | string | The template language. |
templateComponents | JSON | The template component variables. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The integration (Channel) ID. |
convId | string | Required. The conversation ID. |
agentId | string | The agent or AI ID. Omit it to unassign the conversation. |
isAi | boolean | Assign to AI when true. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in the workspace. |
Target agent does not exist | agentId isn’t an agent of the workspace, or the agent was deleted. |
This agent is already assigned to this conversation | The conversation is already assigned to agentId. |
You can only reassign conversations that are unassigned or assigned to you for your current role | The caller is an Agent or Agent+ (user or agent API key) and the conversation is assigned to another agent. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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).
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in the workspace. |
You cannot access this conversation for your current role assignment | The caller doesn’t have MANAGE_CONVS (or uses an agent API key) and the conversation is assigned to another agent. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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"
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
assigneeId | string | Only count conversations assigned to this agent. |
integrationId | string | Only count conversations on this integration (Channel). |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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
}
}| Error | Cause |
|---|---|
You cannot query conversations for other agents for your current role | A user without MANAGE_CONVS passed another agent’s assigneeId. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
integrationId | string | Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel. |
forceEndDespiteRating | boolean | When |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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):
endedbecomestrue,endedAtis set andendedByis 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_CONVwebhook fires, withcontent: "END"andtype: "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, theCONVERSATION_ASSIGNEDwebhook 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.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation matches convId and integrationId in 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":"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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
integrationId | string | Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel. |
orderNo | string | The order, shipment or invoice number linked to the conversation. An empty value is ignored, so this API can't clear it. |
stage | string | The stage name (not its ID). Send an empty string or |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Tags starting with "bc:" are reserved and cannot be created or applied | stage starts with the reserved bc: prefix. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | 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.
| Strategy | Type | How the agent is picked |
|---|---|---|
AUTO | StartWithType | Default. The client's default agent ( |
AGENT | StartWithType | 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_CODE | StartWithType | Like |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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_ASSIGNEDwebhook 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.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in the workspace. |
You cannot hand over an ended conversation | The conversation is already ended. |
No available agent to assign the conversation | The strategy found no agent, for example no assignable agent or an empty handover pool. |
This conversation is already assigned to this agent | The picked agent is already the conversation’s assignee. |
Unsupported handover assignment strategy | The Channel’s handover strategy is AI or AI_BY_COUNTRY_CODE. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
integrationId | string | 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.
| Property | Type | Description |
|---|---|---|
fromIntegrationId | string | The Channel ID before the switch. |
fromIntegrationType | IntegrationType | The Channel type before the switch. |
toIntegrationId | string | The Channel ID after the switch. |
toIntegrationType | IntegrationType | The Channel type after the switch. |
switchedAt | DateTime | When the switch happened. |
switchedBy | string | 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/gqmutation 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.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in the workspace. |
You cannot continue an ended conversation on another integration | The conversation is already ended. |
Target conversation is already on this integration | integrationId is the conversation’s current Channel. |
Target integration does not exist | No Channel with this integrationId in 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":"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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
integrationId | string | Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel. |
tag | string | Required. The tag to add. Tags starting with |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Tags starting with "bc:" are reserved and cannot be created or applied | The tag starts with the reserved bc: prefix. |
Target conversation does not exist | No conversation with this convId. |
Target conversation is already tagged with <tag> | The conversation already has this tag. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
integrationId | string | Required. The integration (Channel) ID of the conversation. It must be the conversation's current Channel. |
tag | string | Required. The tag to remove. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
]
}
}
}| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
rating | number | The rating, from 1 to 5. |
reason | FeedbackReason | The feedback reason: |
comment | string | A free-text comment from the client. |
sentiment | string | A free-text sentiment label, such as |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Rating must be between 1 and 5 | rating is outside 1 to 5. |
You do not have permission to access this resource with your current role assignment | The caller’s role is below Admin, or the caller uses an agent API key. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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:
textis the summary, up to 600 output tokens.usageis the token usage reported by the AI model (for exampleinputTokens,outputTokens,totalTokens). - If the AI service fails, the call is retried up to 3 times and then fails with
Internal server error.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in 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":"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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
currentMessage | string | Required. The reply draft being typed. Leading and trailing spaces are trimmed. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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.
textis empty andusageisnull, 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 asThanksorOK.textis 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,
textis empty instead of an error.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in 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":"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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
convId | string | Required. The conversation ID. |
currentMessage | string | Required. The reply draft to rewrite. Leading and trailing spaces are trimmed. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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,FRIENDLYorPLAYFUL; defaultFRIENDLY) and the wording followswritingReadingLevel(SIMPLE,STANDARDorTECHNICAL; defaultSTANDARD). 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.
usageis the token usage reported by the AI model. textis empty andusageisnullwhen the draft is empty.textis also empty if the AI model fails.
| Error | Cause |
|---|---|
Target conversation does not exist | No conversation with this convId in 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":"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}"}'