Skip to main content

Turn Fallback Channel

warning

This API is going to be deprecated at some point in the future. If you were planning to start using it, please instead refer to Channels API

The fallback channel allows you to send non-WhatsApp messages using Turn, it is enabled by specifying a fallback url in the UI.

Contacts will be defaulted to the fallback channel when the amount of WhatsApp failures reach the error threshold configured in the UI. A successful incoming WhatsApp message from the contact would change the default back to WhatsApp.

Example payload​

{
  "preview_url": false,
  "recipient_type": "individual",
  "to": "16315551003",
  "type": "text",
  "text": {
    "body": "text message content"
  }
}

Override outgoing message​

You can specify a header to force a message to be sent over the fallback channel, this will send the message payload to the fallback channel regardless of default channel on the contact.

$ curl -X POST "https://whatsapp.turn.io/v1/messages" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "x-turn-fallback-channel: 1"
  -d '
    {
        "preview_url": false | true,
        "to": "whatsapp-id",
        "type": "text",
        "text": {
            "body": "your-text-message-content"
        }
    }'

Events​

Fallback channel events can be sent to https://whatsapp.turn.io/api/whatsapp/channel-uuid in the format specified here: https://developers.facebook.com/docs/whatsapp/api/webhooks/outbound

note

If you want to identify fallback channel webhook events you can specify the x-turn-fallback-channel header when sending the events, this header will be forwarded to the webhooks

Manually updating flag​

You can call the contact API to manually update the "is_fallback_channel_active" flag

See the Contact Api for more info

Security​

See an example below of how the signature can be calculated using the Python programming language.

>>> import hmac
>>> import base64
>>> from hashlib import sha256
>>> h = hmac.new("secret", '{"foo":"bar"}', sha256)
>>> base64.b64encode(h.digest())
'PzqzmGtlarsXrz6xRD7WwI74//n+qDkVkJ0bQhrsib4='

The signature is sent as an HTTP header to the fallback channel endpoints you have configured.

X-Turn-Hook-Signature: PzqzmGtlarsXrz6xRD7WwI74//n+qDkVkJ0bQhrsib4=

The hmac secret should be used to calculate a signature for the message payload. Using this signature you can verify that the message was indeed received from Turn.

note

Currently only SHA256 is supported as an hmac digest

The signature is sent as an HTTP header in the webhook posted to the endpoints you have configured.