JATIS MOBILE

WhatsApp Business Protocol

TECHNICAL SPECIFICATION DOCUMENT

VERSION AUTHOR and REVIEWER
Version 3.9.0 Boby Juliyanto
Lorensius Simanjuntak

FILE NAME -
WhatsApp Business Protocol v3.9.0

Technical Specification DATE 5/2/2023 Page 2 of 64

5:19:00 PM
CONFIDENTIAL & PROPRIETARY
For Internal Use Only
Print Date: 05/02/23 5:19 PM
WhatsApp Business Protocol Confidential Jatis Mobile

1 Document Information
1.0 Purpose
This document provides complete Protocol technical specification for Jatis’s WhatsApp Interactive
Service

1.1 Target Audience

IT staff. Basic knowledge of the various technology used in the project are required.

1.2 Document Update History

Version Editor Reviewer Change Summary

3.0 Lorensius Simanjuntak Boby Juliyanto Add guidelines on webhooks
(11 Dec 2018)
3.1 Lorensius Simanjuntak Boby Juliyanto Remove Send end point on sending
(25 Feb 2019) messages URL path
3.2 Boby Juliyanto Lorensius Simanjuntak Adding application settings API
(14 Jun 2019)
3.3 Boby Juliyanto Lorensius Simanjuntak Adding “Read Mark” API
(8 Jul 2019)
3.4 Boby Juliyanto Lorensius Simanjuntak Adding send media messages with URL.
(10 Sep 2019)
3.4.1 Boby Juliyanto Lorensius Simanjuntak • Adding health API
(25 Oct 2019)
3.5.0 Boby Juliyanto Lorensius Simanjuntak Message Templates (Media)
(17 Apr 2020)
3.5.1 Boby Juliyanto Lorensius Simanjuntak Message Templates (HSM text)
(2 Jun 2020)
3.5.2 Boby Juliyanto Lorensius Simanjuntak • Message Templates for Button
(24 Jun 2020) • Sticker
3.5.3 Boby Juliyanto Lorensius Simanjuntak • Webhooks for incoming interactive
(25 Aug 2021) message
• Messages API for button and menu
interactive message
• Check contact API
• WA to SMS reroute status
3.5.4 Boby Juliyanto Lorensius Simanjuntak • Sequence diagram
(16 Dec 2021)
3.6.1 Boby Juliyanto Lorensius Simanjuntak • Upload Media API
(7 Mar 2021)
3.7.0 Boby Juliyanto Lorensius Simanjuntak • Replace HSM with Template as it will
(16 Mar 2021) be deprecated
3.7.1 Boby Juliyanto Lorensius Simanjuntak • Cloud API converter
(5 Dec 2022)
3.8.0 Boby Juliyanto Lorensius Simanjuntak • Product catalog
(6 Dec 2022)
3.9.0 Boby Juliyanto Lorensius Simanjuntak • New pricing info (page 12)
(2 May 2023)

Page 3 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

2 Webhooks
Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger
event occurs, the Jatis WhatsApp API sees the event, collect the data, and immediately sends a
notification (HTTP Request) to the webhook URL specified by client updating the status of sent messages
or indicating when you receive a message.

When a customer sends you a message, the Jatis WhatsApp API will send an HTTP POST request
notification to the webhook URL with the details that are described in the following sections:
- Inbound Message Notifications
- Inbound Media Message Notifications
- Outbound Message Status Notifications
- Parameter/Field Descriptions for Inbound Messages

2.0 Inbound Message Notifications

You will receive a notification when your WhatsApp Id received a message. The messages object section
below will covers all the information you may receive about an incoming message.

Example: Text Message Received

The following is an example of a text message you received from a customer. See the text object section
below for more information

{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1518694235",
"text": {
"body": "Hello this is an answer"
},
"type": "text"
}]
}

Page 4 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Static Location Message Received

The following is an example of a message you received from a customer specifying their static location.
See the location object section below for more information.

{
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"location":{
"latitude":38.9806263495,
"longitude":-131.9428612257
},
"timestamp":"1521497875",
"type":"location"
}]
}

2.1 Inbound Media Message Notifications

When a message with media is received, the Jatis WhatsApp API will download the media. A notification
is sent to your webhook once the media downloaded. This message contains information that identifies
the media object and enables you to find and retrieve the object. Use download endpoint at media node
with the media’s id to download the media.

Page 5 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Message with Image received

The following is an example inbound message that contains an image. See the media object section below
to learn more about the different media types.

{
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image":{
"id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type":"image/jpeg",
"caption": "Check out my new phone!"
},
"timestamp":"1521497954",
"type":"image"
}]
}

The caption field is optional for media messages. It is only included if the user has set the caption.

Example: Message with Document Received

The following is an example inbound message that contains a document. See the media object section
below to learn more about the different media types.

{
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp":"1522189546",
"type":"document",
"document":{
"caption":"80skaraokesonglistartist",
"id":"fc233119-733f-49c-bcbd-b2f68f798e33",
"mime_type":"application/pdf"
}
}]
}

Page 6 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Message with Voice Message Received

The following is an example inbound message that contains a voice message. See the media object
section below to learn more about the different media types.

{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1521827831",
"type": "voice",
"voice": {
"id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
"mime_type": "audio/ogg; codecs=opus"
}
}]
}

2.2 Interactive Message Notifications

An interactive object is found in webhooks related to interactive messages, including List Messages,
Reply Button, and Place Order inbound messages. This object contains the following components:

Name Description

type Required for list_reply.

Supported values:

• list_reply for List Messages

• button_reply for Reply Button Messages

list_reply Used to notify you when customers are replying to List Messages.

Contains the following information about the rows selected by the

customer: id, title, and description.

button_reply Used to notify you when customers are replying to Quick Reply Messages.

Contains the following information about the button clicked by the

customer: id and title.

Page 7 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Customer Replied to a List Message

{
"messages": [ {
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"title": "row-title-content-here",
"id": "unique-row-identifier-here",
"description": "row-description-content-here"
}
}
}

Example: Customer Replied to a Reply Button Message

{
"messages": [
{
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "unique-button-identifier",
"title": "button-text"
}
} # end interactive node
} # end message item
] # end messages array
}

Page 8 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Customer click the place order in shopping cart page.

{
"messages": [ {
"from": "customer-whatsapp-id",
"group_id": "group-id",
"id": "message-ID",
"timestamp": "message-timestamp",
"type": "order"
"order": {
"catalog_id": "catalog_id",
"product_items": [
{
"product_retailer_id":"product-ID",
"quantity":"number-of-items",
"item_price":"unitary-price-of-item",
"currency":"price-currency"
},
...
],
"text":"text-message-sent-along-with-the-order"
}
}
}

2.3 Message Status Notifications

Message status notifications provided information about the state of your messages.
This section covers:
- Message Status Notifications
- Message Status Notifications Parameters

Message Status Notifications

The Jatis WhatsApp API will send notifications to inform you of the status of the messages between you
and users. When a message is sent successfully, you will receive notification when the message is sent,
delivered, and read. The order of these notifications in your app may not reflect the actual timing of the
message status. View the timestamp to determine the timing, if necessary. The notifications you may
receive are:

o sent – your sent message was received by the server

o delivered – your sent message was delivered to user’s device

Page 9 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

o read – your sent message was read by the user. Read notifications will only be available for
those users that have read receipts enabled. For users that do not have it enabled, you will only
receive the delivered notification.
o failed – your message was failed to send. Reason for failure will be included in the callback
o Success reroute to sms – your message was failed to send but successfully re-route to
SMS.

Example: Message Sent

{
"statuses":[{
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"recipient_id": "16315555555",
"status": "sent",
"timestamp": "1518694700"
}]
}

Example: Message Delivered

{
"statuses":[{
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"recipient_id": "16315555555",
"status": "delivered",
"timestamp": "1518694708"
}]
}

Example: Message Read

{
"statuses":[{
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"recipient_id": "16315555555",
"status": "read",
"timestamp": "1518694722"
}]
}

Page 10 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Example: Message Success reroute to SMS

{
"statuses":[{
"id": "qIL4bA5RRSOb73nas7KawEl6",
"sms_message_id": "5Y44bLRQHOS0kQz1NhMngvGi",
"recipient_id": "6287825735522",
"status": "Success reroute to sms",
"timestamp": "1630256497"
}]
}

Example: Status message failed (code 480)

{
"statuses": [{
"errors": [{
"code": 480,
"title": "Failed to send message since we detect an identity change of
the contact"
}],
"id": "gBGGFjFVU2AfAgldhhKwWDGSrTs",
"recipient_id": "16315553601",
"status": "failed",
"timestamp": "1602535356"
}]
}

Message Status Notifications Parameters

When you send a message to a user and have your webhook configured, you will receive status updates
letting you know when the message is sent, delivered, and when it was read by the user. There are fields
that comprise the status message.

The statuses object

The statuses object will keep you apprised of the status of messages between you and users.

Page 11 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name
Description Type

id Message ID String

recipient_id WhatsApp ID of recipient String

status Status of message: read, delivered, sent or failed. String

timestamp Timestamp of the status message String

sms_message_id SMS Message ID (only for rerouted messages to SMS) String

All Possible Message Statuses

This table lists all possible options for the status of the message.

Status Description WhatsApp Mobile

Equivalent

Sent Message received by WhatsApp server One checkmark

Delivered Message delivered to recipient Two checkmarks

Read Message read by recipient Two blue checkmarks

Failed Message failed to send Red error triangle

Success reroute to Message failed to send but successfully -

sms reroute to SMS

Pricing Updates
Starting June 1, 2023, the conversation and pricing object in your outbound notifications will have
new conversation and pricing categories, the business-initiated category will be replaced by:

• Utility conversations - Facilitate a specific, agreed-upon request or transaction or update to a

customer about an ongoing transaction, including post-purchase notifications and recurring billing
statements

Page 12 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

• Authentication conversations - Enable businesses to authenticate users with one-time passcodes,

potentially at multiple steps in the login process (e.g., account verification, account recovery,
integrity challenges)
• Marketing conversations - Include promotions or offers, informational updates, or invitations
for customers to respond / take action. Any conversation that does not qualify as utility or
authentication is a marketing conversation.

And the user-initiated category will be replaced by Service Conversations.

The following webhook will be received when a business sends a message as part of a Service
Conversations (if that conversation did not originate in a free entry point):

{
"statuses": [{
"id": "3A0C810BBE72C289F9CD",
"recipient_id": 6281384438846,
"status": "sent",
"timestamp": 1518694236,
"type": "message",
"conversation": {
"id": "conversation-ID",
"expiration_timestamp": 1518780636,
"origin": {
"type": "service"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "service"
}
}]
}

The following webhook will be received when a business sends a message as part of a Utility
Conversations:

{
"statuses": [{
"id": "3A0C810BBE72C289F9CD",
"recipient_id": 6281384438846,
"status": "sent",
"timestamp": 1518694236,
"type": "message",
"conversation": {
"id": "532b57b5f6e63595ccd74c6010e5c5c7",
"expiration_timestamp": 1518780636,

Page 13 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

"origin": {
"type": "utility"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "utility"
}
}]
}

The following webhook will be received when a business sends a message as part of a Authentication
Conversations:

{
"statuses": [{
"id": "3A0C810BBE72C289F9CD",
"recipient_id": 6281384438846,
"status": "sent",
"timestamp": 1518694236,
"type": "message",
"conversation": {
"id": "532b57b5f6e63595ccd74c6010e5c5c7",
"expiration_timestamp": 1518780636,
"origin": {
"type": "authentication"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "authentication"
}
}]
}

The following webhook will be received when a business sends a message as part of a Marketing
Conversations:

{
"statuses": [{
"id": "3A0C810BBE72C289F9CD",
"recipient_id": 6281384438846,
"status": "sent",

Page 14 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

"timestamp": 1518694236,
"type": "message",
"conversation": {
"id": "532b57b5f6e63595ccd74c6010e5c5c7",
"expiration_timestamp": 1518780636,
"origin": {
"type": "marketing"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "marketing"
}
}]
}

The following webhook will be received when a business sends a message in reply to a Service
Conversation originating from free entry points:

{
"statuses": [{
"id": "3A0C810BBE72C289F9CD",
"recipient_id": 6281384438846,
"status": "sent",
"timestamp": 1518694236,
"type": "message",
"conversation": {
"id": "532b57b5f6e63595ccd74c6010e5c5c7",
"expiration_timestamp": 1518780636,
"origin": {
"type": "referral_conversion",
}
},
"pricing": {
"pricing_model": "CBP",
"billable": false,
"category": "referral_conversion"
}
}]
}

Page 15 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Parameter/Field Descriptions for Inbound Messages

as shown in the examples contained within this document, notifications of received messages are
contained within a messages object. The tables in this section describe the fields in the inbound
notifications.

Name Description Type

Messages Messages Object Array of any type of message objects

The messages object provides all of the information about the incoming message.

Name Description Type

From WhatsApp ID of the sender String

Id Message ID String

Timestamp Message received timestamp String

Type Message type. Values String

include: audio, document, ima
ge,location, text, video, vo
ice

audio, document, image, lo Message contents Message objects that provide

cation, text, video, voice more information about the
objects received message.

Page 16 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

The text object

When the notification describes a text message, the text object provides the body of the text message.

Name Description Type

Body Message text String

The location object

When you receive a notification of a user’s static location, the location object provides the details of the
location.

Name Description Type

Latitude Latitude of location being sent Number

Longitude Longitude of location being sent Number

The media objects (image|document|audio|video|voice) objects

When message with media is received, the Jatis WhatsApp API will download the media. Once the media
is downloaded, a notification is sent to your webhook. This message contains information that identifies
the media object enables you to find and download the object.

Name Description Type

caption Optional. Only present if specified. String

id ID of the media. Can be used to delete the media if stored locally String
on the client.

mime_type Mime type of media String

Page 17 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

2.4 Marking Messages as Read

You can use the messages node to change the status of incoming message to read.

Request
The message_id indicated is the id provided in the inbound notification

PUT /wa/messages/message-id

{
"status": "read"
}

Parameters

Name Required Description

status Yes Updating status to read is applicable only for incoming messages.

Response

null # or {}

Page 18 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3 Reference

3.0 Base URLs

Currently we have two base URLs for WhatsApp Business API (WABA) endpoint with on-premises
setup basis:
1. https://interactive.jatismobile.com/wa/
2. https://interactive.jatismobile.com/v1/
Since the Cloud API version of WABA endpoint is already live in Jatis production, we provide another
endpoint to facilitate clients that need to migrate to Cloud API but don’t want to change anything in the
payload. The endpoint is:
• https://interactive.jatismobile.com/v2/
Please contact our Account Executive or Customer Service if you wish to migrate from on-premise setup
to Cloud API and use this endpoint for your solution.

3.1 Users

/wa/users
Use the users node for managing authentication and accessing the Jatis WhatsApp API.

Developers and/or system administrators can perform the following actions:

- Log into the Jatis WhatsApp API and get an authentication token

Page 19 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

/wa/users Endpoints

Name Action Returns

POST Log in to get your A users object containing the

/wa/users/login authentication token authentication token and the expiration
date of the token

To authenticate your self with Jatis WhatsApp API, you must log in. To login you send your username
and password basic authentication and receive a bearer token in response. You then use the bearer token
for authentication when sending request to any Jatis WhatsApp API endpoint.

This section covers:

- Authentication
- Login Requests
- Login Responses
- Tokens

Authentication
To use the Jatis WhatsApp API, you must authenticate yourself. Only users with valid authentication
tokens can access the service.

Login Requests
Jatis will provide you username and password. You will authenticate yourself using basic authentication
(username,password) when you login. The Authorization is set in the HTTP header. The type is
Basic and the credentials are a base64-encoded string consisting of the given username and
password joined with a colon (i.e., username:password).

Authentication Header
Many client software app (e.g., Postman) will take the username:password parameter and build the
authentication header automatically. If you need to build it yourself, here are the basic steps:
1. Create the username:password string
2. Use your favorite tool to base64-encode the string
For example, your username and password string is admin:secret, the base64-encoding for this is
YWRtaW46c2VjcmV0, so the user credentials will be Authorization: Basic
YWRtaW46c2VjcmV0.

Standard Login

Page 20 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

After you prepare the user credentials, you can use a standard login for the Jatis WhatsApp API, which
should look like:

POST /wa/users/login

Authorization: Basic base64(username:password)

The cURL version should look like:

curl -X POST \
-H 'Authorization: Basic base64(username:password)' \
-H 'Content-Type: application/json' \
-d '{}' \
https://{{BASE-URL}}/users/login

Login Responses
When your login request id received by the Jatis WhatsApp API, your credentials are processed for
validation.

- If successful, your token is generated. The response contains your token in the token field.

- If not successful, an error is returned

Success
On success, a status of 200 Ok is returned, along with the token and token expiration time. All generated
tokens expired in 7 days.

The response will look like the following example:

{
"users": [{
"token": "eyJhbGciOHlXVCJ9.eyJ1c2VyIjoNTIzMDE2Nn0.mEoF0COaO00Z1cANo",
"expires_after": "2018-03-01 15:29:26+00:00"
}]

Page 21 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Parameters:

Field Required Default Value/Description

Token Yes Authentication token to be used for all other Jatis

WhatsApp API calls. The token must be sent in the
authorization header in the format:
Authorization: Bearer <authentication-
token>

expires_after Yes Token expiration timestamp. By default, this is 7 days.

Tokens
For your initial login, use your username and password for basic authentication. For all other secure
transactions, you must use the bearer token that is returned after a successful login.

Usage
The tokens are sent in the authorization header of the HTTP request for many of the Jatis WhatsApp API
calls. In particular, notice in the following example that the type of authorization that is used with this is
token Bearer.

HTTP-METHOD /secured-path

Authorization: Bearer your-auth-token

For all secured paths, we validate the token. During the validation, if the token is found to be expired, that
token is removed from the system. Upon successful validation, the request is allowed to proceed.

Expiration
You can use your token for authentication until the token expires. Tokens are set to expire after a default
time, such as 7 days. The expires_after parameter in the response provides the expiration date for
the token. Login again to generate a new token.

Page 22 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.2 Media

/wa/media

Use the media node to upload and retrieve media

The media file must be uploaded to the media storage on Jatis server. Once the upload is complete, you
can send a message using the media ID.
This section covers:
- Uploading Media
- Retrieving Media

Uploading Media

To upload media to the Jatis WhatsApp API, use the media node. The POST body must contain the
binary media data and the Content-Type header must be set to the type of media being uploaded.
See the Supported File Types section for information about supported file types. Note: the maximum file
size for uploaded media is 64MB.
Sending binary data in a POST HTTP request is a standard way of uploading binary data. If you want to
upload an image, for example, you issue a POST request with the actual image bytes in the payload.

Request

Uploading media:

POST /wa/media/upload
Content-Type: image/jpeg or other appropriate media type

binary-media-data

Uploading media with cURL:

curl -X POST \
https://{{BASE-URL}}/media/upload \
-H 'Authorization: Bearer your-auth-token' \
-H 'Content-Type: image/jpeg' \ # or other appropriate media type
--data-binary @your-file-path

Response

Page 23 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

A successful response returns the id field, which is the information you need for downloading media files
and sending a media message to your customers.

{
"media": [
{
"id": "f043afd0-f0ae-4b9c-ab3d-696fb4c8cd68"
}
]
}

Supported file types

Media Supported File Types

Document PDF, DOC(X), PPT(X), XLS(X)

Image JPG, JPEG, PNG

Audio AAC, AMR, MP3, OGG, OPUS

Downloading Media
Downloading media is particularly useful when a user has uploaded an image that is sent to your
webhook. When a message with media is received, the Jatis WhatsApp API will download the media.
Once the media is downloaded, you will receive a notification through your webhook. Use the media ID
found in the notification to download the media.

Request

Page 24 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

GET /wa/media/download?media_id={{media-id}}

Or

GET /v1/media/{{media-id}}

For example, using the example image uploaded in the previous section:

curl -X GET \
https://interactive.jatismobile.com/wa/media/download?media_id=f043afd0-f0ae-
4b9c-ab3d-696fb4c8cd68 \
-H 'Authorization: Bearer your-auth-token'

Or

curl -X GET \
https://interactive.jatismobile.com/v1/media/f043afd0-f0ae-4b9c-ab3d-
696fb4c8cd68 \
-H 'Authorization: Bearer your-auth-token'

To send this example media to a file, use the -o parameter, as shown below:

curl -X GET \
https://interactive.jatismobile.com/wa/media/download?media_id=f043afd0-f0ae-
4b9c-ab3d-696fb4c8cd68 \
-H 'Authorization: Bearer your-auth-token' \
-o path/filename

Or

curl -X GET \
https://interactive.jatismobile.com/v1/media/f043afd0-f0ae-4b9c-ab3d-
696fb4c8cd68 \
-H 'Authorization: Bearer your-auth-token' \
-o path/filename

Page 25 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Response

If successful, you will see a response containing a 200 OK status and the binary data you downloaded.

Content-Type: image/jpeg or other appropriate media type

Content-Length: content-size

binary-media-data

If you used tool like postman, you will see the image that was downloaded. If you are using a command
line tool, you will see the binary data that was downloaded. If you sent the data to a file, you will see the
image in your file browser.

3.3 Contacts

/v1/contacts

Use the contacts node to manage WhatsApp users in your database by validating them before
sending messages and verify a user's identity with identity hashes.

With the contacts node you can:

• Verify that a phone number in your database belongs to a valid WhatsApp account. You
must ensure that the status is valid before you can message a user.
• Get the WhatsApp ID for a phone number. WhatsApp IDs are needed to send messages and
user notifications.

Constraints

• If you check too many phone numbers without sending messages to them, you will be
banned. Only check only phone numbers critical to your business for which you have already
received customer opt-in.
• At this time, there is no callback to inform you when a WhatsApp user joins or leaves the
network, so you must check contacts frequently.

Page 26 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Creating

Before sending messages to users who have opted in, send a POST API call to /v1/contacts to
create a WhatsApp account user validation request. In your call, include a list of phone numbers you
want to validate.

Example

Send an API call to /v1/contacts containing an array of registered phone numbers. The phone
numbers can be in any standard telephone number format.

POST /v1/contacts
{
"blocking": "wait" | "no_wait",
"contacts": [
"16315551000",
"+1 631 555 1001",
"6315551002",
"+1 (631) 555-1004",
"1-631-555-1005"
],
"force_check": false | true
}

You will receive a response with the current status of the requested numbers and their WhatsApp
IDs (wa_id):

{
"contacts": [ {
"wa_id": "16315551000",
"input": "16315551000",
"status": "valid"
},
{
"wa_id": "16315551001",
"input": "+1 631 555 1001",
"status": "processing" # Only applicable when request is non-blocking
},
{
"input": "6315551002",
"status": "invalid"
},
{
"input": "+163155588",
"status": "failed"
}

Page 27 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Save the WhatsApp IDs for those numbers that returned a status of valid. Valid users are those
with a WhatsApp account. Use the WhatsApp IDs to send messages and notifications.

Repeat these steps on a regular basis to manage your list of valid users. The results are cached in
the WhatsApp Business API client's database for 7 days.

Parameters

The following parameters are supported for POST calls to /v1/contacts:

Name Description

blocking Optional.
Whether the API request should wait for processing to complete or not
before returning a response. For more information, read
the Blocking section below.

Possible values: no_wait (default), wait

contacts Required.
Array of phone numbers that you are validating.

The numbers can be in any standard telephone number format. The

recommended format for contact phone numbers is with a plus sign (+)
and the country code. For more information, see the Phone Number
Formats section below.

force_check Optional.
Whether to check the contacts cache or not. Contact information is
normally cached for 7 days. By setting the force_check parameter
to true, the cache will be bypassed ensuring a check is performed.

Possible values: false (default), true

Blocking
There are two options for the blocking parameter: no_wait and wait. If the blocking parameter
is not specified in a call it is no_wait by default.

Page 28 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

The blocking parameter determines whether the request should wait for the processing to
complete (synchronous) or not (asynchronous).

Setting Description

no_wait The processing of the phone numbers is asynchronous.

The API response may include some numbers with status set
to processing. If that happens, we recommend you follow these steps:

1. You get an API response with some numbers marked

as processing.
2. Issue another check contact request including the numbers with
the processing status.
3. If the processing is done in your new request, you get a correct
status for that number (valid or invalid).
4. If you still see numbers marked as processing, repeat step 2
until you have an answer for each number.

wait The processing of the numbers is synchronous. You see the final status
for all of the contacts after syncing with server. This setting makes the
query block wait until the numbers have all been checked before returning
results. This might take some time.

Phone Number Formats

The phone numbers in the contacts API request can be in any dialable format.

When there is no plus sign (+) at the beginning of the phone number, the country code is determined
using the phone number that your WhatsApp Business API client is registered under, so phone
numbers associated with a different country code will fail.

The recommended best practice is to always specify the country code with the phone number and
explicitly prefix it with a plus sign (+).
Here are some examples that demonstrate this behavior, assuming the WhatsApp Business API
client is registered with an Indian phone number (i.e., country code is +91):

Phone Number Translated Phone Number Valid?

"+1-631-555-1002" "+16315551002" Yes

"6315551002" "+916315551002" No

Page 29 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Phone Number Translated Phone Number Valid?

"1-631-555-1002" "+9116315551002" No

"+1 (516) 283-7151" "+15162837151" Yes

"+54 9 11 5612-1008" "+5491156121008" Yes

Returned Fields

The contacts response payload contains the same array of phone numbers sent in the request with
the input, status, and wa_id properties:

Name Description

input The value you sent in the contacts field of the API call.

status Status of the user.

Possible values:

• processing — Input is still being processed

• valid — A valid WhatsApp user
• invalid — Not a valid WhatsApp user
• failed — There was an error processing this check

wa_id WhatsApp user ID that can be used in other API calls. Only returned if
the status is valid

Along with the processing status, you should see an HTTP status of 200 OK. If there are any
errors in the response, see Error and Status Messages for more information.

Best Practices

We recommend checking contacts before sending messages, however you do not need to check
contacts when responding to incoming customer messages as you can immediately respond using
the provided wa_id. There is no additional cost as results are cached.

Page 30 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.4 Messages

/wa/messages

Use the messages node to send text messages, media/documents to your customers.

This section covers:

- Sending Text Messages
- Sending Media/Documents Messages

3.4.1 Sending Text Messages

/wa/messages

Use the messages endpoint to send text messages to your customers.

Request

After you have the WhatsApp ID for the user you want to message, use it to send a text message. A text
message can be max of 4096 characters long.

POST /wa/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "text",
"text": {
"body": "your-text-message-content"
}
}

Parameters

Name Required Description

Page 31 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Required Description

recipient_type Yes Default: individual

Determines whether the recipient is an individual

To Yes When recipient_type is individual, this field is the

WhatsApp ID (phone number) that the message will send to.

Type Yes Default: text

Text Yes Contains the body field

The text object

Name Required Description

Body Yes The text of the text message.

Response

A successful response includes a messages object with an identifier for the newly created message.

{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}

3.4.2 Sending Media/Documents Messages

/wa/messages

Use the messages endpoint to send messages containing audio, video, images, or documents to your
customers.

POST /wa/messages

Page 32 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "audio" | "document" | "image" | "video" | "sticker",

"audio": {
"link": "http(s)://the-url.mp3"
}

"document": {
"link": "http(s)://the-url.pdf",
"caption": "your-document-caption"
}

"image": {
"link": "http(s)://the-url.jpg",
"caption": "your-image-caption"
}

"video": {
"link": "http(s)://the-url.mp4",
"caption": "your-video-caption"
}

"sticker": {

"link": "http(s)://the-url.webp"

The audio, document, image, video, and sticker objects

Name Required Description

recipient_type Yes Default: individual (default).

To Yes When recipient_type is individual, this field is the

WhatsApp ID (phone number) that the message will send to.

Page 33 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Required Description

Type Yes Options: image, audio, document, video, sticker

link Yes The protocol and URL of the media to be sent. Use only with
HTTP/HTTPS URLs.

Page 34 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

caption No Describes the specified image, video or document media. Do not use
with audio and sticker media.

Response
The successful response includes a messages object with a message ID.

{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}

Page 35 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.4.3 Interactive Object Messages

The interactive object generally contains 4 main components: header, body, footer,
and action. Additionally, some of those components can contain one or more different objects:

• Inside header, you can nest media objects.

• Inside action, you can nest section and button objects.

Name
Description

type Required.
Supported values:

• list: Use it for List Messages.

• button: Use it for Reply Buttons.

header Optional.
Header content displayed on top of a message. See header object for more
information.

body Required.
The body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.

footer Optional.
The footer of the message. Emojis and markdown are supported.

Maximum length: 60 characters.

action Required.
Action you want the user to perform after reading the message.

The header Object

Name Description

type Required.
The header type you would like to use. Supported values are:

• text: Used for List Messages and Reply Buttons.

• video: Used for Reply Buttons.
• image: Used for Reply Buttons.

Page 36 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Description

• document: Used for Reply Buttons.

text Required if type is set to text.

Text for the header. Formatting allows emojis, but not markdown.

Maximum length: 60 characters.

video Required if type is set to video.

Contains the media object for this video.

image Required if type is set to image.

Contains the media object for this image.

document Required if type is set to document.

Contains the media object for this document.

The body Object

Name Description

text Required.
The body content of the message. Emojis and markdown are supported. Links
are supported.

Maximum length: 1024 characters.

The footer Object

Name Description

text Required if the footer object is present.

The footer content. Emojis and markdown are supported. Links are supported.

Maximum length: 60 characters

The action Object

Name Description

Page 37 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Description

button Required for List Messages.

Button content. It cannot be an empty string and must be unique within the
message Does not allow emojis or markdown.

Maximum length: 20 characters.

buttons Required for Reply Button Messages.

A button can contain the following parameters:

• type: only supported type is reply (for Reply Button Messages)

• title: Button title. It cannot be an empty string and must be unique
within the message. Does not allow emojis or markdown. Maximum
length: 20 characters.
• id: Unique identifier for your button. This ID is returned in the webhook
when the button is clicked by the user. Maximum length: 256
characters.

sections Required for List Messages.

Array of section objects. There is a minimum of 1 and maximum of 10.
See section object.

The section Object

Name Description

title Required if the message has more than one section.

Title of the section.

Maximum length: 24 characters.

rows Required for List Messages.

Contains a list of rows.
Each row must have a title (Maximum length: 24 characters) and
an ID (Maximum length: 200 characters). You can add
a description (Maximum length: 72 characters), but it is optional.

Example:

"rows": [

Page 38 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Description

"id":"unique-row-identifier-here",

"title": "row-title-content-here",

"description": "row-description-content-here",

Example

Interactive messages (lists):

POST /v1/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "interactive",
"interactive":{
"type": "list",
"header": {
"type": "text",
"text": "your-header-content-here"
},
"body": {
"text": "your-text-message-content-here"
},
"footer": {
"text": "your-footer-content-here"
},
"action": {
"button": "cta-button-content-here",
"sections":[
{
"title":"your-section-title-content-here",
"rows": [
{
"id":"unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here",
}
]
},
{
"title":"your-section-title-content-here",

Page 39 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

"rows": [
{
"id":"unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here",
}
]
},
...
]
}
}

Interactive messages (reply buttons):

POST /v1/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "interactive",
"interactive": {
"type": "button",
"header": { # optional
"type": "text" | "image" | "video" | "document",
"text": "your text"
# OR
"document": {
"id": "your-media-id",
"filename": "some-file-name"
}
# OR
"document": {
"link": "the-provider-name/protocol://the-url",
"provider": {
"name": "provider-name",
},
"filename": "some-file-name"
},
# OR
"video": {
"id": "your-media-id"
}
# OR
"video": {
"link": "the-provider-name/protocol://the-url",
"provider": {
"name": "provider-name"
}
}
# OR
"image": {
"id": "your-media-id"

Page 40 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

}
# OR
"image": {
"link": "http(s)://the-url",
"provider": {
"name": "provider-name"
}
}
}, # end header
"body": {
"text": "your-text-body-content"
},
"footer": { # optional
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "unique-postback-id",
"title": "First Button’s Title"
}
},
{
"type": "reply",
"reply": {
"id": "unique-postback-id",
"title": "Second Button’s Title"
}
}
]
} # end action
} # end interactive

Page 41 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Interactive messages (multi-product messages):

Multi-product message example

Page 42 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Menu triggered when user clicks on Start Shopping button.

Multi-product payload example:

Page 43 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

POST /v1/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "interactive",
"interactive":
{
"type": "product_list",
"header":{
"type": "text",
"text": "text-header-content"
},
"body":{
"text": "text-body-content"
},
"footer":{
"text":"text-footer-content"
},
"action":{
"catalog_id":"catalog-id",
"sections": [
{
"title": "the-section-title",
"product_items": [
{ "product_retailer_id": "product-SKU-in-catalog" },
{ "product_retailer_id": "product-SKU-in-catalog" },
...
]},
{
"title": "the-section-title",
"product_items": [
{ "product_retailer_id": "product-SKU-in-catalog" }
...
]},
...
]
},
}
}

Page 44 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Interactive messages (single-product messages):

Single product message example

Page 45 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Product detail page example.

Single product payload example:

POST /v1/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "interactive",
"interactive": {
"type": "product",
"body": {
"text": "text-body-content"
},

Page 46 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

"footer": {
"text": "text-footer-content"
},
"action": {
"catalog_id": "catalog-id",
"product_retailer_id": "product-SKU-in-catalog"
}
}
}

Shopping cart page example.

When user hit Place Order button, an inbound message will be sent to webhook. Click here to see
the webhook example of the place order action.

Page 47 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.4.4 Sending Media Message Templates

Beginning with v3.5.0, media message templates expand the content you can send recipients
beyond the standard message template type to include media, headers, and footers using
a components object. The components object allows you to indicate the type of message and the
message's parameters.
Request

POST /v1/messages

"to": "recipient_wa_id",
"type": "template",
"template": {
"namespace": "your-namespace",
"language": {
"policy": "deterministic",
"code": "your-language-and-locale-code"
},
"name": "your-template-name",
"components": [
{
"type" : "header",
"parameters": [
# The following parameters code example includes several different possible
header types,
# not all are required for a media message template API call.
{
"type": "text",
"text": "replacement_text"
}
# OR
{
"type": "document",
"document": {
"link": "the-provider-name/protocol://the-url",
# provider and filename are optional parameters
"provider": {
"name" : "provider-name"
},
"filename": "your-document-filename"
}

Page 48 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

}
# OR
{
"type": "image",
"image": {
"link": "http(s)://the-url",
# provider is an optional parameter
"provider": {
"name" : "provider-name"
},
}
}
]
# end header
},
{
"type" : "body",
"parameters": [
{
"type": "text",
"text": "replacement_text"
},
{
"type": "currency",
"currency" : {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33, #OR
"timestamp": 1485470276
}
},
{
...

Page 49 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

# Any additional template parameters

}
]
# end body
},
]
}
}

Parameters

Name Required Description

to Yes WhatsApp ID of the recipient

type No Set to template to send a media template

message

template Yes (For template messages) Contains all the template information

The template Object

Name Required Description

namespace Yes Namespace of the template

Note: Beginning with v2.27.8, this must be the namespace associated
with the WhatsApp business account that owns the phone number
associated with the current WhatsApp Business API client or the
message will fail to send

name Yes Name of the template

language Yes Specifies the language the template may be rendered in

Only the deterministic language policy works with media template
messages

components No Array containing the parameters of the message

The Components Object

Name Required Description

type Yes Describes the component type

Values: header, content, footer

parameters No Array containing the content of the message

The Parameters Object

Page 50 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Required Description

type Yes Describes the parameter type

Values: text, currency, date_time, image, document
The media types (image and document) follow the same format as those
used in standard media messages. Note: Only PDF documents are currently
supported for media message
templates. Note: The currency and date_time parameters
for template messages uses fallback_value in place of default. See
the Request sample above for an example.

Response
A successful response includes a messages object with an id.

"messages": [{

"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"

}]

An unsuccessful response will contain an error object that will contain an error string, error code and
other information.

Page 51 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.4.5 Sending Text Message Templates

/v1/messages

You can use the messages endpoint to send message templates to your customers. Use the
WhatsApp Manager to create your message templates.

Request
As with other messages, the message is sent to the /v1/messages endpoint. What's different about
sending message templates is the content of the message body specified with
the template parameter.

The template parameter contains a namespace and a name pair that identify a template and the
values to apply to variables in that template. Note: Beginning with v3.6.1,
the namespace and name parameters must match up or the message will fail to send.

The following code provides an example of sending a message template. This example uses
the purchase_with_credit_card element name within
the cdb2df51_9816_c754_c5a4_64cdabdcad3e namespace.

POST /v1/messages

{
"to": "whatsapp_id" | "whatsapp_group_id",
"type": "template",

"template": {
"namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
"name": "purchase_with_credit_card",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"components": [
{ "type": "body",
"parameters": [
{"type": "text",
"text": "$10" },
{"type": "text",
"text": "1234" }
]
}
]
}
}

The resulting message received by the customer will look like this:

You made a purchase for $10 using a credit card ending in 1234.

Page 52 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

As you can see from looking at the localizable parameters and the message the client received, the
template used the default value of 10 as the amount of the purchase and the default value of 1234
as the last numbers of the account.

Parameters

Name Required Description

type Yes (for The type of message being sent

message Options: text (default), image, audio, document, template
templates)

to Yes The WhatsApp ID or group ID to whom the message is being

sent

recipient_type No (Optional) Options: individual (default), group

template Yes (for The containing element for the message content — Indicates
message that the message is highly structured. Parameters contained
templates) within provide the structure.

The template Object

Name Required Description

namespace Yes The namespace that will be used

Note: Beginning with v2.2.7, if the namespace does not
match up to the element_name, the message will fail to
send

name Yes The template name that indicates which template to use
within the namespace
Note: Beginning with v3.6.1, if the name does not match
up to the namespace, the message will fail to send

language Yes Allows for the specification of a deterministic or fallback

language
The fallback option is deprecated with v2.27.8

components Yes This field is an array of values to apply to variables in the

template

Page 53 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Response

A successful response includes a messages object with an id.

{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}

An unsuccessful response will contain an error object that will contain an error string, error code and
other information.

3.4.6 Sending Interactive Message Templates

Interactive message templates expand the content you can send recipients beyond the standard
message template and media messages template types to include interactive buttons using
the components object.

There are two types of predefined buttons offered:

• Call-to-Action — Allows your customer to call a phone number and visit a website
• Quick Reply — Allows your customer to return a simple text message

These buttons can be attached to text messages or media messages. Once your interactive
message templates have been created and approved, you can use them in notification messages as
well as customer service/care messages.

Request

POST /v1/messages
{
"to": "recipient_wa_id",
"type": "template",
"template": {
"namespace": "your-namespace",
"language": {
"policy": "deterministic",
"code": "your-language-and-locale-code"
},
"name": "your-template-name",
"components": [
{
"type" : "header",
"parameters": [
{
"type": "text",
"text": "replacement_text"

Page 54 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

}
]
# end header
},
{
"type" : "body",
"parameters": [
{
"type": "text",
"text": "replacement_text"
},
{
"type": "currency",
"currency" : {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33, #OR
"timestamp": 1485470276
}
},
{
...
# Any additional template parameters
}
]
# end body
},

# The following part of this code example includes several possible

button types,
# not all are required for an interactive message template API call.
{
"type": "button",
"sub_type" : "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
# Business Developer-defined payload

"payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
},

Page 55 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

{
"type": "button",
"sub_type" : "url",
"index": "1",
"parameters": [
{
"type": "text",
# Business Developer-defined dynamic URL suffix
"text": "9rwnB8RbYmPF5t2Mn09x4h"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "2",
"parameters": [
{
"type": "text",
# Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}
]
}
}

Parameters

Name Required Description

to Yes WhatsApp ID of the recipient

type No Set to template to send a media template message

template Yes Contains all the template information

(For template messages)

The template object

Name Required Description

namespace Yes Namespace of the template

name Yes Name of the template

language Yes Specifies the language the template may be rendered in

components No Array containing the parameters of the message

Page 56 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

The components object

Name Required Description

type Yes Describes the component type

Values: header, body, footer, button

parameters No Array containing the content of the message

The parameters object

Name Required Description

type Yes Describes the parameter type

Values: text, currency, date_time, image, document, video, button
Note: The document media message template type is currently limited to
PDF format.
Note: The currency and date_time parameters for template messages
uses fallback_value in place of default. See the Request sample above
for an example.

The button type

Name Required Description

sub_type Yes Type of button being created

Values: quick_reply, url

index Yes Position index of the button

You can have up to 3 buttons using index values of 0-2

parameters Yes The parameters for the button, which are set at creation time in your
Business Manager

The sub_type parameter

Name Required Description

quick_reply No Refers to a previously created quick reply button that allows for the
customer to return a predefinied message

url No Refers to a previously created button that allows the customer to visit
the URL generated by appending the text parameter to the pre-
defined prefix URL in the template

The parameters object

Page 57 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Required Description

type Yes Indicates the type of parameter for the button

Values: payload, text

payload Yes Developer-defined payload that will be returned when the

(for quick_reply buttons) button is clicked in addition to the display text on the
button

text Yes (for url buttons) Developer provided suffix that will be appended to a
previously created dynamic URL button

Response
A successful response includes a messages object with an id.

{
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}

An unsuccessful response will contain an error object that will contain an error string, error code and
other information.

If a template is sent to an account that is incapable of receiving the template, the 1026
(ReceiverIncapable) error will be sent in the error object to the configured Webhook server.

Callback from a Quick Reply Button Click

When your customer clicks on a quick reply button, a response is sent. Below is an example of the
callback format.

Note: A customer may not click a button and either reply to the interactive message or just send you
a message. Make sure that you are able to support this type of scenario as well.

{
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16505551234"
}
],

Page 58 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

"messages": [
{
"button": {
"payload": "No-Button-Payload",
"text": "No"
},
"context": {
"from": "16315558007",
"id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
},
"from": "16505551234",
"id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
"timestamp": "1591210827",
"type": "button"
}
]
# If there are any errors, an errors field (array) will be present
"errors": [ { ... } ]
}

Page 59 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

3.5 Settings

/wa/settings

Use the settings node to configure the Jatis Whatsapp API.

Configurable settings include:

- Application Settings

/wa/settings Endpoints

Name Action Returns

PATCH Update multiple No application (payload)

/wa/settings/application application settings object

Application Settings

/wa/settings/application

Update or reset your application settings using API calls to the /wa/settings/application
endpoint.

Update Application Settings

To configure settings for the Jatis WhatsApp API, use the /wa/settings/application endpoint
with a JSON message body containing the field names and values to be set.

Request
Currently the API only support on updating or setting webhooks. When you need to set or if there is a
change in webhook URL, you can call this API.

PATCH /wa/settings/application
{
"webhooks": {
# see Webhooks Settings below
"url": "webhook.your-domain"
}
}

Parameters

Page 60 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Name Type Description

webhooks Webhooks URL for your Webhook

Object If the Webhook URL is not set, then callbacks will be dropped.
Callbacks are an important channel to deliver, both timely
notifications as well as out-of-band errors, and it is thus highly
recommended to configure the Webhook URL endpoint.
Example: https://spotless-process.glitch.me/webhook

Webhooks Parameters
The following table describes fields in the webhooks object in more detail

Name Type Description

url String Inbound and outbound notifications are routed to this URL. A HTTPS-based
endpoint is required; HTTP will not work. This URL may look like
this: https://spotless-process.glitch.me/webhook.

Response
A successful response is the HTTP status code 200 OK with a null or {} message body:

3.6 Health
/wa/health
Check the status of your WhatsApp Business API client with the health node. This node samples
the health of the gateway to the WhatsApp server and sends back a JSON response.
Request

GET /wa/health
{
Authorization: Bearer your-auth-token | Apikey your-api-key-token
}

Authorization
The health node supports Bearer token authenication similar to other WhatsApp Business API
nodes. However, if you wish to monitor the health status from an orchestrator, Bearer tokens are
not the best option for ongoing health checks as they expire every 7 days. To mediate this, you can
use an API key, which can be set using the WA_API_KEY environment variable in the waweb
environment section in the .yml file of your installation setup.

Page 61 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Note: The API key you set must have a minimum of 12 characters and a maximum of 128
characters.

services:
...
waweb:
...
environment:
...
WA_API_KEY: your-api-key-token

Response
The response will provide the status of the health of the gateway to the WhatsApp server. If
the Authorization header is not present or invalid, a 401 error code will be returned.

Single instance

{
"health": {
"gateway_status": "connected | connecting | disconnected | uninitialized |
unregistered"
}
}

High Availability/Multiconnect

{
"health": {
"your-hostname1:your-container-id1": {
"gateway_status": "connected | connecting | disconnected |
uninitialized | unregistered",
"role": "primary_master | secondary_master | coreapp"
},
"your-hostname2:your-container-id2": {
"gateway_status": "connected | connecting | disconnected |
uninitialized | unregistered",
"role": "primary_master | secondary_master | coreapp"
},
}
}

Note: In High Availability mode, only one Coreapp will be connected to the WhatsApp server, all
other nodes including the primary master will have a gateway_status of disconnected. In
Multiconnect mode with X shards, X Coreapps will be connected to the WhatsApp server, and the
primary master will also connect to the WhatsApp server.

Page 62 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

Parameters

Name Description Type

health The health object contains the fields that describe the health of Object
the WhatsApp Business API Client.

gateway_status Status of the connection between the Coreapp and WhatsApp String
servers.
Values:
• connected, connecting — The health is good.
• uninitialized — The application could be in the process
of upgrading or initializing the database schema. Try again in a few
minutes and contact Jatis Support if you continue to see this status.
• unregistered — You need to register your WhatsApp
Business API Client.

role Role of the container in High Availability/Multiconnect setups

Values: primary_master, secondary_master, coreapp.

Page 63 of 64 5/2/2023
WhatsApp Business Protocol Confidential Jatis Mobile

4 Sequence Diagram
Below is the detail sequence diagram of push template message mechanism.

1. Login request
WhatsApp API using oAuth mechanism for API access authentication. So, before you could access every
API in this document, you should get token access by hitting login API.
2. Token response
If your credential is correct, the login API will return a token key which has expiry time. Use this token in
every hit of any WhatsApp API.
3. Check contact
Before you send a template message to a WA number, you should perform a check contact of the number
to know if it’s a valid WA user or not.
4. Valid WA id
The check contact API will return a valid/invalid contact, if it’s a valid contact then you can perform the
send template message.
5. Send message request
Use this API to send a template message.
6. Message id response
Messages API returns message id if success, you should keep the message id and wait for the delivery
status related to the message id.
7. Delivery status
Delivery status of the message id from point 6 will be sent to you once WhatsApp send it to Jatis.

Page 64 of 64 5/2/2023