Messaging
Overview
In this doc we will explain how you can add a message to a conversation using our GraphQL API.
For the Gateway-plan REST send endpoint (POST /core/v1/messages), see Send Message (REST). That endpoint is Gateway plan only.
Our platform allows you to manage a client conversation using API and webhooks. You can check the webhooks document to know how you can receive different events on webhooks.
To send a message to a client, you will need to use addMessage mutation with the following parameters:
| Attributes | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
integrationId | string | The integration (channel) ID. |
convId | string | The conversation ID. |
content | string | The content of the message, in the case of media messages, will contain the URL of the media file. |
type | string | The type of the message. Can be 'text', 'image', 'audio', 'document', 'video', 'location', 'interactive', 'template', 'contacts', or 'note'. |
noteType | NoteType | Only used when |
replyToMessageId | string | Message ID to reply to. |
The “Note” message is only used internally to follow up on specific events or notes during the conversations, so the note message type will not be sent to the client; it will just be appended to the conversation messages.
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation addMessage($input: MessageInput!) {
addMessage(input: $input) {
messageId
content
type
isAgent
status
externalMessageId
tags
createdAt
}
}
input MessageInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Integration/channel ID.
convId: ID! # Conversation ID.
content: String! # Message content.
type: MessageType! # Message type.
noteType: NoteType # Note type for internal notes.
replyToMessageId: ID # Message ID to reply to.
}We are returning the following structure in the response of adding a message to a conversation:
{
"data": {
"addMessage": {
"messageId": "msg_123",
"content": "Hi Omar, your order ORD-1042 has shipped.",
"type": "text",
"isAgent": true,
"status": "pending",
"externalMessageId": "15582e91-aeb8-4404-96f5-bb0e0bfcc2bc",
"tags": [],
"createdAt": "2026-03-16T00:00:00.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":"addMessage","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","content":"Hi Omar, your order ORD-1042 has shipped.","type":"text","replyToMessageId":"msg_120"}},"query":"mutation addMessage($input: MessageInput!) {\n addMessage(input: $input) {\n messageId\n content\n type\n isAgent\n status\n createdAt\n }\n}"}'Send Notification API
Send a notification to a client (also used for OTP messages).
| 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. Supports placeholders like {{name}} in string values. |
trunk | string | Provider trunk identifier. |
senderId | string | Sender identifier. |
Template Placeholders
When sending WhatsApp template messages (sendNotification), you can use placeholders inside any string value within templateComponents.
- Syntax:
{{fieldName}} - Allowed fields:
name,surname,fullName,email,phone,address,code,city,country - Missing values are replaced with an empty string.
- Unsupported placeholders are left unchanged.
Example:
{
"templateComponents": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Hello {{name}}, your city is {{city}}"
}
]
}
]
}Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation sendNotification($input: SendNotificationInput!) {
sendNotification(input: $input) {
messageId
content
type
status
externalMessageId
createdAt
}
}
input SendNotificationInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Integration/channel ID.
clientId: ID # Target client ID.
phone: String # Target phone number (if clientId omitted).
templateName: String! # Template name.
templateLang: String # Template language.
templateComponents: JSON # Template component variables.
trunk: String # Provider trunk identifier.
senderId: String # Sender identifier.
}The mutation above returns JSON structured like this:
{
"data": {
"sendNotification": {
"messageId": "msg_123",
"content": "{\"name\":\"order_update\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"Omar\"},{\"type\":\"text\",\"text\":\"ORD-1042\"}]}]}",
"type": "template",
"status": "pending",
"externalMessageId": null,
"createdAt": "2026-03-16T10:15:00.000Z"
}
}
}The mutation returns the message as soon as it is created, with status: pending and placeholders already filled in. externalMessageId and later statuses arrive asynchronously: subscribe to the MESSAGE_UPDATED webhook, or use the Send Notification And Wait API to wait for delivery.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"sendNotification","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 sendNotification($input: SendNotificationInput!) {\n sendNotification(input: $input) {\n messageId\n content\n type\n status\n externalMessageId\n createdAt\n }\n}"}'Send Notification And Wait API
Send a WhatsApp template notification to a client and keep the request open until the channel reports the message as delivered. It is useful when your next step depends on delivery, for example OTP codes.
It takes the same input as Send Notification and runs the same checks: WhatsApp Channels only, plan limits, client lookup (or creation from phone) and template placeholders. The difference is what happens after the template is handed to WhatsApp. sendNotification returns right away, while sendNotificationAndWait checks the message status once per second, for up to 15 seconds:
delivered,readorplayed: the mutation returns the message.failed: the mutation fails withMessage failed to be delivered.- Still
pendingorsentafter 15 seconds: the mutation fails withMessage did not reach delivered status within timeout period. Asentstatus is not enough.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The Channel ID. It must be a WhatsApp Channel (WhatsApp on Meta or WhatsApp on Gupshup). |
clientId | string | The client ID. Either |
phone | string | The client phone number, e.g. |
templateName | string | Required. The name of an approved WhatsApp template. |
templateLang | string | The template language code, e.g. |
templateComponents | JSON | The template components array in the WhatsApp Cloud API format. String values support placeholders like |
trunk | string | Provider trunk identifier, saved on the message. |
senderId | string | Sender identifier in the provider's system, saved on the message. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation sendNotificationAndWait($input: SendNotificationInput!) {
sendNotificationAndWait(input: $input) {
messageId
type
status
externalMessageId
createdAt
}
}
input SendNotificationInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # WhatsApp Channel ID.
clientId: ID # Target client ID (clientId or phone is required).
phone: String # Target phone number (if clientId is omitted).
templateName: String! # Approved template name.
templateLang: String # Template language, e.g. en or en_US.
templateComponents: JSON # Template components, supports {{fieldName}} placeholders.
trunk: String # Provider trunk identifier.
senderId: String # Sender identifier.
}The mutation above returns JSON structured like this:
{
"data": {
"sendNotificationAndWait": {
"messageId": "msg_123",
"type": "template",
"status": "pending",
"externalMessageId": null,
"createdAt": "2026-10-17T09:30:00.000Z"
}
}
}A successful response is the delivery confirmation. The message in the response is the record as it was created, before sending, so status reads pending and externalMessageId is null. To read the current values, use the Messages API or the MESSAGE_UPDATED webhook event.
The request can stay open for about 15 seconds plus the send time, so give your HTTP client a timeout of at least 30 seconds.
A timeout does not cancel anything. The template was already handed to WhatsApp, the message record is kept, and it can still be delivered later. Calling the mutation again sends a second template, so check the message status before you retry.
| Error | Cause |
|---|---|
Client Id or phone is missing | Neither clientId nor phone was sent. |
INSUFFICIENT_CREDITS: Buy more credits to continue sending. | Gateway plan: the workspace has no credits left. |
USAGE_LIMIT_REACHED: Conversation usage exceeded 120% of the plan limit for this period. | Inbox plan: the conversation usage limit is exceeded. |
Target integration does not exist | No Channel with this ID in the workspace, or it was deleted. |
Sending notifications is only supported for WhatsApp family of integrations: WhatsApp on Meta, WhatsApp on Gupshup | The Channel is not a WhatsApp Channel. |
Target client does not exist | clientId does not match a client in the workspace. |
| The provider’s error message | WhatsApp rejected the template (for example an unknown template name or language). The message is saved as failed with this reason and the mutation fails at once, without waiting. |
Message failed to be delivered | WhatsApp accepted the template, then reported the message as failed within the 15 seconds. |
Message did not reach delivered status within timeout period | No delivered, read or played status arrived within 15 seconds. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"sendNotificationAndWait","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","phone":"+12025550123","templateName":"otp_code","templateLang":"en","templateComponents":[{"type":"body","parameters":[{"type":"text","text":"482913"}]},{"type":"button","sub_type":"url","index":"0","parameters":[{"type":"text","text":"482913"}]}]}},"query":"mutation sendNotificationAndWait($input: SendNotificationInput!) {\n sendNotificationAndWait(input: $input) {\n messageId\n type\n status\n externalMessageId\n createdAt\n }\n}"}'Tag Message API
Add a tag to a message in a conversation. The tag is also saved to the workspace tag list as a message tag (see Tags), so it can be picked again later. Tags are internal: nothing is sent to the client.
Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on messages in any conversation; Agent and Agent+ users only in 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. |
integrationId | string | Required. The Channel ID of the conversation. |
convId | string | Required. The conversation ID. |
messageId | string | Required. The message ID ( |
tag | string | Required. The tag to add. Tags starting with |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation tagMessage($input: MessageTagInput!) {
tagMessage(input: $input) {
messageId
content
tags
}
}
input MessageTagInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Channel ID of the conversation.
convId: ID! # Conversation ID.
messageId: ID! # Message ID.
tag: String! # Tag to add or remove.
}The mutation above returns JSON structured like this:
{
"data": {
"tagMessage": {
"messageId": "msg_123",
"content": "My order arrived damaged",
"tags": [
"urgent",
"complaint"
]
}
}
}| Error | Cause |
|---|---|
Tags starting with "bc:" are reserved and cannot be created or applied | The tag starts with bc: (case-insensitive). |
Target message does not exist | No message with this ID in this conversation and workspace. |
Target message is already tagged with <tag> | The message 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":"tagMessage","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","messageId":"msg_123","tag":"complaint"}},"query":"mutation tagMessage($input: MessageTagInput!) {\n tagMessage(input: $input) {\n messageId\n content\n tags\n }\n}"}'Untag Message API
Remove a tag from a message. If the message does not have the tag, the call still succeeds and returns the message unchanged. The tag stays in the workspace tag list.
Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on messages in any conversation; Agent and Agent+ users only in 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. |
integrationId | string | Required. The Channel ID of the conversation. |
convId | string | Required. The conversation ID. |
messageId | string | Required. The message ID ( |
tag | string | Required. The tag to remove. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation untagMessage($input: MessageTagInput!) {
untagMessage(input: $input) {
messageId
tags
}
}
input MessageTagInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Channel ID of the conversation.
convId: ID! # Conversation ID.
messageId: ID! # Message ID.
tag: String! # Tag to add or remove.
}The mutation above returns JSON structured like this:
{
"data": {
"untagMessage": {
"messageId": "msg_123",
"tags": [
"urgent"
]
}
}
}| Error | Cause |
|---|---|
Target message does not exist | No message with this ID in this conversation and 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":"untagMessage","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","messageId":"msg_123","tag":"complaint"}},"query":"mutation untagMessage($input: MessageTagInput!) {\n untagMessage(input: $input) {\n messageId\n tags\n }\n}"}'React to Message API
React with an emoji to a message the client sent. The reaction is delivered to the client on the channel, where it shows on their message like any reaction from your business, and is then saved on the message. If the channel rejects it, nothing is saved.
A message holds one business reaction: reacting again replaces the previous one. The client’s own reaction (isAgent: false) is kept. The conversation must be open.
Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on messages in any conversation; Agent and Agent+ users only in conversations assigned to them or unassigned. A signed-in user also needs an agent profile. Works with workspace API keys (any conversation) and agent API keys (conversations assigned to the linked agent, plus unassigned ones). Reactions added with an API key have agentId: null.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The Channel ID of the conversation. The reaction is sent through this Channel. |
convId | string | Required. The conversation ID. |
messageId | string | Required. The ID of a message the client sent. |
emoji | string | Required. The emoji character, e.g. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation reactToMessage($input: MessageReactionInput!) {
reactToMessage(input: $input) {
messageId
reactions {
emoji
isAgent
agentId
createdAt
}
}
}
input MessageReactionInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Channel ID of the conversation.
convId: ID! # Conversation ID.
messageId: ID! # ID of the client message.
emoji: String! # Emoji character, e.g. "👍".
}The mutation above returns JSON structured like this:
{
"data": {
"reactToMessage": {
"messageId": "msg_123",
"reactions": [
{
"emoji": "❤️",
"isAgent": false,
"agentId": null,
"createdAt": "2026-10-17T09:28:12.000Z"
},
{
"emoji": "👍",
"isAgent": true,
"agentId": null,
"createdAt": "2026-10-17T09:30:00.000Z"
}
]
}
}
}Supported channels:
| Channel | Reactions |
|---|---|
| WhatsApp on Meta, WhatsApp on Gupshup | Supported. The emoji is sent as is. |
| Facebook Messenger, Instagram | Supported. The emoji is sent as is. |
| Telegram | Only the emoji in Telegram’s fixed reaction list. Others fail with Telegram does not support reacting with <emoji>. |
| Custom channels, web chat | Not supported: Reactions are not supported for integration type <type>. |
| Error | Cause |
|---|---|
Target message does not exist | No message with this ID in this conversation and workspace. |
Cannot react to a message that has no external message id | The message has no channel message ID, so the channel cannot find it. |
Cannot react to a message that was sent by an agent or a bot | Only messages sent by the client can get reactions. |
Target conversation does not exist | The conversation was not found. |
You cannot react on an ended conversation | The conversation is ended. |
You are not authorized to react on this conversation while you are not an agent | The signed-in user has no agent profile. |
Cannot deliver the reaction to the channel, the target message or client is not linked to an external id | The client has no channel ID. |
| The channel’s error message | The channel does not support reactions or rejected the emoji. Nothing is saved. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"reactToMessage","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","messageId":"msg_123","emoji":"👍"}},"query":"mutation reactToMessage($input: MessageReactionInput!) {\n reactToMessage(input: $input) {\n messageId\n reactions {\n emoji\n isAgent\n agentId\n createdAt\n }\n }\n}"}'Remove Message Reaction API
Remove your business reaction from a client’s message, on the channel and in Bread Crumbs. Every business reaction on the message is removed, whatever emoji you send. The client’s own reaction is kept. Supported channels and checks are the same as for React to Message.
Access: Any workspace role. Owner, Admin and Manager (MANAGE_CONVS) can act on messages in any conversation; Agent and Agent+ users only in conversations assigned to them or unassigned. A signed-in user also needs an agent profile. 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. |
integrationId | string | Required. The Channel ID of the conversation. The reaction is sent through this Channel. |
convId | string | Required. The conversation ID. |
messageId | string | Required. The ID of a message the client sent. |
emoji | string | Required. The emoji of the reaction to remove. It is not used to pick the reaction: the business reaction is removed whatever its emoji. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation unreactToMessage($input: MessageReactionInput!) {
unreactToMessage(input: $input) {
messageId
reactions {
emoji
isAgent
createdAt
}
}
}
input MessageReactionInput {
workspaceId: Int! # Workspace ID.
integrationId: ID! # Channel ID of the conversation.
convId: ID! # Conversation ID.
messageId: ID! # ID of the client message.
emoji: String! # Emoji character, e.g. "👍".
}The mutation above returns JSON structured like this:
{
"data": {
"unreactToMessage": {
"messageId": "msg_123",
"reactions": [
{
"emoji": "❤️",
"isAgent": false,
"createdAt": "2026-10-17T09:28:12.000Z"
}
]
}
}
}| Error | Cause |
|---|---|
Target message does not exist | No message with this ID in this conversation and workspace. |
Cannot react to a message that has no external message id | The message has no channel message ID, so the channel cannot find it. |
Cannot react to a message that was sent by an agent or a bot | Only messages sent by the client can get reactions. |
Target conversation does not exist | The conversation was not found. |
You cannot react on an ended conversation | The conversation is ended. |
You are not authorized to react on this conversation while you are not an agent | The signed-in user has no agent profile. |
Cannot deliver the reaction to the channel, the target message or client is not linked to an external id | The client has no channel ID. |
| The channel’s error message | The channel does not support reactions or rejected the emoji. Nothing is saved. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"unreactToMessage","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","convId":"conv_123","messageId":"msg_123","emoji":"👍"}},"query":"mutation unreactToMessage($input: MessageReactionInput!) {\n unreactToMessage(input: $input) {\n messageId\n reactions {\n emoji\n isAgent\n createdAt\n }\n }\n}"}'