Messaging

Overview

In this doc we will explain how you can add a message to a conversation using our API

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`	Note type for internal notes.
`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/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": "Hello world ....",
      "type": "text",
      "isAgent": true,
      "status": "pending",
      "externalMessageId": "15582e91-aeb8-4404-96f5-bb0e0bfcc2bc",
      "tags": ["tag1", "tag2"],
      "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":"id_123","convId":"id_123","content":"sample","type":"VALUE","noteType":"VALUE","replyToMessageId":"id_123"}},"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/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": "sample",
      "type": "template",
      "status": "sent",
      "externalMessageId": "wamid_123",
      "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":"sendNotification","variables":{"input":{"workspaceId":12,"integrationId":"id_123","clientId":"id_123","phone":"+12025550123","templateName":"sample","templateLang":"sample","templateComponents":{"key":"value"},"trunk":"sample","senderId":"sample"}},"query":"mutation sendNotification($input: SendNotificationInput!) {\\n  sendNotification(input: $input) {\\n    messageId\\n    content\\n    type\\n    status\\n    externalMessageId\\n    createdAt\\n  }\\n}"}'

Conversations Channels