Skip to Content
API ReferenceMessaging

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:

AttributesTypeDescription
workspaceIdnumber

The workspace ID.

integrationIdstring

The integration (channel) ID.

convIdstring

The conversation ID.

contentstring

The content of the message, in the case of media messages, will contain the URL of the media file.

typestring

The type of the message. Can be 'text', 'image', 'audio', 'document', 'video', 'location', 'interactive', 'template', 'contacts', or 'note'.

noteTypeNoteType

Only used when type is 'note'. Use 'MEMO' for a manual note; the other values are used by automatic notes.

replyToMessageIdstring

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/gq
mutation 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:

response.json
{ "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" } } }
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":"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).

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. Supports placeholders like {{name}} in string values.

trunkstring

Provider trunk identifier.

senderIdstring

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/gq
mutation 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.

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":"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, read or played: the mutation returns the message.
  • failed: the mutation fails with Message failed to be delivered.
  • Still pending or sent after 15 seconds: the mutation fails with Message did not reach delivered status within timeout period. A sent status is not enough.

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The Channel ID. It must be a WhatsApp Channel (WhatsApp on Meta or WhatsApp on Gupshup).

clientIdstring

The client ID. Either clientId or phone is required.

phonestring

The client phone number, e.g. +12025550123. Used when clientId is omitted. Spaces, dashes, brackets and a leading + or 00 are removed. If no client has this phone, a new client is created and the NEW_CLIENT webhook event fires.

templateNamestring

Required. The name of an approved WhatsApp template.

templateLangstring

The template language code, e.g. en or en_US.

templateComponentsJSON

The template components array in the WhatsApp Cloud API format. String values support placeholders like {{name}}, see Template Placeholders.

trunkstring

Provider trunk identifier, saved on the message.

senderIdstring

Sender identifier in the provider's system, saved on the message.

Request & Response

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

ErrorCause
Client Id or phone is missingNeither 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 existNo 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 GupshupThe Channel is not a WhatsApp Channel.
Target client does not existclientId does not match a client in the workspace.
The provider’s error messageWhatsApp 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 deliveredWhatsApp accepted the template, then reported the message as failed within the 15 seconds.
Message did not reach delivered status within timeout periodNo delivered, read or played status arrived within 15 seconds.
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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The Channel ID of the conversation.

convIdstring

Required. The conversation ID.

messageIdstring

Required. The message ID (messageId in the Messages API).

tagstring

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

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" ] } } }
ErrorCause
Tags starting with "bc:" are reserved and cannot be created or appliedThe tag starts with bc: (case-insensitive).
Target message does not existNo message with this ID in this conversation and workspace.
Target message is already tagged with <tag>The message 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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The Channel ID of the conversation.

convIdstring

Required. The conversation ID.

messageIdstring

Required. The message ID (messageId in the Messages API).

tagstring

Required. The tag to remove.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" ] } } }
ErrorCause
Target message does not existNo message with this ID in this conversation and 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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The Channel ID of the conversation. The reaction is sent through this Channel.

convIdstring

Required. The conversation ID.

messageIdstring

Required. The ID of a message the client sent.

emojistring

Required. The emoji character, e.g. 👍.

Request & Response

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

ChannelReactions
WhatsApp on Meta, WhatsApp on GupshupSupported. The emoji is sent as is.
Facebook Messenger, InstagramSupported. The emoji is sent as is.
TelegramOnly the emoji in Telegram’s fixed reaction list. Others fail with Telegram does not support reacting with <emoji>.
Custom channels, web chatNot supported: Reactions are not supported for integration type <type>.
ErrorCause
Target message does not existNo message with this ID in this conversation and workspace.
Cannot react to a message that has no external message idThe 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 botOnly messages sent by the client can get reactions.
Target conversation does not existThe conversation was not found.
You cannot react on an ended conversationThe conversation is ended.
You are not authorized to react on this conversation while you are not an agentThe 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 idThe client has no channel ID.
The channel’s error messageThe channel does not support reactions or rejected the emoji. Nothing is saved.
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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The Channel ID of the conversation. The reaction is sent through this Channel.

convIdstring

Required. The conversation ID.

messageIdstring

Required. The ID of a message the client sent.

emojistring

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/gq
mutation 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" } ] } } }
ErrorCause
Target message does not existNo message with this ID in this conversation and workspace.
Cannot react to a message that has no external message idThe 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 botOnly messages sent by the client can get reactions.
Target conversation does not existThe conversation was not found.
You cannot react on an ended conversationThe conversation is ended.
You are not authorized to react on this conversation while you are not an agentThe 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 idThe client has no channel ID.
The channel’s error messageThe channel does not support reactions or rejected the emoji. Nothing is saved.
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":"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}"}'