How to Send Transactional Messages on WhatsApp via Digital Connect API
How to Send Transactional Messages on WhatsApp via Digital Connect API
As a business, you may want to automate transactional messages on WhatsApp, sending message templates directly from your own system—such as a website, app, or CRM—whenever a relevant customer event occurs.
This article will guide you through the precise steps required to automate WhatsApp notifications with templates using your own system.
Prerequisites
TABLE OF CONTENTS
HTTP Request using API Key
POSThttps://eoceandigitalconnect.com/v2/api/outgoing/message
To authenticate the API request, you will require the API key associated with your account. The API key can be found in the Developer Settings of your Digital Connect account. Please note that access to the Developer Settings is restricted to the platform administrator only.
Example:
The request body for the API should be in JSON format and include the following parameters:
| Fields | Type | Description |
|---|---|---|
| phone_number | String (required) | Phone number to authenticate |
| type | String (required) | Type of message template |
| parameters | Object (required) | Contains the data for the chosen type |
Request Payload
Message Types and Parameters
You can send both types of WhatsApp messages, including Template and Free-form messages. However, Free Form messages can only be sent to customers within a 24-hour conversation window. Otherwise, although the message won’t be sent, you will still receive a success response from the API.
Make sure to include the relevant parameters based on the type you choose when sending the message in the request body.
Type : TEXT
| Fields | Data Type | Description |
|---|---|---|
| body | String (required) | text message that can contain URLs and supports formatting |
| preview_url | Boolean (optional) | Set this field to true to include a URL preview box |
Text Message Payload (Without Preview URL)
Text Message Payload (With Preview URL)
Type: MEDIA
The media object consists of audio, document, image and video objects.
| Fields | Data Type | Description |
|---|---|---|
| type | String (required) | The type of media object |
| id | String (required) | The ID of the media object |
| link | String (required when type is audio, document, image, sticker or video or when not using uploaded media ID ) | The protocol and URL of the media to be sent |
| caption | String (optional) | Description of the media object |
| filename | String (optional) | Specified filename document |
Image Message by ID Payload
Image Message by URL Payload
Audio Message by ID Payload
Audio Message by URL Payload
Document Message by ID Payload
Document Message by URL Payload
Video Message by ID Payload
Video Message by URL Payload
Type: LOCATION
| Fields | Data Type | Description |
|---|---|---|
| latitude | String (required) | latitude of the location |
| longitude | String (required) | longitude of the location |
| name | String (optional) | name of the location |
| address | String (optional) | address of the location |
Location Message Payload
Type: TEMPLATE
| Fields | Data Type | Description |
|---|---|---|
| name | String (required) | The ID of the media object |
| language | Object (required) | Specifies the language object |
| component | Array of Objects (optional) | Specifies the array of component objects |
Template Text Message Payload
Template Button Message Payload
Template Date and Currency Message Payload
Type: CONTACTS
| Fields | Data Type | Description |
|---|---|---|
| name | Object (required) | Specifies the name object |
| address | Object (required) | Specifies the address object |
| Object (required) | Specifies the email object | |
| org | Object (required) | Specifies the organization object |
| phone | Object (required) | Specifies the phone object |
| birthday | String (required) | Specifies the birthday |
| url | Object (required) | Specifies the url object |
Contact Message Payload
Parameter Fields
| Fields | Data Type | Description |
|---|---|---|
| type | String (required) | Describes parameter type. Values: text, currency, date_time, image or document. |
| text | String (required when type is text) | Message of the text |
| currency | String (required when type is currency) | Specifies the currency object |
| date_time | string (required when type is date_time) | Specifies the date_time object |
| image | String (required when type is image) | Specifies the media object of type image |
| document | String (required when type is document) | Specifies the media object of type document |
For more information on message types and their required parameters, please refer to the following link:
https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages
Response Body
If successful, the response body will return a status of 200 including message ID and a success indicator.
Message Throughput
For each registered business phone number, Cloud API supports up to 1,000 messages/sec by default.
Throughput is inclusive of inbound and outbound messages and all message types. Note that business phone numbers, regardless of throughput, are still subject to their WhatsApp Business Account’s business use case rate limit and template messaging limits.
If you attempt to send more messages than your current throughput level allows, the API will return error code 130429 until you are within your allowed level again.
Error Codes and Messages
| Error Message | Error Code | Error Description |
|---|---|---|
| noToken | Unauthorised: No token Provided (Code: 1488) | The request is missing the required authentication token |
| invalidToken | Unauthorised: Invalid token (Code: 1489) | The provided authentication token is invalid or expired |
| incorrectCredentials | Incorrect org_unit_id or phone_number_id (Code: 1652) | The provided org_unit_id or phone_number_id is incorrect or invalid |
| validation | Data Validation Error (Code: 1265) | Data being sent does not match the expected format |
| limitReached | limitReached: (Code: 130429) | Requests per minute exceeded |
Example Postman Request
Step 1: Setup Request Type to “POST”
Step 2: Setup URL
Step 3: Select Headers option
Step 4: Set token under Headers section
Step 5: Choose body type “raw”
Step 6: Select “JSON” type
Step 7: Set content of the request
You can find more examples here – Open in Postman
Check your messaging limit tier in your Facebook Business Manager or Digital Connect Campaign Manager to determine your daily template sending limit.