Custom Channel

Open in the app: Channels (opens in a new tab)

A Custom Channel lets you connect your own messaging system to Bread Crumbs (for example, a custom app, gateway, or provider).

Communication model

Channel messaging is asynchronous.

New customer messages are sent to Bread Crumbs as events
Outgoing replies are delivered back through async delivery flow, you will need to provide an endpoint to receive the replies.
Message status updates (pending, sent, failed, etc.) are handled asynchronously

This model is designed for real-world messaging systems where delivery is event-based and not immediate request/response.

Custom Channel Integration Properties

Attributes	Type	Description
`endpoint`	`string`	Your outgoing webhook URL where Bread Crumbs sends agent replies.
`validateToken`	`string`	Token used to authorize incoming requests from your system to Bread Crumbs.
`accessToken`	`string`	Token used by Bread Crumbs when calling your outgoing endpoint (sent as Bearer token by default).
`externalId`	`string`	Your channel sender identifier used as senderId in outgoing payloads.

Incoming: Send messages to Bread Crumbs

Use this endpoint to forward customer messages into Bread Crumbs:

POST https://gateway.bcrumbs.net/ext/v1/incoming/custom/:integrationId

Incoming authentication

You can provide the channel validateToken using one of these options:

x-validate-token header
x-validation-token header
Authorization: Bearer <validateToken> header

Incoming payload

Attributes	Type	Description
`content`	`string`	Required. Message content/body.
`type`	`string`	Required. The type of the message. One of: text, image, audio, video, document, location, interactive, template, contacts.
`senderId`	`string`	Required. External sender identifier from your system.
`receiptId`	`string`	Optional. External recipient identifier.
`messageId`	`string`	Optional. External message identifier. It's important later for status updates
`conversationId`	`string`	Optional. External conversation/thread identifier.
`clientInfo`	`object`	Optional. Client profile data (for example: name, surname, email, phone, or additional fields). This is optional and will be used to create a new client in Bread Crumbs if it doesn't exist.
`context`	`object`	Optional. Message reply context (`replyToId`, `replyToContent`, `replyToType`). This is optional and will be used to reply to a message in Bread Crumbs.
`createdAt`	`string`	Optional. ISO datetime for when the message was created.

Incoming request example

curl -X POST "https://gateway.bcrumbs.net/ext/v1/incoming/custom/<integrationId>" \
  -H "Content-Type: application/json" \
  -H "x-validate-token: <validateToken>" \
  -d '{
    "content": "Hello from my app",
    "type": "text",
    "senderId": "customer-123",
    "messageId": "msg-001",
    "conversationId": "conv-7788",
    "clientInfo": {
      "name": "John",
      "phone": "+201000000000"
    }
  }'

Successful requests return 200 status code.

Outgoing: Receive agent messages from Bread Crumbs

When an agent replies in Bread Crumbs, the platform sends a POST request to your configured channel endpoint. When creating a custom channel, you can configure the endpoint URL.

Outgoing auth headers

Bread Crumbs sends:

Authorization: Bearer <accessToken>

And you will need to validate the token using the accessToken you provided when creating the custom channel.

Outgoing payload shape

{
  "content": "Agent reply text",
  "type": "text",
  "senderId": "business-123",
  "receiptId": "customer-123",
  "conversationId": "conv-7788",
  "createdAt": "2026-03-08T10:00:00.000Z"
}

Outgoing response expected by Bread Crumbs

To map delivery IDs correctly, your endpoint should return:

{
  "externalMessageId": "msg-001"
}

messageId is also accepted as a fallback. If you return messageId, Bread Crumbs will use it as the external message ID.

Related pages in the app

Integrations Custom AI