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:
| Type | For | Inbound endpoint | Replies |
|---|---|---|---|
| Forms and leads | Website forms, lead tools, "call me back" boxes | …/submissions | To the customer by email |
| Two-way chat | Messaging inside your own app | …/messages | To 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
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).
| Field | Required | What happens |
|---|---|---|
id | no | Your record ID (up to 190 characters). Sending the same ID again does not open a new ticket — retry safely after a network error. |
form | no | The ticket subject (Quote form — Jane Doe). Defaults to the channel name. |
contact.name · email · phone | no | The 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 message | label + value (text, number, true/false or a list). Written into the ticket as Label: value lines; empty values are skipped. Up to 50 fields. |
message | yes, unless fields | Free text — its own paragraph after the fields. |
page_url | no | The page the form was sent from — shown on the ticket. |
utm | no | Campaign source (utm_source is stored as source). Up to 10 keys. |
deal | no | If present, a deal opens in the first stage of your sales pipeline. Give a title with {"title": "…"}; defaults to the ticket subject. |
Field names are a contract: an unknown field ("email" 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:
{
"conversation_id": "0193c4e2-…",
"duplicate": false,
"deal_id": null,
"deal_note": "pipeline_not_set_up"
}| Field | Meaning |
|---|---|
duplicate | true means this id was already processed; the same ticket is returned. |
deal_id | The deal that was opened (or had been opened before). |
deal_note | Why 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)
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_idis the person's ID in your system; the same person always lands in the same conversation (reopened if closed).message.idis 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 ownmessage.ids, or amessage.idwe 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:
{ "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:
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Blesyum-Event: message.created
X-Blesyum-Signature: t=1790000000,v1=5f3a9c…{
"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 {"id": "…"} 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 "<t>.<raw body>" with your signing secret. Reject t older than five minutes — that is a replayed request.
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
| Endpoint | What it does |
|---|---|
POST …/custom/<channel>/conversations/<conversation>/escalate | "I want to talk to a person" — hands over from the AI to your team. Already with a person: {"transferred": false, "reason": "already_human"}. |
POST …/custom/<channel>/conversations/<conversation>/csat | {"rating": 4, "remark": "…"} — satisfaction rating. 409 if CSAT is off or already rated. |
Errors
The body always has the same shape:
{ "type": "error.list", "errors": [{ "code": "parameter_invalid", "message": "Send at least one field or a message." }] }| Status | When |
|---|---|
400 parameter_invalid | Unreadable body, unknown field, empty submission, invalid email, a value over its limit (never silently truncated). |
401 unauthorized | Missing, wrong or rotated key. |
403 forbidden | Another 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_found | The channel doesn't exist or was removed. |
409 conflict | The channel is paused; /messages on a form channel or /submissions on a chat channel. |
429 rate_limit_exceeded | More than 300 requests a minute on the channel — retry after X-RateLimit-Reset seconds. |