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

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

The query above returns JSON structured like this:

{
  "data": {
    "convs": {
      "nodes": [
        {
          "id": "id_123",
          "integrationId": "id_123",
          "clientId": "id_123",
          "ended": false,
          "assigneeId": "id_123",
          "createdAt": "2026-03-16T00:00:00.000Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor_123",
        "count": 1
      }
    }
  }
}

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"convs","variables":{"input":{"workspaceId":12,"integrationId":"id_123","clientId":"id_123","ended":true,"tags":["sample"],"assigneeId":"id_123","stageId":"sample","nameOrPhone":"+12025550123","externalConversationId":"sample","aiId":"id_123"}},"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/gq

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

The query above returns JSON structured like this:

{
  "data": {
    "messages": {
      "nodes": [
        {
          "messageId": "msg_123",
          "content": "sample",
          "type": "text",
          "isAgent": true,
          "status": "sent",
          "createdAt": "2026-03-16T00:00:00.000Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor_123",
        "count": 1
      }
    }
  }
}

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"messages","variables":{"input":{"workspaceId":12,"clientId":"id_123","assigneeId":"id_123","tags":["sample"],"type":"VALUE","startDate":"2026-03-16T00:00:00.000Z","endDate":"2026-03-16T00:00:00.000Z"}},"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/gq

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

The mutation above returns JSON structured like this:

{
  "data": {
    "startConv": {
      "id": "id_123",
      "integrationId": "id_123",
      "clientId": "id_123",
      "ended": false,
      "createdAt": "2026-03-16T00:00:00.000Z",
      "assigneeId": null
    }
  }
}

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"startConv","variables":{"input":{"workspaceId":12,"integrationId":"id_123","clientId":"id_123","phone":"+12025550123","templateName":"sample","templateLang":"sample","templateComponents":{"key":"value"}}},"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.

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 ID.
`isAi`	`boolean`	Assign to AI when true.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

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

The mutation above returns JSON structured like this:

{
  "data": {
    "assignConv": {
      "id": "id_123",
      "assigneeId": "id_123",
      "aiId": null,
      "aiAssigneed": false,
      "ended": false,
      "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":"assignConv","variables":{"input":{"workspaceId":12,"integrationId":"id_123","convId":"id_123","agentId":"id_123","isAi":true}},"query":"mutation assignConv($input: ConvAssignInput!) {\\n  assignConv(input: $input) {\\n    id\\n    assigneeId\\n    aiId\\n    aiAssigneed\\n    ended\\n    createdAt\\n  }\\n}"}'

API Reference Messaging