Skip to Content

Channel APIs

Overview

Manage channels (integrations) in a workspace. Channels are the integrations that connect Bread Crumbs with external messaging providers. Each channel has its own setup flow and integration properties, you can setup a new channel in the Channels page.

ℹ️

Most of the channels require to be created from the Channels page visually while it needs some steps to be completed from the provider’s website. For now you can only use the API to create Telegram and Custom Channel.

Channel properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The channel ID.

namestring

The channel name.

identifierstring

Computed public display id for the channel (see table below). May be null on some legacy Instagram channels.

typeIntegrationType

The channel type, it can be 'WHATSAPP', 'WA_GUPSHUP', 'FACEBOOK', 'INSTAGRAM', 'TELEGRAM', 'CUSTOM', or 'BCWEBCHAT'.

createdAtDateTime

The created timestamp.

patchedAtDateTime

The last updated timestamp.

propertiesjson

Conversation routing settings only (see next section). Not page handles, avatars, or provider secrets.

Identifier by channel type

Channelidentifier value
WhatsApp / WA GupshupBusiness display phone number
FacebookPage name
InstagramPage / account username
TelegramBot username / display name
Customnull — use name

Properties vs IntegrationProperties

  • properties — public JSON for routing (assignees, handover, rating, etc.). Safe to read from integrations.
  • integrationProperties — provider credentials and internal metadata. These are intentionally not exposed on the public integrations query. Do not rely on reading secrets over the API; use identifier + name + type for display.

Channel assignment properties (properties)

PropertyTypeDescription
startWithStartWithType

The conversation assignment strategy. Possible values: AUTO, AI, AGENT, AI_BY_COUNTRY_CODE, AGENT_BY_COUNTRY_CODE.

assigneeIdstring

The default assignee ID used by assignment rules, it can be a live agent or an AI assistant.

byCountryCodeConfigjson

Array of assignment rules by country code.

byCountryCodeConfig[].codestring

The country code used in the routing rule.

byCountryCodeConfig[].assigneeIdstring

The assignee ID for that country code rule, it can be a live agent or AI assistant.

List Channels API

List the channels in a workspace. Next are the available filters to list the channels.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Name filter.

stateIntegrationState

State filter.

typeIntegrationType

Type filter, it can be 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM' or 'CUSTOM'.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query integrations($input: IntegrationsInput!) { integrations(input: $input) { nodes { id name type state identifier createdAt } } } input IntegrationsInput { workspaceId: Int! # Workspace ID. name: String # Name filter. state: IntegrationState # State filter. type: IntegrationType # Type filter. }

The query above returns JSON structured like this:

{ "data": { "integrations": { "nodes": [ { "id": "integration_123", "name": "Support WhatsApp", "type": "WHATSAPP", "state": "ACTIVE", "identifier": "+1 202-555-0123", "createdAt": "2026-03-16T10:15: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":"integrations","variables":{"input":{"workspaceId":12,"name":"Support","state":"ACTIVE","type":"WHATSAPP"}},"query":"query integrations($input: IntegrationsInput!) {\n integrations(input: $input) {\n nodes {\n id\n name\n type\n state\n identifier\n createdAt\n }\n }\n}"}'

Create Channel API

Create a channel. You can only create Telegram and Custom Channel through the API.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationPropertiesjson

Required. Provider-specific channel properties.

namestring

Required. The name of the channel.

typestring

Required. Channel type, it can be 'TELEGRAM' or 'CUSTOM'.

integrationProperties by channel type

Telegram channel (type: TELEGRAM)

PropertyTypeDescription
accessTokenstring

Required. Telegram bot token.

Custom channel (type: CUSTOM)

PropertyTypeDescription
endpointstring

Required. Custom channel endpoint URL.

validateTokenstring

Required. Verification token used for validating callbacks/webhooks.

accessTokenstring

Required. Access token used when communicating with the custom endpoint.

externalIdstring

Required. External identifier for the custom channel.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation createIntegration($input: IntegrationCreateInput!) { createIntegration(input: $input) { id name type state identifier createdAt } } input IntegrationCreateInput { workspaceId: Int! # Workspace ID. integrationProperties: JSON! # Provider-specific channel properties. name: String! # Channel name. type: IntegrationType! # Channel type. }

The mutation above returns JSON structured like this:

{ "data": { "createIntegration": { "id": "integration_124", "name": "Support bot", "type": "TELEGRAM", "state": "ACTIVE", "identifier": "acme_support_bot", "createdAt": "2026-03-16T10:15: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":"createIntegration","variables":{"input":{"workspaceId":12,"integrationProperties":{"accessToken":"123456789:AAExampleBotTokenFromBotFather"},"name":"Support bot","type":"TELEGRAM"}},"query":"mutation createIntegration($input: IntegrationCreateInput!) {\n createIntegration(input: $input) {\n id\n name\n type\n state\n identifier\n createdAt\n }\n}"}'

Patch Channel API

Patch a channel. You should have the MANAGE_WORKSPACE permission to patch a channel.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The ID.

propertiesJSON

Channel assignment properties (see Channel assignment properties). The object replaces the stored one, so include every key you want to keep. callingEnabled is kept when omitted.

namestring

The name.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation patchIntegration($input: IntegrationPatchInput!) { patchIntegration(input: $input) { id name type state identifier patchedAt } } input IntegrationPatchInput { workspaceId: Int! # Workspace ID. id: ID! # Channel ID. properties: JSON # Channel assignment properties; replaces the stored object. name: String # New channel name. }

The mutation above returns JSON structured like this:

{ "data": { "patchIntegration": { "id": "integration_123", "name": "Support WhatsApp", "type": "WHATSAPP", "state": "ACTIVE", "identifier": "+1 202-555-0123", "patchedAt": "2026-03-16T10:15: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":"patchIntegration","variables":{"input":{"workspaceId":12,"id":"integration_123","properties":{"startWith":"AGENT","assigneeId":"agent_123"},"name":"Support WhatsApp"}},"query":"mutation patchIntegration($input: IntegrationPatchInput!) {\n patchIntegration(input: $input) {\n id\n name\n type\n state\n identifier\n patchedAt\n }\n}"}'

Waba Message Templates API

Get the WhatsApp message templates for a channel.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The channel ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query wabaMessageTemplates($input: WabaMessageTemplatesInput!) { wabaMessageTemplates(input: $input) { nodes { id name language status category library_template_name } } } input WabaMessageTemplatesInput { workspaceId: Int! # Workspace ID. integrationId: ID! # WhatsApp channel ID. }

The query above returns JSON structured like this:

{ "data": { "wabaMessageTemplates": { "nodes": [ { "id": "1234567890123456", "name": "order_update", "language": "en_US", "status": "APPROVED", "category": "UTILITY", "library_template_name": 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":"wabaMessageTemplates","variables":{"input":{"workspaceId":12,"integrationId":"integration_123"}},"query":"query wabaMessageTemplates($input: WabaMessageTemplatesInput!) {\n wabaMessageTemplates(input: $input) {\n nodes {\n id\n name\n language\n status\n category\n library_template_name\n }\n }\n}"}'

Get Channel API

Get one channel by its ID. The response includes the routing properties and the computed identifier, never the provider credentials (integrationProperties). Deleted channels are not returned.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+, Agent). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The channel ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query integration($input: IntegrationInput!) { integration(input: $input) { id name type state identifier callingEnabled properties createdAt patchedAt } } input IntegrationInput { workspaceId: Int! # Workspace ID. id: ID! # Channel ID. }

The query above returns JSON structured like this:

{ "data": { "integration": { "id": "integration_123", "name": "Sales WhatsApp", "type": "WHATSAPP", "state": "ACTIVE", "identifier": "+1 202-555-0123", "callingEnabled": false, "properties": { "startWith": "AUTO" }, "createdAt": "2026-09-02T08:15:00.000Z", "patchedAt": "2026-10-17T09:30:00.000Z" } } }

callingEnabled is true only when WhatsApp voice calling was turned on for the channel.

ErrorCause
Target integration is not found!No channel with this ID in the workspace, or the channel was deleted.
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":"integration","variables":{"input":{"workspaceId":12,"id":"integration_123"}},"query":"query integration($input: IntegrationInput!) {\n integration(input: $input) {\n id\n name\n type\n state\n identifier\n callingEnabled\n properties\n createdAt\n patchedAt\n }\n}"}'

Delete Channel API

Delete a channel. The channel is soft-deleted: state becomes DELETED, deletedAt is set, and it no longer appears in List Channels or Get Channel.

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The ID of the channel to delete.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation deleteIntegration($input: IntegrationDeleteInput!) { deleteIntegration(input: $input) { id name type state deletedAt } } input IntegrationDeleteInput { workspaceId: Int! # Workspace ID. id: ID! # Channel ID. }

The mutation above returns JSON structured like this:

{ "data": { "deleteIntegration": { "id": "integration_123", "name": "Sales WhatsApp", "type": "WHATSAPP", "state": "DELETED", "deletedAt": "2026-10-17T09:30:00.000Z" } } }

What happens after deletion:

  • Conversations and messages on the channel are kept. They are not ended or deleted.
  • Incoming messages for the channel are no longer added to conversations, and starting a conversation or sending a template on it fails with Target integration does not exist.
  • Nothing is disconnected on the provider side. Bread Crumbs does not unsubscribe the WhatsApp Business Account from webhooks, remove the Telegram bot webhook, or revoke tokens. Do that in the provider’s console if the provider should stop sending events.
  • The same phone number, Page, or bot can be connected again later, because the duplicate check ignores deleted channels. The API has no way to restore a deleted channel.

Deleting a channel that is already deleted succeeds again and refreshes deletedAt. An ID that does not exist in the workspace returns an error.

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":"deleteIntegration","variables":{"input":{"workspaceId":12,"id":"integration_123"}},"query":"mutation deleteIntegration($input: IntegrationDeleteInput!) {\n deleteIntegration(input: $input) {\n id\n name\n type\n state\n deletedAt\n }\n}"}'

Waba Message Template Details API

Get one WhatsApp message template with its components (header, body, footer, and buttons). Use it after the Waba Message Templates API to see which variables a template expects before you send it with templateComponents. The template is read live from Meta for WHATSAPP channels and from Gupshup for WA_GUPSHUP channels.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+, Agent). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Required. The ID of a WHATSAPP or WA_GUPSHUP channel.

templateIdstring

Required. The template ID, as returned in id by the Waba Message Templates API.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query wabaMessageTemplateDetails($input: WabaMessageTemplateDetailsInput!) { wabaMessageTemplateDetails(input: $input) { id name language status category parameter_format components } } input WabaMessageTemplateDetailsInput { workspaceId: Int! # Workspace ID. integrationId: ID! # WhatsApp channel ID. templateId: String! # Template ID from the Waba Message Templates API. }

The query above returns JSON structured like this:

{ "data": { "wabaMessageTemplateDetails": { "id": "1234567890123456", "name": "order_shipped", "language": "en_US", "status": "APPROVED", "category": "UTILITY", "parameter_format": "POSITIONAL", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Order update" }, { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped.", "example": { "body_text": [ [ "Sara", "#10432" ] ] } }, { "type": "FOOTER", "text": "Reply STOP to opt out" }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Track order", "url": "https://example.com/track/{{1}}", "example": [ "https://example.com/track/10432" ] } ] } ] } } }

For WA_GUPSHUP channels, library_template_name and parameter_format are always null, and components is built from the Gupshup template.

ErrorCause
Target integration is not found!No channel with this ID in the workspace, or the channel was deleted.
Getting Waba template details is only supported for WhatsApp family of integrations: WhatsApp on Meta, WhatsApp on GupshupThe channel is not a WHATSAPP or WA_GUPSHUP channel.
Template not foundThe provider returned no template for templateId.
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":"wabaMessageTemplateDetails","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","templateId":"1234567890123456"}},"query":"query wabaMessageTemplateDetails($input: WabaMessageTemplateDetailsInput!) {\n wabaMessageTemplateDetails(input: $input) {\n id\n name\n language\n status\n category\n parameter_format\n components\n }\n}"}'

Create a single-use link that lets someone outside your workspace, usually your customer, connect their own WhatsApp, Facebook, or Instagram channel to your workspace without a Bread Crumbs login. Use it when the customer owns the Meta business assets and you do not want to give them access to your workspace.

How the connect link flow works:

  1. Call this mutation with the channel type. It returns a secret token and expiresAt.
  2. Send the customer the connect page https://app.bcrumbs.net/connect-channel/<token>.
  3. The page calls the Get Channel Connect Link API to show the workspace name and who shared the link.
  4. The customer signs in with the provider on that page (Meta Embedded Signup for WhatsApp, Facebook Login, or Instagram login). The page then calls the Create Channel By Connect Link API, the channel is added to your workspace, and the link stops working.

A link is valid for one hour and creates one channel. The token is returned only in this response, and only its hash is stored, so a lost token cannot be recovered. Create a new link instead. Creating a new link does not cancel earlier ones, and there is no API to revoke a link before it expires.

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID the channel will be added to.

typeIntegrationType

Required. The channel type the link can create: WHATSAPP, FACEBOOK, or INSTAGRAM. Other types are rejected.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation createChannelConnectLink($input: CreateChannelConnectLinkInput!) { createChannelConnectLink(input: $input) { token expiresAt } } input CreateChannelConnectLinkInput { workspaceId: Int! # Workspace ID. type: IntegrationType! # WHATSAPP, FACEBOOK or INSTAGRAM. }

The mutation above returns JSON structured like this:

{ "data": { "createChannelConnectLink": { "token": "Xk3vQ9mL2pR7sT1wY5zA8cE4gJ6nB0dF2hK9uM3qW7e", "expiresAt": "2026-10-17T10:30:00.000Z" } } }

The link remembers who created it. When it is created with a workspace API key, the connect page shows the key label as the sharer, and workspaceName and sharedByEmail are empty strings.

ErrorCause
Channel connect links support WhatsApp, Facebook, and Instagram onlytype is not WHATSAPP, FACEBOOK, or INSTAGRAM.
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":"createChannelConnectLink","variables":{"input":{"workspaceId":12,"type":"WHATSAPP"}},"query":"mutation createChannelConnectLink($input: CreateChannelConnectLinkInput!) {\n createChannelConnectLink(input: $input) {\n token\n expiresAt\n }\n}"}'

Read a channel connect link: the channel type, the workspace it connects to, who shared it, and when it expires. Reading a link does not use it up. The connect page calls this first so the customer can confirm where the channel will be added.

Access: No login required. The input has no workspaceId because the token identifies the workspace, and any Authorization header is ignored.

AttributeTypeDescription
tokenstring

Required. The token returned by the Create Channel Connect Link API.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query channelConnectLink($input: ChannelConnectLinkInput!) { channelConnectLink(input: $input) { type workspaceName sharedByName sharedByEmail expiresAt } } input ChannelConnectLinkInput { token: String! # Connect link token. }

The query above returns JSON structured like this:

{ "data": { "channelConnectLink": { "type": "WHATSAPP", "workspaceName": "Acme Support", "sharedByName": "Sara Haddad", "sharedByEmail": "[email protected]", "expiresAt": "2026-10-17T10:30:00.000Z" } } }
ErrorCause
Link is invalid or expiredThe token is empty or unknown, the link already created a channel, or the hour has passed.
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":"channelConnectLink","variables":{"input":{"token":"Xk3vQ9mL2pR7sT1wY5zA8cE4gJ6nB0dF2hK9uM3qW7e"}},"query":"query channelConnectLink($input: ChannelConnectLinkInput!) {\n channelConnectLink(input: $input) {\n type\n workspaceName\n sharedByName\n sharedByEmail\n expiresAt\n }\n}"}'

Create the channel from a connect link. The workspace and channel type come from the link, so the input has only the token, a channel name, and the provider properties collected during sign-in. On success the link is used up and the new channel is returned. If creation fails, the link stays valid until it expires, so the customer can try again. The connect page at https://app.bcrumbs.net/connect-channel/<token> calls this after the customer finishes the provider sign-in.

Access: No login required. The input has no workspaceId because the token identifies the workspace, and any Authorization header is ignored.

AttributeTypeDescription
tokenstring

Required. The connect link token.

namestring

Required. The display name of the new channel. Leading and trailing spaces are trimmed, and a blank name is rejected.

integrationPropertiesJSON

Required. Provider properties from the sign-in. The required keys depend on the link's channel type, see the tables below.

integrationProperties for WhatsApp (WHATSAPP)

PropertyTypeDescription
accessTokenstring

Required. The authorization code returned by Meta Embedded Signup. It is exchanged for a business token.

phoneIdstring

Required. The WhatsApp phone number ID.

wabaIdstring

Required. The WhatsApp Business Account ID. Bread Crumbs subscribes this account to its webhooks during setup.

integrationProperties for Facebook (FACEBOOK)

PropertyTypeDescription
accessTokenstring

Required. The Facebook user access token from Facebook Login.

pageIdstring

Required. The ID of the Facebook Page to connect.

pageNamestring

Optional. The Page name, used as the channel identifier.

integrationProperties for Instagram (INSTAGRAM)

PropertyTypeDescription
accessTokenstring

Required. The authorization code from Instagram login.

redirectUristring

Required. The redirect URI used in that login. It must match for the code exchange to succeed.

pageNamestring

Optional. The account name. Defaults to the name returned by Instagram.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation createIntegrationByConnectLink($input: CreateIntegrationByConnectLinkInput!) { createIntegrationByConnectLink(input: $input) { id workspaceId name type state identifier createdAt } } input CreateIntegrationByConnectLinkInput { token: String! # Connect link token. name: String! # Channel name. integrationProperties: JSON! # Provider properties from the sign-in. }

The mutation above returns JSON structured like this:

{ "data": { "createIntegrationByConnectLink": { "id": "integration_123", "workspaceId": 12, "name": "Acme WhatsApp", "type": "WHATSAPP", "state": "ACTIVE", "identifier": "+1 202-555-0123", "createdAt": "2026-10-17T09:42:00.000Z" } } }
ErrorCause
Channel name is requiredname is empty or only spaces.
Link is invalid or expiredThe token is empty or unknown, the link already created a channel, or the hour has passed.
This link is already being usedAnother request is creating a channel with the same link at the same time.
WHATSAPP integration properties are invalidA required key is missing from integrationProperties. The message names the link’s channel type.
Failed to generate token for WHATSAPP integration, please try again or contact us.The provider rejected the code or token, for example because it expired or was already used. The message names the channel type.
WHATSAPP integration with the same phoneId already existsThe number is already connected to an active channel in Bread Crumbs, in any workspace. For Facebook and Instagram the check uses pageId.
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":"createIntegrationByConnectLink","variables":{"input":{"token":"Xk3vQ9mL2pR7sT1wY5zA8cE4gJ6nB0dF2hK9uM3qW7e","name":"Acme WhatsApp","integrationProperties":{"accessToken":"AQD4x7Rk2mN9pQ1sV5wZ8bC3eG6hJ0kL","phoneId":"109876543210987","wabaId":"102345678901234"}}},"query":"mutation createIntegrationByConnectLink($input: CreateIntegrationByConnectLinkInput!) {\n createIntegrationByConnectLink(input: $input) {\n id\n workspaceId\n name\n type\n state\n identifier\n createdAt\n }\n}"}'