Reference
This guide provides a mapping between the calls, fields, and functionalities used in the standalone WhatsApp API and the WhatsApp channel of the Conversation API. In order to ease the comparison process, this guide's organization reflects the organization of the standalone WhatsApp API documentation.
Opt-In-and-Outs
Note:
As of June 30th, 2022, the Sinch WhatsApp Business Messaging API does not check whether recipients have opted in before sending messages. It is the user's responsibility to ensure that the recipient has opted in before sending. The endpoints still function, but will not be used to allow or prevent message delivery. For more information on the opt-in and opt-out requirements for WhatsApp messages, see the WhatsApp Business Policy.
All Business initiated conversations via the Sinch WhatsApp Business API should start with an “Opt-In” by the user. This can be collected through any third party channel. For example in an SMS message, In-Line with a Web Form, in an Email, or even via a deep-link in print media.
Note
If a customer initiates contact with a WhatsApp Business, this will constitute as a temporary, 24-hour opt-in.
For more information on the opt-in and opt-out requirements for WhatsApp messages, see the WhatsApp Business Policy.
Callbacks
The Conversation API delivers contact messages, delivery receipts for app messages, and various notifications through callbacks. The sections below provide a mapping between the callback functionalities, callbacks, and callback fields of the standalone WhatsApp API and the Conversation API.
Signature
Conversation API callbacks can be signed when triggered by a registered webhook.
Delivery report callback
The table below provides a mapping between the standalone WhatsApp delivery report callback and the Conversation API message delivery report callback.
| Standalone field | Conversation API field |
|---|---|
statuses |
message_delivery_report (note that, while statuses is an array of delivery reports, message_delivery_report only represents one delivery report) |
status |
status |
state |
status |
message_id |
message_id |
details |
reason and/or metadata |
recipient |
channel_identity |
conversation |
message_metadata |
timestamp |
event_time |
errors |
reason |
Inbound message callback
The table below provides a mapping between the standalone WhatsApp inbound message callback and the Conversation API inbound message callback.
| Standalone field | Conversation API field |
|---|---|
contacts |
channel_identity (note that, while contacts is an array of contact information, channel_identity is an object that represents only one contact) |
notifications |
message (note that, while notifications is an array of inbound messages, message only represents a single message) |
Sub-fields in the contacts object
| Standalone field | Conversation API field |
|---|---|
profile |
N/A |
wa_id |
identity (under channel_identity) |
Sub-fields in the nofications object
| Standalone field | Conversation API field |
|---|---|
from |
identity (under channel_identity) or contact_id (depending on use case) |
to |
app_id and conversation_id |
replying_to |
N/A |
message_id |
id under message |
message |
contact_message |
type (under message) |
defined by the object immediately under the contact_message object |
Other fields vary depending on which message types were selected.
Mark as read
N/A
Blacklisting
N/A
WhatsApp Capability
The tables below provide a mapping between the standalone WhatsApp API capability request and the Conversation API capability request.
Endpoint mapping
| API | Endpoint |
|---|---|
| Standalone WhatsApp | GET whatsapp/v1/{bot-id}/capability or POST whatsapp/v1/{bot-id}/capability |
| Conversation API | POST https://{region}.conversation.api.sinch.com/v1/projects/{project_id}/capability:query |
Field mapping
| Standalone field | Conversation API field |
|---|---|
numbers |
recipient |
Note the following:
- When using the standalone WhatsApp API, you can include a list of numbers in a capability check. When using the Conversation API app, you can only include one recipient per call.
-
The results of a Conversation API capability check are delivered via webhook. You must be subscribed to the
CAPABILITYwebhook trigger.
Media Provider
N/A
Send messages
The tables below provide a mapping between the standalone WhatsApp API message endpoint and the Conversation API message endpoint. This includes mappings between endpoint addresses, message types, and fields. The mappings in this parent section apply to every send message request, whereas the mappings provided in the following sub-sections apply to the specific message type.
Note:
In addition to the tables below, and the documentation that exists for Conversation API message types, you can also use the Message Composer on the Sinch Customer Dashboard to help you construct Conversation API messages. You can use the Code editor to create template content using code samples, or you can use the Form or Visual editors to compose a message and then extract the snippet from the Code editor. This snippet can then be used to populate the message field of non-template messages.
Endpoint Mapping
| API | Endpoint |
|---|---|
| Standalone WhatsApp | POST whatsapp/v1/{bot-id}/messages |
| Conversation API | POST https://{region}.conversation.api.sinch.com/v1/projects/{project_id}/messages:send |
Message type mapping
| Standalone message type | Conversation API message |
|---|---|
template |
template_message with the channel_template field populated |
text |
text_message |
image |
media_message |
video |
media_message |
document |
media_message |
audio |
media_message |
location |
location_message |
contacts |
N/A |
sticker |
media_message or card_message |
interactive |
choice_message, card_message, and/or list_message |
For more interactive message type assignment information, see the interactive message section. For more information can be Conversation API message types, see the Conversation API message type documentation.
General field mapping
| Standalone field | Conversation API field |
|---|---|
to |
recipient (note that you can only specify one recipient per standard Conversation API call) |
message |
message |
callback |
callback_url |
Template message
If you are migrating from the standalone WhatsApp API to the Conversation API, you may have existing WhatsApp message templates that you want to use when sending messages. Standalone WhatsApp template messages have a direct mapping in the Conversation API in the form of WhatsApp channel-specific template messages. Our documentation on WhatsApp channel-specific template messages provides instructions on how to send WhatsApp template messages on the WhatsApp channel of the Conversation API, along with examples that demonstrate the structure of those messages.
Conversation API Omni-channel template messages
The Conversation API also allows you to create templates that can be used with any channel. These templates are used to send omni-channel template messages, and such messages can be sent on the WhatsApp channel of the Conversation API. It's important to note that approved WhatsApp templates are not the same as omni-channel templates. WhatsApp templates need to be approved by WhatsApp, and are not used on other Conversation API channels.
Text message
Standalone WhatsApp text messages can be mapped to Conversation API text messages by populating the text_message object.
| Standalone field | Conversation API field |
|---|---|
text |
text |
preview_url |
N/A |
Image message
Standalone WhatsApp image messages can be mapped to Conversation API media messages by populating the media_message object.
| Standalone field | Conversation API field |
|---|---|
url |
url |
caption |
N/A |
provider |
N/A |
Video message
Standalone WhatsApp video messages can be mapped to Conversation API media messages by populating the media_message object.
| Standalone field | Conversation API field |
|---|---|
url |
url |
caption |
N/A |
provider |
N/A |
Document message
Standalone WhatsApp document messages can be mapped to Conversation API media messages by populating the media_message object.
| Standalone field | Conversation API field |
|---|---|
url |
url |
filename |
N/A |
caption |
N/A |
provider |
N/A |
Audio message
Standalone WhatsApp audio messages can be mapped to Conversation API media messages by populating the media_message object.
| Standalone field | Conversation API field |
|---|---|
url |
url |
caption |
N/A |
provider |
N/A |
Location message
Standalone WhatsApp location messages can be mapped to Conversation API location messages by populating the location_message object.
| Standalone field | Conversation API field |
|---|---|
lat |
latitude under coordinates |
lng |
longitude under coordinates |
name |
title |
address |
title |
Sticker message
Standalone WhatsApp sticker messages can be mapped to Conversation API media messages by populating the media_message object.
| Standalone field | Conversation API field |
|---|---|
url |
url |
id |
N/A |
provider |
N/A |
Interactive message
There are several types of Interactive messages that can be sent using the standalone WhatsApp API. These message types are mapped to Conversation API message types, including choice messages, card messages, and list messages, below:
| Standalone message type | Conversaton API message |
|---|---|
button |
choice_message or card_message, depending on the type of header used in the button message. To recreate button messages with a text header, use choice_message. To recreate button messages with any other type of header, use card_message. |
list |
list_message, specifying choice at the items level. |
product |
list_message, specifying product at the items level, and in which only one product is specified. |
product_list |
list_message, specifying product at the items level. |
Stickerpack management
N/A
