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
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The channel ID. |
name | string | The channel name. |
identifier | string | Computed public display id for the channel (see table below). May be null on some legacy Instagram channels. |
type | IntegrationType | The channel type, it can be 'WHATSAPP', 'WA_GUPSHUP', 'FACEBOOK', 'INSTAGRAM', 'TELEGRAM', 'CUSTOM', or 'BCWEBCHAT'. |
createdAt | DateTime | The created timestamp. |
patchedAt | DateTime | The last updated timestamp. |
properties | json | Conversation routing settings only (see next section). Not page handles, avatars, or provider secrets. |
Identifier by channel type
| Channel | identifier value |
|---|---|
| WhatsApp / WA Gupshup | Business display phone number |
| Page name | |
| Page / account username | |
| Telegram | Bot username / display name |
| Custom | null — use name |
Properties vs IntegrationProperties
properties— public JSON for routing (assignees, handover, rating, etc.). Safe to read fromintegrations.integrationProperties— provider credentials and internal metadata. These are intentionally not exposed on the publicintegrationsquery. Do not rely on reading secrets over the API; useidentifier+name+typefor display.
Channel assignment properties (properties)
| Property | Type | Description |
|---|---|---|
startWith | StartWithType | The conversation assignment strategy. Possible values: AUTO, AI, AGENT, AI_BY_COUNTRY_CODE, AGENT_BY_COUNTRY_CODE. |
assigneeId | string | The default assignee ID used by assignment rules, it can be a live agent or an AI assistant. |
byCountryCodeConfig | json | Array of assignment rules by country code. |
byCountryCodeConfig[].code | string | The country code used in the routing rule. |
byCountryCodeConfig[].assigneeId | string | 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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Name filter. |
state | IntegrationState | State filter. |
type | IntegrationType | Type filter, it can be 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM' or 'CUSTOM'. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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"
}
]
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationProperties | json | Required. Provider-specific channel properties. |
name | string | Required. The name of the channel. |
type | string | Required. Channel type, it can be 'TELEGRAM' or 'CUSTOM'. |
integrationProperties by channel type
Telegram channel (type: TELEGRAM)
| Property | Type | Description |
|---|---|---|
accessToken | string | Required. Telegram bot token. |
Custom channel (type: CUSTOM)
| Property | Type | Description |
|---|---|---|
endpoint | string | Required. Custom channel endpoint URL. |
validateToken | string | Required. Verification token used for validating callbacks/webhooks. |
accessToken | string | Required. Access token used when communicating with the custom endpoint. |
externalId | string | Required. External identifier for the custom channel. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID. |
properties | JSON | Channel assignment properties (see Channel assignment properties). The object replaces the stored one, so include every key you want to keep. |
name | string | The name. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The channel ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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
}
]
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The channel ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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.
| Error | Cause |
|---|---|
Target integration is not found! | No channel with this ID in the workspace, or the channel was deleted. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID of the channel to delete. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Required. The ID of a |
templateId | string | Required. The template ID, as returned in |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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.
| Error | Cause |
|---|---|
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 Gupshup | The channel is not a WHATSAPP or WA_GUPSHUP channel. |
Template not found | The provider returned no template for templateId. |
Programming language examples
cURL
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 Channel Connect Link API
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:
- Call this mutation with the channel
type. It returns a secrettokenandexpiresAt. - Send the customer the connect page
https://app.bcrumbs.net/connect-channel/<token>. - The page calls the Get Channel Connect Link API to show the workspace name and who shared the link.
- 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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID the channel will be added to. |
type | IntegrationType | Required. The channel type the link can create: |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Channel connect links support WhatsApp, Facebook, and Instagram only | type is not WHATSAPP, FACEBOOK, or INSTAGRAM. |
Programming language examples
cURL
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}"}'Get Channel Connect Link API
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.
| Attribute | Type | Description |
|---|---|---|
token | string | Required. The token returned by the Create Channel Connect Link API. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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"
}
}
}| Error | Cause |
|---|---|
Link is invalid or expired | The token is empty or unknown, the link already created a channel, or the hour has passed. |
Programming language examples
cURL
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 Channel By Connect Link API
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.
| Attribute | Type | Description |
|---|---|---|
token | string | Required. The connect link token. |
name | string | Required. The display name of the new channel. Leading and trailing spaces are trimmed, and a blank name is rejected. |
integrationProperties | JSON | 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)
| Property | Type | Description |
|---|---|---|
accessToken | string | Required. The authorization code returned by Meta Embedded Signup. It is exchanged for a business token. |
phoneId | string | Required. The WhatsApp phone number ID. |
wabaId | string | Required. The WhatsApp Business Account ID. Bread Crumbs subscribes this account to its webhooks during setup. |
integrationProperties for Facebook (FACEBOOK)
| Property | Type | Description |
|---|---|---|
accessToken | string | Required. The Facebook user access token from Facebook Login. |
pageId | string | Required. The ID of the Facebook Page to connect. |
pageName | string | Optional. The Page name, used as the channel |
integrationProperties for Instagram (INSTAGRAM)
| Property | Type | Description |
|---|---|---|
accessToken | string | Required. The authorization code from Instagram login. |
redirectUri | string | Required. The redirect URI used in that login. It must match for the code exchange to succeed. |
pageName | string | Optional. The account name. Defaults to the name returned by Instagram. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}| Error | Cause |
|---|---|
Channel name is required | name is empty or only spaces. |
Link is invalid or expired | The token is empty or unknown, the link already created a channel, or the hour has passed. |
This link is already being used | Another request is creating a channel with the same link at the same time. |
WHATSAPP integration properties are invalid | A 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 exists | The number is already connected to an active channel in Bread Crumbs, in any workspace. For Facebook and Instagram the check uses pageId. |
Programming language examples
cURL
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}"}'