Adapter - WhatsApp
This page describes version 2.0.4 of the adapter.
Overview
The WhatsApp adapter allows businesses to send text or text-template messages, receive messages from customers, as well as react to existing messages in a conversation.
Note
The adapter uses the WhatsApp Cloud API to send and receive messages on the WhatsApp platform. You will need a WhatsApp Business Account along with a Meta Developer Account in order to configure the adapter.
Properties
| Name | Display | Is Required | Comments | Type | Default Value | Maximum Value | Minimum Value | Maximum Length | Minimum Length |
|---|---|---|---|---|---|---|---|---|---|
| authenticationToken | WhatsApp Cloud platform authentication token | True | The authentication token used to access the WhatsApp Cloud API | string | 1000 | 20 | |||
| apiVersion | WhatsApp Cloud platform version | True | Version of the WhatsApp Cloud platform (e.g. v17.0) | string | 100 | 1 | |||
| phoneNumberId | WhatsApp Business Phone ID | True | The ID of the registered WhatsApp Business Account phone number from which to send messages | string | 100 | 1 |
Configuration
The configuration of the adapter requires you to set up a Meta developer account and a Meta developer application configured with WhatsApp product. Refer to the WhatsApp Cloud API documentation for more details.
To receive notifications when a message was received or when the status of a message changes, a WhatsApp Webhooks endpoint should be configured in the Meta application.
Webhook Event Processing
The Meta application uses a Webhook endpoint to post events to UIP. For on-premise UIP systems, the UIP must be in the DMZ or have port forwarding configured to receive WhatsApp notifications.
Webhook post events sent from WhatsApp should be processed by the adapter's Process Webhook command. The adapter command will parse the WhatsApp notification content and create new events which can trigger the start of another workflow to take action with these details. Use the following steps to create a workflow and webhook listener to process the events:
- Create a UIP Workflow that implements the Process Webhook command. Set the WhatsApp Notification property to
{whatsAppEvent}. - Create and configure a UIP Trigger as an Advanced Webhook with:
- Authentication Type: HMAC SHA256 using key
- Authentication Key: use the WhatsApp App Secret encoded as a Base64 string
- ResponseType: None
- Workflow: the Workflow created in step 1 above
- ParseBody: false
- Add a property called "whatsAppEvent" and set its value to
{wfsystem.body}
- Create event triggers that can be used to monitor the incoming messages or message status notifications.
- In the Meta application configure the WhatsApp Webhook with:
- Callback URL: the UIP Advanced Webhook URL
- Verify token: the name of the Advanced Webhook Trigger created above
- Webhook fields: events you can subscribe to receive (e.g. -
messages,message_template_status_update, etc.)
Commands
Send a Text Message (sendMessageText)
Sends a text message to the specified phone number.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| phoneNumber | Destination phone number | Phone number of the message-recipient. | True | string |
| message | Message | The message (text) to be sent to the recipient. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status of the adapter command. | string |
| messageId | The id of the sent message, use it to track your message status. | string |
| code | Error code if there is one. | string |
| error | The error message if there is one. | string |
Send a Text Message Template (sendMessageTextTemplate)
Sends a text message template to the specified phone number.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| phoneNumber | Destination phone number | Phone number of the message-recipient. | True | string |
| templateName | Template Name | The message (text) template to be sent to the recipient. | True | string |
| languageCode | Language Code | The language code of the text template. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status of the adapter command. | string |
| messageId | The id of the sent message, use it to track your message status. | string |
| code | Error code if there is one. | string |
| error | The error message if there is one. | string |
Send a Reaction Message (sendMessageReaction)
Sends a reaction message to the specified phone number.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| phoneNumber | Destination phone number | Phone number of the message-recipient. | True | string |
| messageId | Message ID | The message id the reaction is sent for. | True | string |
| emoji | Emoji | The emoji reaction. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status of the adapter command. | string |
| messageId | The id of the sent reaction message, use it to track your message status. | string |
| code | Error code if there is one. | string |
| error | The error message if there is one. | string |
Process Webhook (processWebhook)
Processes a custom webhook notification from WhatsApp.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| whatsAppNotification | WhatsApp Notification | The WhatsApp Notification received as JSON. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status of the adapter command. | string |
Events
Receive message from customer (customer_message)
An event that occurs when a customer sends a message to the business.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| contacts | Contacts | Array of contact objects with information for the customer who sent a message to the business. | array |
| contacts[0].wa_id | Contact WhatsApp ID | The contact's WhatsApp ID. This can be match to the "from" property of a message. A business can respond to a customer using this ID. This ID may not match the customer's phone number. | string |
| contacts[0].profile.name | Contact Name | The contact's name. | string |
| messages | Messages | Array of objects with information about a message received by the business. | array |
| messages[0].id | Message ID | The ID of the message received. | string |
| messages[0].from | Message From | The WhatsApp ID of the contact. | string |
| messages[0].timestamp | Message Timestamp | The time the message was sent. | string |
| messages[0].type | Message Type | The type of WhatsApp message sent (e.g. - audio, button, document, text, image, interactive, order, sticker, system, video, or unknown). This type describes additional properties which may be accessed from the event message (https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object). | string |
| messages[0].errors | Errors | An array of error objects describing the error. | array |
| messages[0].errors[0].code | Error Code | Error code. | string |
| messages[0].errors[0].title | Error Title | Error code title. | string |
| messages[0].errors[0].error_data.details | Error Details | Describes the error. | string |
Message status changed (status_changed)
An event that occurs when a message is sent or delivered to a customer or the customer reads or reacts to the delivered message sent by the business.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| statuses | Statuses | Array of status objects with information for a message that was sent by the business. | array |
| statuses[0].id | ID | The ID for the message that the business that is subscribed to the webhooks sent to a customer. | string |
| statuses[0].status | Status | Indicates the status of the message (e.g. delivered/read/sent). | string |
| statuses[0].timestamp | Timestamp | Date for the status message. | string |
| statuses[0].recipient_id | Recipient ID | The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number. | string |
| statuses[0].errors | Errors | An array of error objects describing the error. | array |
| statuses[0].errors[0].code | Error Code | Error code. | string |
| statuses[0].errors[0].title | Error Title | Error code title. | string |
| statuses[0].errors[0].error_data.details | Error Details | Describes the error. | string |
Release History
| Version | Type | Description | Tracking # | Date |
|---|---|---|---|---|
| 2.0.1 | Initial | First release in the Adapter Type store. | NAP-3858 | |
| 2.0.2 | Maintenance | Updated third-party components and improved maintainability. | NAP-27635 | 2024-07-31 |
| 2.0.4 | Maintenance | Updated third-party components and improved maintainability. | NAP-27635 | 2024-12-19 |