Try for free

Channel cascade

The channel object decides which channels the message is sent through and in what order. It is available in Advanced transactional and Advanced promotional, API version 2.0 only.

Channels table

Every key of the channel object is one channel and holds that channel's own object.

KEY	CHANNEL OBJECT
`sms`	SMS
`viber`	Viber – transactional / Viber – promotional
`rcs`	RCS
`whatsapp`	WhatsApp

Order of the cascade

The order of the keys in your request is the order of the cascade. The first key is the primary channel; if the message cannot be delivered through it, the next channel in the list is used.

{ "channel": { "viber": { "sender": "BulkGate" }, "sms": { "sender_id": "gText", "sender_id_value": "BulkGate" } } }

Viber is tried first here, SMS second. Swapping the two keys swaps the priority - nothing else in the request changes.

Important

SMS is not appended to the end of the cascade automatically. If you want SMS as the last fallback, list the sms object explicitly. A cascade of {"viber": {…}} alone has no fallback at all.

When channel is omitted entirely, the message is sent as SMS with the default sender.

Switching between channels - `expiration`

Each channel object has its own expiration - the time limit in seconds after which the next channel in the cascade is used. Values below 60 are ignored and replaced by the default of that channel.

CHANNEL	DEFAULT `expiration`
`viber`	`300`
`rcs`	`60`
`whatsapp`	`180`

Which text is used

sms and viber fall back through three places, the first non-empty one wins:

PRIORITY	PLACE	NOTE
1	`number[].text`	text of one specific recipient, see Value `number`
2	`channel.sms.text` / `channel.viber.text`	text for that one channel
3	`text`	top-level text of the request

rcs and whatsapp do not read any of them. Their content lives inside their own variant object (message, template, card, …), so the top-level text has no effect on them.

Errors

TYPE	MEANING
`invalid_rcs_variant`	the `rcs` object holds none or more than one of `message`/`file`/`card`/`carousel`
`invalid_whatsapp_variant`	the `whatsapp` object holds none or more than one of `template`/`otp`/`message`/`file`/`location`
`no_recipients`	the request produced no valid recipient

See all the error types for Simple API and Advanced API here.

Was this page helpful?

Ask AI Copied