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

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
numbers
required
Array of string
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
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.

Send a WhatsApp message

Authorizations
Request Body Schema
  • application/json
to
required
Array of string
Array of phone numbers (msisdns). Required.
message*
required
TextMessage (object) or
ImageMessage (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
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.

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.

LocationMessage

type
required
string
Value: location
lat
required
number [-90 .. 90]
The latitude position as a float number.
lng 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

200 Expected result to a valid request

Response Schema: application/json

type string
Value: whatsapp
property name* object (receipt)

*property name

message_id string
status string
Enum: success failure
state string
Enum: queued delivered read deleted no_capability no_opt_in failed

400 Bad request

Response schema: application/json

title string
reason string

401 Unauthorized bot

Response schema: application/json

title string
reason string

406 Media file not accepted

Response schema: application/json

title string
reason string

415 Unsupported media file type

Response schema: application/json

title string
reason string

500 Internal server error

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",
    "text": "Greetings from Sinch"
  }
}

Image Message

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

Document Message

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

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"
    ]
  }
}

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

200

{
  "type": "whatsapp",
  "receipts": {
    "0732001122": {
      "message_id": "asdbas-7sdf78sd-16237smh",
      "status": "success",
      "state": "queued"
    },
    "0732002244": {
      "status": "failed",
      "state": "no_capability"
    },
    "0732003366": {
      "status": "failed",
      "state": "no_opt_in"
    }
  }
}

400

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

401

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

406

{
  "message": "406",
  "reason": "Error when downloading media from given URL"
}

415

{
  "message": "415",
  "reason": "File type not supported"
}

500

{
  "message": "500",
  "reason": "Internal server error"
}

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.

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 (receipt)
Array of status updates. Such as delivered/read events.

notifications

Array [

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

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)
Array of object (ContactCard)

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
status string
Enum: "success" "failure"
state string
Enum: "queued" "delivered" "read" "deleted" "no_capability"
"no_opt_in" "failed"

]


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

Sample notification messages are shown below.

Text

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

Media

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

Contacts

{
  "receipts":[
    {
      "message_id":"asdbas-7sdf78sd-16237gtf",
      "status":"success",
      "state":"delivered"
    }
  ],
  "notifications":[
    {
      "from":"0732001122",
      "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

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