WhatsApp API

Introduction

The Sinch WhatsApp Business Messaging API provides a rich, enterprise grade messaging solution for clients who wish to communicate with their customers via WhatsApp.

With over 1.5bn users globally using WhatsApp regularly to communicate with friends and family, it really does represent the digital extension of the users living room. It’s the inner circle of your customer’s communication so bringing your trusted brand communications to that inner circle has huge potential.

Integrating the Sinch WhatsApp Business Messaging API with your own backend systems enables Rich, High fidelity, contextual conversations to be established via the WhatsApp channel.

This API specification covers the range of features available.

Authentication

The Sinch WhatsApp API securely authenticates via a bot identifier and bearer token pair. During the initial client on boarding process, these will be provided by your account manager.

To be able to authenticate the access token needs to be passed. For all WhatsApp end-points it is required to set the bearer token in the authorization HTTP header like: Authorization: Bearer AbCdEf123456. Where the string "AbCdEf123456" is the bearer authorization token.

BearerAuth

Security scheme type: HTTP
HTTP Authorization Scheme bearer

Base URL

Currently all WhatsApp URLs referenced in the WhatsApp documentation has the base URL:

https://us1.whatsapp.api.sinch.com

We’re working on setting up an EU server as soon as possible, meanwhile please use the listed base url.

Opt-In-and-Outs

All Business initiated conversations via the Sinch WhatsApp Business API must start with an “Opt-In” by the user. This can be collected through any third party. For example in an SMS message, In-Line with a Web Form, in an Email, or even via a deep-link in print media.

You can record a opt-in by the API call described below and once the “Opt-In” is recorded you’ll be able to message that customer via the Sinch WhatsApp Business API.

Businesses must provide a method by which customers may opt-out of receiving future messages from your organisation. The opt-out should be handled using the API call below.

Opt-In

Opt-in numbers to enable the receiving of business messages via WhatsApp.

Authorizations
Request Body Schema
  • application/json
  • The numbers that you wish to opt in, which allows the current bot to send messages to them.
numbers
required
Array of string [1..20] items
Array of phone numbers (msisdns).

Responses

200 Expected result to a valid request

400 Bad request

Response schema: application/json

title string
reason string

401 Unauthorized bot

Response schema: application/json

title string
reason string


Path Parameters
bot-id
required
string
The identifier of the bot that wishes to send messages.

Request samples

POST

/whatsapp/v1/{bot-id}/provision/optin

Payload

{
  "numbers":[
    "46732001122",
    "46732002244",
    "46732003366"
  ]
}

Response samples

200

<empty request body>

400

{
  "message":"Validation error",
  "reason":"Field [numbers] can not be empty."
}

401

{
  "message":"401",
  "reason":"Unauthorized bot"
}

Opt-Out

Opt-out numbers to disable the receiving of business.

Authorizations
Request Body Schema
  • application/json
numbers
required
Array of string [1..20] items
Array of phone numbers (msisdns).

Responses

200 Expected result to a valid request

400 Bad request

Response schema: application/json

title string
reason string

401 Unauthorized bot

Response schema: application/json

title string
reason string


Path Parameters
bot-id
required
string
The identifier of the bot that wishes to send messages.

Request samples

POST

/whatsapp/v1/{bot-id}/provision/optout

Payload

{
  "numbers":[
    "46732001122",
    "46732002244",
    "46732003366"
  ]
}

Response samples

200

<empty request body>

400

{
  "message": "Validation error",
  "reason": "Field [numbers] can not be empty."
}

401

{
  "message": "401",
  "reason": "Unauthorized bot"
}

Message

The message endpoint is used as the primary endpoint of the API and this is where all the messages are sent through.

WhatsApp message flow

../_images/whatsapp-msg-flow1.png
  1. Customer opt-in is essential before sending any messages.
  2. Businesses can only start a conversation with a defined message template.
  3. Once you get a reply from your customer, a customer care session starts. You can then send “session” rich content messages for 24 hours.
  4. Every time a customer replies to one of your messages, a new 24-hour cycle starts.
  5. If a “session” expires, you’ll need to re-initiate a conversation, starting with a defined message template again.
  6. Customers can start a rich content conversation with a business at any time
    • this opens up a new 24-hour session.

Supported Content-Types

The Sinch WhatsApp API supports several media types. In the table below you can find what content-types are supported by the API.

Message type Supported Content-Types
Image image/jpeg, image/png
Video video/mp4
Note: Only H.264 video codec and AAC audio codec is supported.
Document application/pdf, application/msword, application/vnd.ms-powerpoint, application/vnd.ms-excel, text/plain
Audio audio/acc, audio/mp4, audio/amr, audio/mpeg, audio/ogg, codecs=opus

Send a WhatsApp message

Authorizations
Request Body Schema
  • application/json
to
required
Array of string [1..20] items
Array of phone numbers (msisdns). Required.
message*
required
TextMessage (object) or
ImageMessage (object) or
VideoMessage (object) or
DocumentMessage (object) or
AudioMessage (object) or
TemplateMessage (object) or
LocationMessage (object) or
ContactsMessage (object)

message

One of the following:

TextMessage

type
required
string
Value: "text"
preview_url boolean
A preview of a link will show in the message.
Value: true or false
Default false
text
required
string
The actual text body. Required.

ImageMessage

type
required
string
Value: "image"
url
required
string
The url to the image (jpg | jpeg | png).
caption string
Optional caption that will be displayed underneath the image.

VideoMessage

type
required
string
Value: "video"
url
required
string
The url to the video (mp4).
caption string
Optional caption that will be displayed underneath the video.

DocumentMessage

type
required
string
Value: "document"
url
required
string
The url to the document (pdf).
caption string
Optional caption that will be displayed as the document title.

AudioMessage

type
required
string
Value: "audio"
url
required
string
The url to the audio file (mp3).

TemplateMessage

type
required
string
Value: "template"
template_name
required
string
Name of the template. This has to be registered before hand.
params Array of string
An array holding each string parameter that will be injected into the
specified template. Required if the referred template contains variables.
ttl string
Time to live of the template message. If the receiver has not opened the
template message before the time to live expires, the message will be deleted
and a failed callback will be sent. The time to live can be specified
in ISO-8601 Duration format or in seconds as a string.

LocationMessage

type
required
string
Value: "location"
lat
required
number [-90 .. 90]
The latitude position as a float number.
lng
required
number [-180 .. 180]
The longitude position as a float number.
name string
The name for the location. Will be displayed in the message.
address string
The address for the location. Will be displayed in the message.

ContactsMessage

type
required
string
Value: "contacts"
contacts*
required
Array of object (ContactCard)

contacts*

addresses*

Array [

city
required
string
country string
country_code string
state string
street string
type string
zip string

]

Array of object (ContactCardAddress)
birthday string

emails*

Array [

email
required
string
type string

]

Array of object (ContactCardEmail)

name*

first_name string
last_name string
formatted_name
required
string


required

object (ContactCardName)

org*

company
required
string
department string
title string
object (ContactCardOrganization)

phones*

Array [

phone
required
string
type string
wa_id string

]

Array of object (ContactCardPhone)

urls*

Array [

url
required
string
type string

]

Array of object (ContactCardUrl)


Responses

201 Expected result to a valid request

Response Schema: application/json

type
required
string
Value: "whatsapp"
statuses* object (Status)
notifications* object (Notification)

statuses


message_id string
recipient string
status string
Enum: "success" "failure"
state string
Enum: "queued" "dispatched" "sent" "delivered" "read"
"deleted" "no_capability" "no_opt_in" "failed"

notifications


from string
The originator of this message
message_id string
Generated message id for this notification
message* NotificationTextMessage (object) or
NotificationLocationMessage (object) or
NotificationContactsMessage (object) or
NotificationMediaMessage (object)

message

One of the following:

NotificationTextMessage

type string
Value: "text"
body string
The text of the text message

NotificationLocationMessage

type string
Value: "location"
latitude number [-90..90]
longitude number [-180..180]
name string
The name for the location. Will be displayed in the message.
address string
The address for the location. Will be displayed in the message.
url string
Optional url for the location.

NotificationContactsMessage

type
required
string
Value: "contacts"
contacts*
required
Array of object (ContactCard)

contacts*

addresses*

Array [

city
required
string
country string
country_code string
state string
street string
type string
zip string

]

Array of object (ContactCardAddress)
birthday string

emails*

Array [

email
required
string
type string

]

Array of object (ContactCardEmail)

name*

first_name string
last_name string
formatted_name
required
string


required

object (ContactCardName)

org*

company
required
string
department string
title string
object (ContactCardOrganization)

phones*

Array [

phone
required
string
type string
wa_id string

]

Array of object (ContactCardPhone)

urls*

Array [

url
required
string
type string

]

Array of object (ContactCardUrl)

NotificationMediaMessage

type
required
string
Enum: "image" "document" "audio" "video" "voice"
What type of media this object is.
url
required
string
The url where to download the media file from.
mime_type
required
string
The mime type of this file.
caption string
Optional description of this resource.

400 Bad request

Response schema: application/json

title string
reason string

401 Unauthorized bot

Response schema: application/json

title string
reason string

503 Service unavailable

Response schema: application/json

title string
reason string


Path Parameters
bot-id
required
string
The identifier of the bot that wishes to send messages.

Request samples

POST

/whatsapp/v1/{bot-id}/messages

Where the payload is one of the alternatives below.

Text Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "text",
    "preview_url": false,
    "text": "Greetings from Sinch"
  }
}

Image Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "image",
    "url": "https://example.com/image.jpg",
    "caption": "Example Image"
  }
}

Video Message

{
  "to":[
    "46732001122"
  ],
  "message":{
    "type": "video",
    "url": "https://example.com/video.mp4",
    "caption": "Example Video"
  }
}

Document Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "document",
    "url": "https://example.com",
    "caption": "Example study",
    "filename": "document.pdf"
  }
}

Audio Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "audio",
    "url": "https://example.com/song.mp3"
  }
}

Template Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "template",
    "template_name": "sinch_test_greeting",
    "params": [
      "Nick"
    ],
    "ttl": "P1D"
  }
}

Location Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "location",
    "lat": 55.7047,
    "lng": 13.191,
    "name": "Sinch Ideon Lund",
    "address": "Scheelevägen 17"
  }
}

Contact Cards Message

{
  "to": [
    "46732001122"
  ],
  "message": {
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "city": "Menlo Park",
            "country": "United States",
            "country_code": "us",
            "state": "CA",
            "street": "1 Hacker Way",
            "type": "HOME",
            "zip": "94025"
          }
        ],
        "birthday": "2012-08-18",
        "emails": [
          {
            "email": "test@fb.com",
            "type": "WORK"
          }
        ],
        "name": {
          "first_name": "John",
          "formatted_name": "John Smith",
          "last_name": "Smith"
        },
        "org": {
          "company": "WhatsApp",
          "department": "Design",
          "title": "Manager"
        },
        "phones": [
          {
            "phone": "+1 (650) 555-1234",
            "type": "WORK",
            "wa_id": "16505551234"
          }
        ],
        "urls": [
          {
            "url": "https://www.facebook.com",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

Response samples

201

{
  "type":"whatsapp",
  "statuses":[
    {
      "message_id":"f1690238-9c72-49c3-b1c6-b701f8765732",
      "recipient":"+46732001122",
      "status":"success",
      "state":"queued"
    }
  ]
}

400

{
  "message": "Validation error",
  "reason": "Field [to] can not be empty."
}

401

{
  "message": "401",
  "reason": "Unauthorized bot"
}

503

{
  "message": "503",
  "reason": "Internal service not available, request could not be handled"
}

Callback

There are two different types of callbacks that are being sent back from the Sinch WhatsApp API. Namely statuses and notifications where statuses are updates on the message being sent, such as delivered, read or failed. Notifications are messages that the end users wants to send back to the bots which the bots can act upon. Please note that the callback section in this documentation is not an endpoint.

Message States

The message states below are status updates on sent messages.

QUEUED Message has been queued by Sinch WhatsApp API
DISPATCHED Message has been dispatched by Sinch WhatsApp API to WhatsApp
SENT Message has been sent by WhatsApp to end-user
DELIVERED Message has been delivered to end-user by WhatsApp
READ The message has been read by the end-user in the WhatsApp application
DELETED The message has been deleted in the application, e.g. templates expiring or
when the end-user manually deletes a message
NO_CAPABILITY Sent message has been rejected by the Sinch API as the recipient lacks
WhatsApp capability
NO_OPT_IN Message rejected by Sinch API as recipient is not registered to have opted
in to receive business messages on WhatsApp from the sending bot
FAILED Fail status, e.g. trying to send a non-template message outside of the
24 hour customer care window will return this error
Request Body Schema
  • application/json
type string
Value: "whatsapp"
notifications* Array of object (Notification)
Array of notification objects. These are responses that
the users send back which the bot can act upon.
statuses* Array of object (Status)
Array of status updates. Such as delivered/read events.

notifications

Array [

from string
The originator of this message
to string
The bot ID receiving this message
message_id string
Generated message id for this notification
message* NotificationTextMessage (object) or
NotificationLocationMessage (object) or
NotificationContactsMessage (object) or
NotificationMediaMessage (object)

]

message

One of the following:

NotificationTextMessage

type string
Value: "text"
body string
The text of the text message

NotificationLocationMessage

type string
Value: "location"
latitude number [-90..90]
longitude number [-180..180]
name string
The name for the location. Will be displayed in the message.
address string
The address for the location. Will be displayed in the message.
url string
Optional url for the location.

NotificationContactsMessage

type
required
string
Value: "contacts"
contacts*
required
Array of object (ContactCard)

contacts*

addresses*

Array [

city
required
string
country string
country_code string
state string
street string
type string
zip string

]

Array of object (ContactCardAddress)
birthday string

emails*

Array [

email
required
string
type string

]

Array of object (ContactCardEmail)

name*

first_name string
last_name string
formatted_name
required
string


required

object (ContactCardName)

org*

company
required
string
department string
title string
object (ContactCardOrganization)

phones*

Array [

phone
required
string
type string
wa_id string

]

Array of object (ContactCardPhone)

urls*

Array [

url
required
string
type string

]

Array of object (ContactCardUrl)

NotificationMediaMessage

type
required
string
Enum: "image" "document" "audio" "video" "voice"
What type of media this object is.
url
required
string
The url where to download the media file from.
mime_type
required
string
The mime type of this file.
caption string
Optional description of this resource.

statuses

Array [

message_id string
recipient string
status string
Enum: "success" "failure"
state string
Enum: "queued" "dispatched" "sent" "delivered" "read"
"deleted" "no_capability" "no_opt_in" "failed"

]


Responses

202 Your server implementation should return this HTTP status code if the data was received successfully.


Request samples

POST

/pre-registered-callback-url

Notification messages can be of one of the following Text, Location, Contacts or Media.

Sample notification messages are shown below.

Text

{
  "statuses":[
    {
      "message_id":"asdbas-7sdf78sd-16237smh",
      "recipient": "+46732001122",
      "status":"success",
      "state":"delivered"
    }
  ],
  "notifications":[
    {
      "from":"0732001122",
      "to":"sinchbot",
      "message_id":"asd89-sdfsdfsdjsd-7as8da9",
      "message":{
        "type":"text",
        "body":"Hello bot I want to know something!"
      }
    }
  ]
}

Media

{
  "statuses":[
    {
      "message_id":"aa001-7sdf78ac-16567fef",
      "recipient":"+46732001122",
      "status":"success",
      "state":"delivered"
    }
  ],
  "notifications":[
    {
      "from":"0732001122",
      "to":"sinchbot",
      "message_id":"a0189-7df8df4d129-7as8da9",
      "message":{
        "type":"image",
        "url":"http://www.example.com/img.jpg",
        "mime_type":"image/jpeg",
        "caption":"Fantastic headphones"
      }
    }
  ]
}

Contacts

{
  "statuses":[
    {
      "message_id":"asdbas-7sdf78sd-16237gtf",
      "recipient":"+46732001122",
      "status":"success",
      "state":"delivered"
    }
  ],
  "notifications":[
    {
      "from":"0732001122",
      "to":"sinchbot",
      "message_id":"asd89-sdfsdfsdjsd-7as8fr9",
      "message":{
        "type":"contacts",
        "contacts":[
          {
            "addresses":[
              {
                "city":"Menlo Park",
                "country":"United States",
                "country_code":"us",
                "state":"CA",
                "street":"1 Hacker Way",
                "type":"HOME",
                "zip":"94025"
              }
            ],
            "birthday":"2012-08-18",
            "emails":[
              {
                "email":"test@fb.com",
                "type":"WORK"
              }
            ],
            "name":{
              "first_name":"John",
              "formatted_name":"John Smith",
              "last_name":"Smith"
            },
            "org":{
              "company":"WhatsApp",
              "department":"Design",
              "title":"Manager"
            },
            "phones":[
              {
                "phone":"+1 (650) 555-1234",
                "type":"WORK",
                "wa_id":"16505551234"
              }
            ],
            "urls":[
              {
                "url":"https://www.facebook.com",
                "type":"WORK"
              }
            ]
          }
        ]
      }
    }
  ]
}

Location

{
  "statuses":[
    {
      "message_id":"asdbas-7sdf78sd-16237tyf",
      "recipient":"+46732001122",
      "status":"success",
      "state":"delivered"
    }
  ],
  "notifications":[
    {
      "from":"0732001122",
      "to":"sinchbot",
      "message_id":"asd89-sdfsdfsdjsd-7as8fr9",
      "message":{
        "type":"location",
        "lat":55.7047,
        "lng":13.191,
        "name":"Sinch Ideon Lund",
        "address":"Scheelevägen 17"
      }
    }
  ]
}