Adapter - WhatsApp

This page describes version 2.0.1 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:

1. Create a UIP Workflow that implements the Process Webhook command. Set the WhatsApp Notification property to {whatsAppEvent}.
2. 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}
3. Create event triggers that can be used to monitor the incoming messages or message status notifications.
4. 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

Categories

• Bot
• Notification