Sinch Developer Documentation

Building blocks to enable rich customer communication

Introduction

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

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.

📘

Note

Try out the WhatsApp API live in our new tutorial here WhatsApp Tutorial.

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.

If no authentication header is present or if the bearer token is invalid, the API will respond with HTTP 401 Unauthorized.

BearerAuth

Security scheme typeHTTP
HTTP Authorization Schemebearer

HTTP Errors

Responses with status 400 Bad Request and 401 Unauthorized will present a JSON object in the body explaining the error.
It has the following structure:

NameDescriptionJSON Type
messageA error message describing the general error.String
detailsHuman readable description of the error. Can be used for debugging.String

Base URL

📘

Note

We recently added support for a EU server. We are currently working to add a production server in Asia, so stay tuned!

The following WhatsApp URLs can be used by the WhatsApp API. We have servers in the US and EU.

Swagger

The following Swagger UI URLs can be used to test our API.

Headers

Header nameDescriptionRequired
AuthorizationBearer token described aboveAlways
Content-TypeShould be application/json when sending data through request bodyWhen body provided

Accepted media types

📘

Note

Any media file sent through the Sinch WhatsApp API will be processed before it's sent to the recipient.
While the maximum file size for every uploaded media is 100 mb, be aware that the file can be compressed to meet the post-processing limits listed below.

Message typeSupported content typesPost-processing size limit
documentAny content type listed for other message types,
text/plain, text/csv, application/pdf, application/msword, application/x-tar, application/rtf.0, application/vnd.ms-powerpoint,
application/vnd.openxmlformats-officedocument.presentationml.presentation,
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.oasis.opendocument.presentation,
application/vnd.oasis.opendocument.spreadsheet,
application/vnd.ms-excel,
application/vnd.oasis.opendocument.text
100 MB
imageimage/jpeg, image/png5 MB
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg, audio/opus16 MB
videovideo/mp4, video/3gpp16 MB
stickerimage/webp100 KB

📘

Note

Video files must have H.264 video codec and AAC audio codec.

Formatting Text Messages

WhatsApp allows formatting your messages. Use these formatting symbols to format a message:

SymbolFormattingExample
Asterisk (*)BoldThis is *nice*.
Underscore (_)ItalicsShe said _yes_!
Tilde (~)StrikethroughWhat a ~rainy~ sunny day!
Three backticks (```)Code```print 'Success';```

To use emojis in text, encode them with UTF-16 unicode.

SymbolExample
:grinning:Hi \ud83d\ude00
:white-check-mark:\u2705 repair the car
:musical-keyboard:I like \uD83C\uDFB9

Supported language codes

Following language codes are supported for template messages

LanguageCode
Afrikaansaf
Albaniansq
Arabicar
Azerbaijaniaz
Bengalibn
Bulgarianbg
Catalanca
Chinese (CHN)zh_CN
Chinese (HKG)zh_HK
Chinese (TAI)zh_TW
Croatianhr
Czechcs
Danishda
Dutchnl
Englishen
English (UK)en_GB
English (US)en_US
Estonianet
Filipinofil
Finnishfi
Frenchfr
Germande
Greekel
Gujaratigu
Hausaha
Hebrewhe
Hindihi
Hungarianhu
Indonesianid
Irishga
Italianit
Japaneseja
Kannadakn
Kazakhkk
Koreanko
Laolo
Latvianlv
Lithuanianlt
Macedonianmk
Malayms
Malayalamml
Marathimr
Norwegiannb
Persianfa
Polishpl
Portuguese (BR)pt_BR
Portuguese (POR)pt_PT
Punjabipa
Romanianro
Russianru
Serbiansr
Slovaksk
Sloveniansl
Spanishes
Spanish (ARG)es_AR
Spanish (SPA)es_ES
Spanish (MEX)es_MX
Swahilisw
Swedishsv
Tamilta
Telugute
Thaith
Turkishtr
Ukrainianuk
Urduur
Uzbekuz
Vietnamesevi
Zuluzu

Click to WhatsApp

A business can provide a simple method via a Web Page, or embedded within a QR-Code to enable an end user to initiate a conversation through the WhatsApp Business API.
While not a specific endpoint of the WhatsApp Business API, this method has been tested to work.
From the businesses perspective, this avoids initial notification charges as the conversation is customer initiated.
Furthermore, because the customer care session is immediately activated, an implicit 24 hour opt-in enables the business to reply during that time period.

The business would be advised to obtain an explicit, compliant opt-in during that initial customer care session to enable the business to initiate a future conversation using a notification (Template)

Conversation start URL:

GET https://api.whatsapp.com/send

With path variable parameters:

NameDescriptionConstraintsRequired
phoneYour WhatsApp Business Account phone numberE.164 format without '+' sign. E.g. 447537453580Yes
textMessage content to be sent to your accountAny textNo

Example to open conversation with +44 7537 453580:

https://api.whatsapp.com/send?phone=447537453580

Example to send message with content "Text message content" to +44 7537 453580:

https://api.whatsapp.com/send?phone=447537453580&text=Text%20message%20content

Edit on GitHub

Updated about a month ago


What's Next

Get started today

REST API

Introduction


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.