Skip to content
Docs menu

Comms providers

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.

View .md

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); 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.

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.

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): 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.