WhatsApp Direct Send API

Note:

This WhatsApp functionality is not yet generally available to all customers. Access through Sinch is currently limited to selected businesses participating in the beta program.

If you're interested, but not yet on the allow list, please contact Sinch Support to check eligibility.

If you are a business that is allow listed for WhatsApp's Direct Send API, you can use the channel property WHATSAPP_DIRECT_SEND_CATEGORY to access that functionality. This functionality will allow you (the business) to start conversations with users without needing to create pre-approved templates.

Note:

Currently, this functionality will only accept content that would fit into a utility template. See our documentation on utility templates content documentation.

Direct Send API also allows you to specify a maximum amount of time to deliver the message to the end user. See Direct Send TTL for more information.

Currently, three native WhatsApp message types are supported:

Text Messages
Interactive Reply Buttons
Interactive Call To Action URL Button

Therefore, from a Sinch customer's perspective, you are able to send:

Text messages
Choice messages transcodable to Interactive Reply Buttons
Choice messages transcodable to Interactive Call To Action URL Button
Card messages transcodable to Interactive Reply Buttons
Card messages transcodable to Interactive Call To Action URL Button

Sending text messages

All text messages are supported.

Below is an example payload for a text message sent using the Direct Send functionality:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "text_message":
    {
      "text": "This is a text message from the Sinch Conversation API. https://www.sinch.com"
    }
  },
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Sending choice Reply Buttons

Choice messages are natively supported through the use of Reply Buttons if:

The choice message contains only text.
The message contains no more than three choices.
The title of the choice message is set and is no longer than 1024 characters.
Each choice is no more than 20 characters and doesn't contain markdown.
All choices are unique.
Postback data is no more than 229 characters long, and the postback values are unique.

Below is an example payload for a choice message sent using the Direct Send functionality:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "choice_message":
    {
      "text_message":
      {
        "text": "title"
      },
      "choices":
      [
        {
          "text_message":
          {
            "text": "text1"
          },
          "postback_data": "postback1"
        },
        {
          "text_message":
          {
            "text": "text2"
          },
          "postback_data": "postback2"
        }
      ]
    }
  },
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Sending choice CTA URL Button

Choice messages are natively supported through the use of CTA buttons:

The message only contains a single url choice
The single url choice title is not longer than 20 characters.
Postback data is no more than 229 characters long.

Below is an example payload for a choice message (using a CTA URL) sent using the Direct Send functionality:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "choice_message":
    {
      "text_message":
      {
        "text": "title"
      },
      "choices":
      [
        {
          "url_message":
          {
            "title": "Sinch Website",
            "url": "https://sinch.com"
          },
          "postback_data": "postback1"
        }
      ]
    }
  },
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Sending card Reply Buttons

Most Card message features are supported for Direct Send API through reply buttons. However, card messages with media are not supported.

The requirements for card messages are the same as as choice messages. The content shown on the user's device will appear the same way choice message content would.

Card Messages are natively supported through the use of Reply Button(s) if:

The card choices contain only text.
The message contains no more than three choices.
The title of the card message is set and is no longer than 1024 characters.
Each choice is no more than 20 characters and doesn't contain markdown.
All choices are unique.
Postback data is no more than 229 characters long, and the postback values must be unique.

Below is an example payload for a card message sent using the Direct Send functionality:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "card_message":
    {
      "title": "title",
      "choices":
      [
        {
          "text_message":
          {
            "text": "text1"
          },
          "postback_data": "postback1"
        },
        {
          "text_message":
          {
            "text": "text2"
          },
          "postback_data": "postback2"
        }
      ]
    }
  },
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Sending Card CTA URL Button

Similar to sending card messages using Reply Buttons, sending a card message using a CTA URL is effectively the same as sending choice messages using a CTA URL through Direct Send API.

Card Messages are natively supported through the use of CTA URL Button(s) if:

The message only contains a single url choice
The single url choice title is not longer than 20 characters.
Postback data is no more than 229 characters long.

Below is an example payload for a choice message (using a CTA URL) sent using the Direct Send functionality:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "card_message":
    {
      "title": "title",
      "description": "description",
      "choices":
      [
        {
          "url_message":
          {
            "title": "Sinch Website",
            "url": "https://sinch.com"
          },
          "postback_data": "test"
        }
      ]
    }
  },
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Direct Send TTL

When using WhatsApp Direct Send API, you can also specify the maximum amount of time Meta can take to deliver the message to the end user.

If the message is not delivered within the expected amount of time, you will receive an error webhook informing that the message has expired.

Below is a text message code example for using Direct Send TTL in a Conversation API call:

Copy

Copied

{
  "app_id": "{APP_ID}",
  "recipient":
  {
    "contact_id": "{CONTACT_ID}"
  },
  "message":
  {
    "text_message":
    {
      "text": "This is a text message from the Sinch Conversation API. https://www.sinch.com"
    }
  },
  "ttl": "60s",
  "channel_properties":
  {
    "WHATSAPP_DIRECT_SEND_CATEGORY": "utility"
  }
}

Note the following:

When using ttl with the default WhatsApp Cloud API calls, only Sinch's internal processing time is taken into account to determine whether a message has expired. Meta does not provide this feature for Cloud API calls.
When using ttl with Direct Send API calls, both Sinch's internal processing time and Meta's delivery time are considered to determine whether the message has expired. In this case, Meta allows you to specify a ttl value between 30 seconds and 12 hours. Because Sinch’s internal processing time is also taken into account, the minimum ttl value you set must always be greater than 30 seconds.