Conversations / Message channelsAll pages
Conversations

Message channels

WhatsApp and any other messaging provider, next to your calls. Messages arrive in Conversations with photos, voice notes and documents; anyone in the organization can reply, assign the thread, call the person back or link it to a support ticket.

Channel types
WhatsApp · Generic bridge
Files
Up to 10 MB each
Stored on
Your server only
Event
message.received

How it fits together

A channel is one connection to a messaging provider: a WhatsApp Business number, or a generic bridge to anything else (an SMS gateway, a Telegram bot, a chat widget). Each channel gets its own secret inbound URL. Every message that arrives lands in a conversation: one thread per channel and sender number, shown in Conversations next to calls and tickets.

Your serverHTTPSJSONeventWhatsAppMeta Cloud APIYour bridgeSMS, chat, botsChannels/api/channels/…Database + mediaThreads · filesConversationsReply · assignTicketsLink a threadYour systemsWebhooks
Providers post into a channel's inbound URL; replies go back out through the same channel.
WhoCan do
AdminAdd, edit, test, switch off and remove channels; reveal a bridge's signing secret (Integrations → Channels). Every one of these actions is written to the audit trail.
Everyone in the organizationRead every conversation, reply with text or a file, assign a thread, close and reopen it, call the person back, save the sender as a contact, link the thread to a ticket.

WhatsApp (Meta Cloud API)

You need a WhatsApp Business number on Meta's Cloud API. The dashboard talks to the Graph API (graph.facebook.com/v21.0) with your token, and Meta calls your server for every incoming message and delivery status. Setup takes about fifteen minutes.

  1. Create the Meta app

    In Meta for Developers create an app of type Business and add the WhatsApp product.

  2. Collect the phone number ID and a permanent token

    Under WhatsApp → API setup note the Phone number ID (digits only). Create a system user with the whatsapp_business_messaging and whatsapp_business_management permissions and generate a permanent access token.

  3. Add the channel in the dashboard

    Open Integrations → Channels → Add channel, choose WhatsApp (Meta Cloud API), give it a name (for example WhatsApp · Card services) and paste the phone number ID and the token. Optionally paste the app's App secret (App settings → Basic): with it, every delivery from Meta is signature-checked.

  4. Point Meta's webhook at your server

    Open the channel again with Edit. It shows the Callback URL and a Verify token that the dashboard generated. Paste both into WhatsApp → Configuration → Webhook in Meta Then subscribe to the messages field.

    Callback URLText
    https://<your-domain>/api/channels/whatsapp/<channel token>
  5. Test

    Press Test on the channel row. The dashboard asks the Graph API for the number and shows Connected: <verified name> <number>, or Meta's own error message if the token or ID is wrong. Then send a WhatsApp message to the number: it appears in Conversations within seconds.

The verification handshake

When you save the webhook, Meta sends a GET to the callback URL. The dashboard answers with Meta's challenge only if the mode is subscribe and the verify token matches the channel's; anything else gets 403. A token that belongs to no WhatsApp channel gets 404.

Meta → your serverHTTP
1GET /api/channels/whatsapp/<channel token>?hub.mode=subscribe&hub.verify_token=<verify token>&hub.challenge=11582014442 3HTTP/1.1 200 OK4 51158201444

What happens when a message arrives

Meta sends message notifications as JSON with an X-Hub-Signature-256 header. Photos, voice notes and documents are not in the body: Meta sends a media id, and the dashboard downloads the file itself with your token. Here a customer sends a photo of a receipt with a caption.

CustomerCustomerMeta Cloud APIMeta Cloud APIDashboardDashboardYour webhookYour webhookPhoto + caption"Here is my receipt"1POST /api/channels/whatsapp/<token>X-Hub-Signature-2562Token → channel and organization; body ≤ 1 MB; signature checked with the App secretGET /v21.0/<media id>Bearer <access token>4{ url }5GET <url>https only, public address6image/jpeg bytesallowed type, ≤ 10 MB7File saved; thread found or opened; contact matched; message stored once per Meta idmessage.receivedqueued, sent by the worker9200 { ok: true }10
An inbound WhatsApp photo: the file is fetched from Meta and stored on your server before the thread updates.
  • Always 200. Once the token and signature are accepted, the dashboard answers 200 even if processing a message fails (the error goes to the server log), because Meta retries anything else. A switched-off channel also gets 200, and the message is dropped.
  • Rejected deliveries: unknown token 404, body over 1 MB 413, bad or missing signature (when an App secret is set) 401, invalid JSON 400.
  • Duplicates are ignored: a message is stored once per Meta message id, so a retried delivery does not create a second copy or a second webhook event.
  • Delivery statuses (sent, delivered, read, failed) from Meta update the status of the reply they belong to.
  • Sender name comes from the WhatsApp profile Meta includes; a matching contact in your organization takes precedence (see Who is writing).

Message types

WhatsApp sendsShown in the thread as
TextText.
Image, stickerPhoto, with its caption as text.
Voice note, audioVoice message with a player.
Video, documentA file to open or download, with the document's file name and caption.
LocationText: the place name and a maps.google.com link to the coordinates.
Anything elseStored with the type other, so the thread still shows that something arrived.

Replying

Replies are written in the conversation. Enter sends, Shift+Enter starts a new line. Text is limited to 4,000 characters. The paperclip sends a file up to 10 MB with the typed text as its caption:

FileTypesOn WhatsApp it arrives as
PhotoJPG, PNGA photo, with caption
Other imagesWebP, GIFA document, with caption and file name
Voice noteMP3, OGG, M4A, AAC, AMRAudio. WhatsApp shows no caption on audio, so the text is sent as a separate message right after it.
VideoMP4A video, with caption
DocumentPDFA document, with caption and file name

If WhatsApp refuses a text reply, nothing is stored and Meta's error is shown to the person who sent it. A refused file, and any reply a bridge refuses, stays in the thread with the status failed. Every file sent is recorded in the audit trail (message.media_sent).

What the dashboard sends to Meta

A text reply is one call to the Graph API. The number is sent without the leading +.

Text replyHTTP
1POST https://graph.facebook.com/v21.0/<phone number id>/messages2Authorization: Bearer <access token>3Content-Type: application/json4 5{ "messaging_product": "whatsapp", "to": "923001234567", "type": "text", "text": { "body": "Your card is active again." } }

A file takes two calls: the file is uploaded to /<phone number id>/media first, then a message points at the media id Meta returned.

Second call: the message that carries the uploaded fileJSON
1{2  "messaging_product": "whatsapp",3  "to": "923001234567",4  "type": "document",5  "document": { "id": "<media id>", "caption": "Your statement", "filename": "statement.pdf" }6}

Any other provider (generic bridge)

Add a channel of type Generic bridge (webhook). You get an inbound URL for messages coming in, and you give an outbound URL where replies are posted. A small script between your provider and these two URLs is all a bridge needs.

  1. Add the channel

    Integrations → Channels → Add channel, type Generic bridge (webhook), a name (for example SMS gateway) and the outbound URL, for example https://bridge.yourcompany.com/voip9/send. The URL can also be added later.

  2. Copy the inbound URL and the signing secret

    Open the channel with Edit. Copy the Inbound URL into your bridge, and press Show next to Signing secret to read the secret your bridge uses to check replies. Revealing the secret is written to the audit trail (channel.secret_viewed).

  3. Test both directions

    Test posts a signed ping event to the outbound URL and reports the status code your bridge answered. Then post a message into the inbound URL (see below, or use scripts/channel-test.sh).

Inbound: your bridge → dashboard

POST/api/channels/webhook/<channel token>

One message per request. The token in the URL is the channel's secret; keep it out of logs and tickets.

JSON body

fromstringrequired
The person's number, or your provider's user id. Letters, digits and + @ . - _; at most 64 characters. All messages with the same from on this channel share one thread.Example: +923001234567
namestring
Display name, up to 120 characters. A matching contact in the organization takes precedence.Example: Ali Khan
textstring
Message text, up to 4,000 characters. Required unless media_url is given.Example: My card is blocked
media_urlstring
A public https link to a file. The dashboard downloads it once (15 s timeout, redirects are not followed) and keeps it only if it is an allowed type and at most 10 MB.
media_namestring
File name shown in the thread, up to 160 characters.Example: receipt.pdf
idstring
Your provider's message id, up to 120 characters. A second message with the same id is ignored, so retries are safe.Example: provider-message-id
RequestHTTP
1POST https://<your-domain>/api/channels/webhook/<channel token>2Content-Type: application/json3 4{5  "from": "+923001234567",6  "name": "Ali Khan",7  "text": "My card is blocked",8  "media_url": "https://cdn.provider.example/abc.jpg",9  "media_name": "receipt.jpg",10  "id": "provider-message-id"11}
200 responseJSON
{ "ok": true, "conversation_id": 12 }

A repeated id still answers 200, with conversation_id set to null. If the media cannot be downloaded or is not allowed, the message is still stored when it has text; with neither text nor usable media it is refused.

StatuserrorMeaning
404(text: Not found)No generic channel has this token.
409channel_disabledThe channel is switched off. Nothing is stored.
400bad_jsonThe body is not JSON.
400from_requiredfrom is missing or empty after cleaning.
400media_url_not_allowedThe media link is not https, has credentials in it, or points at a private or local address.
400text_or_media_requiredNo text and no usable file.

Outbound: dashboard → your bridge

Every reply is POSTed to the outbound URL as JSON, signed with the channel's secret exactly like webhooks. Answer with any 2xx within 15 seconds; optionally return { "id": "<your message id>" } so the reply is stored with your id. Any other answer, or no answer, marks the reply failed in the thread.

A text reply, as your bridge receives itHTTP
1POST https://bridge.yourcompany.com/voip9/send2Content-Type: application/json3X-Voip9-Timestamp: 17947000004X-Voip9-Signature: v1=5d0c1f…e9a25 6{ "event": "message.send", "channel": "SMS gateway", "to": "+923001234567", "text": "Your card is active again.", "conversation_id": 12, "sent_at": "2026-11-15T10:05:00.000Z" }

A file adds media_url, media_name and media_mime; text is the caption and is left out when there is none. The URL is a signed link to the file on your server that works for one hour, without signing in: download it and hand it to your provider.

A file replyJSON
1{2  "event": "message.send",3  "channel": "SMS gateway",4  "conversation_id": 12,5  "to": "+923001234567",6  "text": "Your statement",7  "media_url": "https://<your-domain>/api/media/public/431?exp=1794700000&sig=…",8  "media_name": "statement.pdf",9  "media_mime": "application/pdf",10  "sent_at": "2026-11-15T10:05:00.000Z"11}

Test in the dashboard posts { "event": "ping", "channel": "<name>", "sent_at": "…" }, signed the same way. Before every POST the outbound URL is checked again: it must be https and resolve to a public address.

Checking the signature

The signature is v1= followed by the hex HMAC-SHA256 of timestamp + "." + raw body, keyed with the channel's signing secret. Compute it over the raw bytes before parsing the JSON, compare in constant time, and reject old timestamps (five minutes is a sensible window).

bridge.jsJavaScript
1import { createHmac, timingSafeEqual } from "node:crypto"2 3// raw: the request body exactly as received (a string), before JSON.parse4export function verify(raw, timestamp, signature, secret) {5  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false6  const expected = "v1=" + createHmac("sha256", secret).update(timestamp + "." + raw).digest("hex")7  return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected))8}

A reply with a file, end to end

AgentAgentDashboardDashboardYour bridgeYour bridgeProviderProviderSend statement.pdfpaperclip, ≤ 10 MB1File stored; message saved as queuedPOST message.sendX-Voip9-Signature3GET /api/media/public/431?exp=…&sig=…4application/pdf5Send file to +92300…6200 { id }7Reply marked sent
The bridge never needs a dashboard login: it fetches the file through a signed link that expires after an hour.

Try it without a provider

scripts/channel-test.sh on the server posts a message into a generic channel exactly as a bridge would. Copy the channel's inbound URL from Integrations → Channels. Run it twice with the same number: both messages land in one conversation.

On the serverShell
1# text only (sender defaults to +923001234567)2scripts/channel-test.sh https://<your-domain>/api/channels/webhook/<token>3 4# a chosen sender, text and a public image that is downloaded into the thread5scripts/channel-test.sh https://<your-domain>/api/channels/webhook/<token> +923001234567 "Here is my receipt" https://example.com/receipt.jpg

Working a conversation

Conversations lists threads with the newest message first, split into Open and Closed, with an unread count in the sidebar. An open thread refreshes every five seconds and is marked read when someone opens it.

In the thread headerWhat it does
Link to ticketFind a ticket by number or title, or create one, with the sender's number filled in. One thread can be on several tickets.
Assigned toPick a colleague, or Unassigned. Only people of your organization can be chosen.
CallCalls the number from your browser phone (available while the phone is signed in).
Save as contactShown for unknown senders. Saves the number to your own contacts and re-matches every thread of the organization.
Close / ReopenA closed thread cannot be replied to until it is reopened. A new message from the customer reopens it automatically.

You can also start a thread with someone who has not written first: the Message button next to a number (contacts, the phone, the call dock) opens the existing thread or creates one. With several channels it asks which to use. The number must have 6 to 15 digits.

Who is writing

Every thread is matched to your organization by number. +92 300 1234567, 0300 1234567 and 923001234567 are the same person: numbers longer than seven digits are compared by their last 10 digits, shorter ones (extensions) must match exactly.

  • An extension-length number that belongs to a colleague shows the colleague's name.
  • Otherwise a contact saved by anyone in the organization gives the name and a Contact badge; favourites win when several match.
  • Matches are refreshed whenever a contact is added, edited or deleted. If the contact is deleted, the thread keeps the last name it showed.
  • An unknown sender gets a Save as contact button in the thread header.

The message.received event

Every new inbound message, on any channel, queues the webhook event message.received for the organization's webhooks that subscribe to it. It is signed and retried like every other event (see Webhooks). Replies sent by your people do not fire it.

message.receivedJSON
1{2  "id": "evt_3f9c1b2a7d4e5f60718293a4",3  "type": "message.received",4  "created_at": "2026-11-15T10:04:12.481Z",5  "organization": "acme-bank",6  "data": {7    "conversation_id": 12,8    "channel": "WhatsApp · Card services",9    "from": "+923001234567",10    "name": "Ali Khan",11    "kind": "image",12    "text": "Here is my receipt",13    "received_at": "2026-11-15T10:04:12.480Z"14  }15}

kind is one of text, image, audio, document, location or other. The file itself is not in the event; open the conversation to see it.

Where the data goes

WhatWhere
Channel settingsYour database. Access token, App secret and bridge signing secret are encrypted with AES-256-GCM; the dashboard never sends them back to the browser (it only shows that one is saved), except the bridge secret on an Admin's explicit Show.
Threads and messagesYour database, one conversation per channel and number.
MediaFiles under /var/spool/voip-ivr/media/<organization>/ on your server, served only to signed-in people of the same organization. Files you send also get a one-hour signed link for your bridge.
EventsWebhook message.received for every inbound message.
TicketsLink any thread to a support ticket from the conversation header.
Removing a channelIts conversations stay in Conversations.

The web server accepts request bodies up to 12 MB on /api/channels/, so 10 MB files fit with room for the upload overhead; the rest of the dashboard is limited to 2 MB.

Next steps