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.
| Who | Can do |
|---|---|
| Admin | Add, 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 organization | Read 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.
Create the Meta app
In Meta for Developers create an app of type Business and add the WhatsApp product.
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 thewhatsapp_business_messagingandwhatsapp_business_managementpermissions and generate a permanent access token.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.
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
messagesfield.Callback URLText https://<your-domain>/api/channels/whatsapp/<channel token>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.
1GET /api/channels/whatsapp/<channel token>?hub.mode=subscribe&hub.verify_token=<verify token>&hub.challenge=11582014442 3HTTP/1.1 200 OK4 51158201444What 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.
- Always 200. Once the token and signature are accepted, the dashboard answers
200even if processing a message fails (the error goes to the server log), because Meta retries anything else. A switched-off channel also gets200, and the message is dropped. - Rejected deliveries: unknown token
404, body over 1 MB413, bad or missing signature (when an App secret is set)401, invalid JSON400. - 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 sends | Shown in the thread as |
|---|---|
| Text | Text. |
| Image, sticker | Photo, with its caption as text. |
| Voice note, audio | Voice message with a player. |
| Video, document | A file to open or download, with the document's file name and caption. |
| Location | Text: the place name and a maps.google.com link to the coordinates. |
| Anything else | Stored 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:
| File | Types | On WhatsApp it arrives as |
|---|---|---|
| Photo | JPG, PNG | A photo, with caption |
| Other images | WebP, GIF | A document, with caption and file name |
| Voice note | MP3, OGG, M4A, AAC, AMR | Audio. WhatsApp shows no caption on audio, so the text is sent as a separate message right after it. |
| Video | MP4 | A video, with caption |
| Document | A 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 +.
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.
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.
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.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).Test both directions
Test posts a signed
pingevent to the outbound URL and reports the status code your bridge answered. Then post a message into the inbound URL (see below, or usescripts/channel-test.sh).
Inbound: your bridge → dashboard
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 samefromon 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
httpslink 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
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}{ "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.
| Status | error | Meaning |
|---|---|---|
404 | (text: Not found) | No generic channel has this token. |
409 | channel_disabled | The channel is switched off. Nothing is stored. |
400 | bad_json | The body is not JSON. |
400 | from_required | from is missing or empty after cleaning. |
400 | media_url_not_allowed | The media link is not https, has credentials in it, or points at a private or local address. |
400 | text_or_media_required | No 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.
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.
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).
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}1import hashlib, hmac, time2 3def verify(raw: bytes, timestamp: str, signature: str, secret: str) -> bool:4 if abs(time.time() - int(timestamp)) > 300:5 return False6 mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()7 return hmac.compare_digest(signature, "v1=" + mac)1<?php2$raw = file_get_contents("php://input");3$ts = $_SERVER["HTTP_X_VOIP9_TIMESTAMP"] ?? "";4$sig = $_SERVER["HTTP_X_VOIP9_SIGNATURE"] ?? "";5$mac = "v1=" . hash_hmac("sha256", $ts . "." . $raw, getenv("VOIP9_CHANNEL_SECRET"));6if (abs(time() - (int) $ts) > 300 || !hash_equals($mac, $sig)) { http_response_code(401); exit; }A reply with a file, end to end
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.
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.jpgWorking 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 header | What it does |
|---|---|
| Link to ticket | Find a ticket by number or title, or create one, with the sender's number filled in. One thread can be on several tickets. |
| Assigned to | Pick a colleague, or Unassigned. Only people of your organization can be chosen. |
| Call | Calls the number from your browser phone (available while the phone is signed in). |
| Save as contact | Shown for unknown senders. Saves the number to your own contacts and re-matches every thread of the organization. |
| Close / Reopen | A 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.
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
| What | Where |
|---|---|
| Channel settings | Your 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 messages | Your database, one conversation per channel and number. |
| Media | Files 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. |
| Events | Webhook message.received for every inbound message. |
| Tickets | Link any thread to a support ticket from the conversation header. |
| Removing a channel | Its 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.