Messaging - Send text-only message with WhatsApp

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use Telesign Messaging to send a simple text-only WhatsApp message to an end-user.

Before you begin

Make sure you have the following before you start:

📘

NOTE:

The Transaction Callback Service is also where you would receive inbound replies from the recipient of your Messaging message, if you include that optional feature in your integration.

🚧

CAUTION:

If an end user does not have WhatsApp, the WhatsApp send will fail. We recommend either ensuring your end users have WhatsApp on their devices or including a fallback channel for users without WhatsApp.

Steps

  1. Send a POST /v1/omnichannel request. Include the following param values:
ParameterValueDescriptionRequired?
channelsarray of channel objectsAdd channel objects to the array in the order you want the service to try the channels.yes
channels[0]{"channel":"whatsapp"}Include whatsapp as the first channel.yes
channels[0].fallback_timeA time in seconds.Specify the time to wait before cascading to the next channel.no
channels[1]{"channel":"sms"}Include sms as the backup channel.yes (if SMS is used for backup)
message.default.templatetextSpecify the predefined template that includes just text.yes
message.default.parameters.textSome text.Text to display in the message.yes

Request example

POST /v1/omnichannel HTTP/1.1
Content-Type: application/json
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
  "channels": [
   	{
      "channel": "whatsapp",
      "fallback_time": 600
    },
    {
      "channel": "sms"
    }
  ],
  "phone_number": "15558675309",
  "message": {
    "default": {
      "template": "text",
      "parameters": {
        "text": "Buy one get one free! Use code 'BOGO' at checkout on viatushop.com"
      }
    }
  },
  "message_type": "ARN"
}

📘

NOTE:

Because the message parameters and values are the same for all channels in this example, we just use message.default rather than specifying message details for each channel. If you wanted different text for each channel, you would have to specify message details for each one.

  1. If the request is processed successfully, you should see a response with a 3001 status code.

Response example

HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 14 Oct 2020 21:25:54 GMT
Content-Type: application/json
Content-Length: 137
Connection: keep-alive
Allow: GET,POST,HEAD
{
  "status": {
    "code": 3001,
    "description": "Message in progress"
  },
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": null
}
  1. If the send in WhatsApp format is successful, your end-user receives a message on their device that looks like this.
A screenshot of a message received by an end user if the send in WhatsApp format is successful.

WhatsApp Message

  1. If the send in WhatsApp format fails, the service tries to send the next specified backup channel (if any).
A screenshot of a message sent using the next specified backup channel if the send in WhatsApp format is unsuccessful.

SMS Backup

  1. Updates on the status of this message are sent to the callback URL for your Transaction Callback Service. The general callback schema common to both this and other products is described on Transaction Callback Service. Modifications to the callback schema for this product are described on Messaging - Callback service. Search for these callbacks based on the reference ID in the response to your original Messaging request. Each callback payload includes an object with the status of the send for each channel that is tried.

Callback example

GET /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": "null",
  "status": {
    "code": 3000,
    "description": "Delivered",
    "last_channel": "sms",
    "updated_on": "2020-05-04 22:07:01:226"
  },
  "channel_status": [
    {"whatsapp": {
      "code": 3056,
      "description": "Message failed to deliver in specified fallback time",
      "reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
      "updated_on": "2020-05-04 22:06:03.837"
    }},
    {"sms": {
      "code": 3000,
      "description": "Delivered",
      "reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
      "updated_on": "2020-05-04 22:07:01:226"
    }}
  ]
}

📘

NOTE:

In addition to the reference ID for the Messaging transaction itself, the delivery status payload also includes a reference ID for the message-send on each channel. These can be useful for troubleshooting purposes.