Integration

Custom channel — connect your own software

Connect your website forms, lead tools or the chat inside your own app to the CRM through the API — channel key, submissions, messages and webhooks.

A custom channel is how you bring your own software into the CRM inbox. Anything without a ready-made integration comes in here: your website's quote form, a lead capture tool, the chat inside your mobile app, a kiosk.

There are two types; you pick one when you create the channel:

TypeForInbound endpointReplies
Forms and leadsWebsite forms, lead tools, "call me back" boxes…/submissionsTo the customer by email
Two-way chatMessaging inside your own app…/messagesTo your webhook address

Create the channel

CRM → Settings → Workspace → Channels → Custom channel → Set up connection

Choose the type and a name (plus a webhook address for chat). You get:

  • A channel key (bck_ prefix) — you call the inbound endpoints with it.
  • The inbound endpoint — on your workspace's CRM address.
  • For chat, a signing secret (bcs_ prefix) — you verify webhook requests with it.

The key and the secret are shown once; we only keep their hashes. If you lose the key, create a New channel key in the channel's details — the old one stops working immediately.

You don't need a separate API key from the core panel. The channel key only opens its own channel's endpoints: it cannot read your contacts or touch other conversations. You can also use an API key with the conversations.write scope instead (see Authentication).

Keep the key on your server — don't embed it in JavaScript that runs in the browser. Post your form to your own server and forward it to us. If the key leaks, the worst case is fake submissions in that one channel; rotate it in the panel.

Form submission

bash
curl -X POST 'https://<your-workspace>.crm.blesyum.app/api/crm/public/v1/channels/custom/<channel>/submissions' \
  -H 'Authorization: Bearer bck_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "lead-1001",
    "form": "Quote form",
    "contact": { "name": "Jane Doe", "email": "jane@example.com", "phone": "+905321112233" },
    "fields": [
      { "label": "Budget", "value": "10,000" },
      { "label": "Modules", "value": ["CRM", "ERP"] }
    ],
    "message": "Please call me on Monday.",
    "page_url": "https://example.com/quote",
    "utm": { "utm_source": "google" },
    "deal": {}
  }'

Copy the address from the panel: the channel screen gives the full URL (it carries your own domain if you connected one).

FieldRequiredWhat happens
idnoYour record ID (up to 190 characters). Sending the same ID again does not open a new ticket — retry safely after a network error.
formnoThe ticket subject (Quote form — Jane Doe). Defaults to the channel name.
contact.name · email · phonenoThe contact is matched or created by email, or by phone when there is no email. With neither, the ticket still opens without a contact.
fields[]yes, unless messagelabel + value (text, number, true/false or a list). Written into the ticket as Label: value lines; empty values are skipped. Up to 50 fields.
messageyes, unless fieldsFree text — its own paragraph after the fields.
page_urlnoThe page the form was sent from — shown on the ticket.
utmnoCampaign source (utm_source is stored as source). Up to 10 keys.
dealnoIf present, a deal opens in the first stage of your sales pipeline. Give a title with {&quot;title&quot;: &quot;…&quot;}; defaults to the ticket subject.

Field names are a contract: an unknown field (&quot;email&quot; at the root instead of under contact) is not silently ignored, it gets a 400.

Response

A new ticket returns 201; the same id again returns 200:

json
{
  "conversation_id": "0193c4e2-…",
  "duplicate": false,
  "deal_id": null,
  "deal_note": "pipeline_not_set_up"
}
FieldMeaning
duplicatetrue means this id was already processed; the same ticket is returned.
deal_idThe deal that was opened (or had been opened before).
deal_noteWhy no deal was opened. pipeline_not_set_up: the workspace has no open pipeline (every CRM comes with a sales pipeline set up; this note only appears when all pipelines are archived) — reopen one in CRM → Deals → ⋯ → Pipeline settings. Then sending the same id again opens the deal without a second ticket.

The ticket lands in the inbox on the Web form channel; the agent's reply goes to the customer by email. The channel shows "Connected" once the first submission arrives.

Chat message (two-way)

bash
curl -X POST 'https://<your-workspace>.crm.blesyum.app/api/crm/public/v1/channels/custom/<channel>/messages' \
  -H 'Authorization: Bearer bck_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": { "external_id": "user-42", "name": "Jane Doe", "email": "jane@example.com" },
    "message": { "id": "msg-1", "body": "Hello, where is my order?" },
    "attachments": [{ "url": "https://cdn.example.com/invoice.pdf", "name": "invoice.pdf" }]
  }'
  • contact.external_id is the person's ID in your system; the same person always lands in the same conversation (reopened if closed).
  • message.id is the duplicate guard: the same ID is never written twice.
  • message.reply_to (optional): if the customer replied to / quoted a message, that message's ID — one of your own message.ids, or a message.id we sent you in a webhook (or the ID you returned for it). The panel shows it as a quote above the message; if the ID is not found the message is still written (shown as "earlier message").
  • Attachment URLs must be publicly reachable (internal network addresses are rejected); we download and store the file (up to 25 MB, 10 attachments).

Response 201:

json
{ "conversation_id": "0193c4e2-…", "message_id": "0193c4e3-…", "new_conversation": true, "duplicate": false }

Replies go to your webhook

When an agent (or the AI) replies, a signed POST arrives at your address:

http
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Blesyum-Event: message.created
X-Blesyum-Signature: t=1790000000,v1=5f3a9c…
json
{
  "event": "message.created",
  "channel_id": "cc_…",
  "conversation_id": "0193c4e2-…",
  "contact": { "external_id": "user-42" },
  "message": {
    "id": "0193c4e4-…",
    "author": { "type": "agent", "name": "Agent Can" },
    "text": "It's shipped and arrives tomorrow.",
    "html": "<p>It's shipped and arrives <b>tomorrow</b>.</p>",
    "attachments": [],
    "reply_to": "msg-1"
  },
  "sent_at": "2026-10-03T12:00:00Z"
}

If you don't answer 2xx, the agent sees the reply as "not delivered". Return {&quot;id&quot;: &quot;…&quot;} in your response body and we store that ID.

message.reply_to: when the agent answers by quoting a message with "Reply", the ID of that message as YOU know it (your message.id for the customer's message; for ours, the ID we sent in the webhook or the one you returned); null when there is no quote. Use it to show the reply attached to that message in your own UI.

Closing, reopening and AI-to-human handoff arrive at the same address as events: conversation.closed · conversation.reopened · conversation.handed_off. They are delivered from a queue and retried with exponential backoff for a few hours.

Verify the signature

v1 is the HMAC-SHA256 (hex) of &quot;&lt;t&gt;.&lt;raw body&gt;&quot; with your signing secret. Reject t older than five minutes — that is a replayed request.

ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function signatureValid(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(parts.v1 ?? ""));
  return a.length === b.length && timingSafeEqual(a, b);
}

Two actions from your customer's interface

EndpointWhat it does
POST …/custom/&lt;channel&gt;/conversations/&lt;conversation&gt;/escalate"I want to talk to a person" — hands over from the AI to your team. Already with a person: {&quot;transferred&quot;: false, &quot;reason&quot;: &quot;already_human&quot;}.
POST …/custom/&lt;channel&gt;/conversations/&lt;conversation&gt;/csat{&quot;rating&quot;: 4, &quot;remark&quot;: &quot;…&quot;} — satisfaction rating. 409 if CSAT is off or already rated.

Errors

The body always has the same shape:

json
{ "type": "error.list", "errors": [{ "code": "parameter_invalid", "message": "Send at least one field or a message." }] }
StatusWhen
400 parameter_invalidUnreadable body, unknown field, empty submission, invalid email, a value over its limit (never silently truncated).
401 unauthorizedMissing, wrong or rotated key.
403 forbiddenAnother channel's key; a channel key on an endpoint outside its channel; an API key without the scope; the workspace's CRM subscription is off.
404 not_foundThe channel doesn't exist or was removed.
409 conflictThe channel is paused; /messages on a form channel or /submissions on a chat channel.
429 rate_limit_exceededMore than 300 requests a minute on the channel — retry after X-RateLimit-Reset seconds.