---
title: Comms providers
description: "Connect your Sinch account step by step, your own Jasmin or Kannel SMS gateway or a Telegram bot, or try Comms with the fake provider; how callbacks are verified and how fallback works."
section: comms
order: 20
audience: [operator]
sources: [services/nodejs-cloud/lib/comms/telegram.ts, services/nodejs-cloud/lib/comms/sinch.ts, services/nodejs-cloud/lib/comms/gateway.ts, services/nodejs-cloud/lib/comms/fake.ts, services/nodejs-cloud/lib/comms/adapter.ts, services/nodejs-cloud/lib/comms/registry.ts, services/nodejs-cloud/app/api/integrations/comms]
features: []
---

Comms sends through a provider account your org owns. Add one in **Settings, Comms, Providers**. Its secrets are
sealed in the vault, shown afterwards only as a hint, and never returned by the API. After saving, the provider's card
shows its **webhook URLs**: give them to the provider so delivery reports, replies and call events come back.

An org can have several providers. Each has a **priority**; a message goes through the lowest number that is enabled,
has the channel and has a sender for it. If that provider fails with an error worth retrying (a timeout, a 5xx), the
next one is tried, and then the message is retried with backoff: 30 seconds, then 1, 2, 4 and 8 minutes, five attempts
in all. A refusal (a bad number, a 4xx) is final.

A provider you turn off takes no new conversation in either: replies, history and call events are refused with 403
until you turn it on again, and the provider keeps retrying them on its side. What must not wait is still kept while it
is off: delivery reports of messages it already sent, template and account states, and a STOP, which is recorded as an
opt-out at once (no confirmation is sent through a provider that is off).

## Sinch

Sinch carries SMS, WhatsApp, RCS and Telegram through one Conversation API, and phone calls through its Voice API.

1. In the Sinch Build dashboard, open **Settings, Projects** and copy the **project ID**.
2. **Settings, Access keys**: create an access key. Copy the **key ID** and the **key secret** (it is shown once).
3. **Conversation API, Apps**: create an app in the region you want (`us`, `eu` or `br`) and connect the channels you
   will use (an SMS number, a WhatsApp sender, an RCS agent, a Telegram bot). Copy the **app ID**.
4. For calls, **Voice, Apps**: create a voice application with a number. Copy the **application key** and **secret**.
5. In Venom, **Settings, Comms, Add a provider, Sinch**: paste the project ID, key ID, key secret, app ID and region;
   choose a **webhook secret** (any long random string); for calls add the voice application key, secret and region
   (empty for global, or `euc1`, `use1`, `sae1`, `apse1`, `apse2`). Save.
6. Back in Sinch, add a webhook to the Conversation app: the **conversation** URL Venom shows
   (`…/api/integrations/comms/<id>/<token>/conversation`), the same webhook secret, and the triggers
   `MESSAGE_DELIVERY` and `MESSAGE_INBOUND`. Set the voice application's callback URL to the **voice** URL
   (`…/voice`).
7. In **Senders**, add each number or sender id with its channels and the countries it serves.
8. Use **Send a test** at the bottom of the page.

Venom checks every callback before reading it: a Conversation webhook must carry a valid HMAC-SHA256 signature made
with the webhook secret, a Voice callback a valid signature made with the application secret, and both must be less
than 10 minutes old. Anything else gets 401 and changes nothing. A callback Sinch sends twice is applied once.

Calls run as Sinch callouts. Each script step becomes Sinch's call control (SVAML): `say` is read by Sinch's
text-to-speech, or played from Venom in your org's TTS voice when you chose one (see [Incidents paging](/docs/comms/incidents-paging.md#voice));
`gather` is a menu whose key presses come back as `call.gather`; `transfer` connects to the number.

## WhatsApp through Meta

The **WhatsApp (Meta Cloud API)** card connects your WhatsApp Business number to Meta's own Cloud API with your Meta
app: paste the app ID, the app secret and a System User token, pick the number, and Venom registers it, points the
account's webhooks at Venom, reads the templates and routes the number to Support. Webhooks are checked against
`X-Hub-Signature-256` (your app secret's HMAC of the body) before anything is read, and Meta's `hub.challenge`
handshake is answered only with the verify token Venom made. Step by step, costs and limits:
[WhatsApp through Meta's Cloud API](/docs/comms/whatsapp-meta.md).

## Your own gateway

The **Self-hosted gateway** provider sends SMS through your own SMS gateway, so messages go from your servers to your
carrier or SMSC with no third-party API:

- **SMS send URL**: the gateway's HTTP send endpoint, such as Jasmin's `https://sms.example.org:1401/send`. Kannel's
  `/cgi-bin/sendsms` takes the same fields.
- **Username** and **Password**: the gateway user Venom sends as.
- **Webhook secret**: made for you when left empty.

Venom posts `username`, `password`, `to`, `from`, `content` and a delivery-report URL; the gateway answers
`Success "<id>"`. Point the gateway's delivery reports and inbound messages (an HTTP client connector in Jasmin) at the
**gateway** URL Venom shows, which carries `?secret=` (or send the secret in an `x-venom-gateway-secret` header).
Inbound messages are answered `ACK/Jasmin`.

Calls through your own PBX (Asterisk ARI) need a media bridge that holds the call's audio; it is planned in the
orchestrator and not built yet, so a call through the gateway is refused with that reason. Use Sinch for calls in the
meantime, with the gateway for SMS: put the gateway first and Sinch second. Until the SMS URL is saved, a send through
the gateway answers that it is not configured.

## A Telegram bot

Make a bot with Telegram's @BotFather (`/newbot`) and copy its token. In **Settings, Comms, Add a provider, Telegram
bot**, paste the token. Venom checks it with `getMe`, sets the webhook to the provider's `…/telegram` URL with a random
secret token (Telegram sends it back in `X-Telegram-Bot-Api-Secret-Token`, which is checked in constant time before
anything is read), and adds the bot as a sender (`@yourbot`). Only private chats count; groups and edits are ignored. A
Telegram bot can send text, photos and documents but not call, and it has no STOP: a person blocks the bot. Route the
bot to Support or People in [Support, Settings](/docs/comms/support-and-people.md#point-a-number-at-a-product).

A bot can only answer people who wrote to it first. To write first, as yourself, link your own Telegram account
through your Venom daemon instead ([Telegram from your own account](/docs/comms/telegram-personal.md)): that is the
`telegram_user` channel, and it is linked with a code, never added here.

## The fake provider

**Fake** sends nothing. It records each message and call, gives them ids, and reports what you ask through
**Simulate** on the settings page or `POST /v1/comms/simulate`: a reply, a STOP, a delivery report, an answered call, a
key press, a hang-up. Use it to try profiles and Incidents paging before buying numbers, and in your own tests.

## Callback URLs

| Route | From |
|---|---|
| `…/conversation` | Sinch's Conversation API webhook |
| `…/voice` | Sinch's Voice API callbacks (answered, key press, disconnected); the answer is the next steps |
| `…/gateway` | your gateway's delivery reports and inbound messages |
| `…/fake` | the fake provider's simulated events |
| `…/telegram` | a Telegram bot's updates |
| `…/meta` | WhatsApp Cloud API webhooks (POST) and Meta's subscription handshake (GET) |
| `…/tts/<call>/<step>` | Sinch fetches a step's audio here when your org has a TTS voice |

Every one starts with `/api/integrations/comms/<provider id>/<token>`. The token is random per provider; removing the
provider retires it.
