WhatsApp Node

WhatsApp node allows you to send text messages, messages with media attachments (audio, video, document and image), and template messages to your WhatsApp customers using a verified WhatsApp business account.

Prerequisites

The following are the prerequisites to use the WhatsApp node in your flows.

1. Configure a WhatsApp app on Webex Connect from Assets -> Apps -> Configure New App' section to authorize Webex Connect to use your WhatsApp account to send and receive messages.
2. To send proactive notification messages to your customers, you should create and submit a respective message template which should be approved by WhatsApp for the allowed messaging use-cases. You should configure these templates, submit them for approval and track the approval status from 'Tools -> Templates' section within Webex Connect.

   🚧

   Get Opt-In for notification messages

   You are required to obtain opt-in before opening marketing, utility, and authentication conversations with customers outside the 24-hour window. You can obtain opt-in in a multitude of ways, both on and off WhatsApp. Refer this section for more details.

Node Configuration

Drag and drop the WhatsApp node on the flow canvas. Double-click the node to configure a message request.

Destination type

The destination type can be one of the following two options:

• WA ID : WhatsApp ID (phone number including country code) of your customer/ recipient of this message.
• Customer ID : Primary key of customer profile. A customer profile can be created to link one or more channel-specific identifiers. Webex Connect intelligently looks up for the corresponding channel identifier under a given customer profile based on the channel context. This allows for cross-channel communication.

Destination

The destination value corresponding to the selected Destination Type. The value can be static or dynamic.
For e.g., on an incoming message/event to your WhatsApp business number, the WA ID of the sender will be stored in a session variable that can be accessed using $(whatsapp.whatsappId) while replying.

📘

Note

If +E.164 format is enabled for your tenant - all the numbers in the To field should follow the "+E.164" format.

This format displays the number with a "+" followed by the country code and the phone number.

+E.164 format is not applicable to the numbers in the From field.

Message Type

WhatsApp supports the following message types:

• Text: Text message; the length of the message is limited to 4096 characters.
• Media: Media attached messages including audio files, video files, documents, stickers, and images along with a caption (optional).
• Template: Rich message templates that can include media objects (image/video/document), header, footer, and/or interactive components (like Call-to-action - CTA buttons and Quick Replies).
• Location: Send location by specifying latitude and longitude with an optional name and address.
• Contact: Share contacts to customers including details like addresses, phone numbers, websites, and so on.
• List Messages: Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.
• Reply Buttons: Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.

📘

24 hour rolling window

Once a user contacts a business, the business can respond with any type of message in the next 24 hours. But if the business is contacting the user before user sends a message, or after 24 hours have passed, it can only send message using the template message type leveraging an approved template, created from within Tools->Templates section.

Free-form text messages, media, location, contact message, reply buttons or list messages will not work outside this 24 hour window. They will result in a failure callback with error.

Text

• Text body: The content of the text message, which can contain URLs and formatting. The length of the message is limited to 4096 characters. To format your messages use the following formatting symbols:

• Preview URL (Optional): WhatsApp recognizes a URL in a text message and makes them clickable. Enable the checkbox to include a preview for the URL and make sure the URL begins with http:// or https://. If multiple URLs are in the body text string, only the first URL will be rendered. Follow the guidelines mentioned in this page to make sure the URL preview is rendered by WhatsApp.

Media

• File type & MIME type: Select the appropriate file type and the corresponding MIME type. Here is a list of supported File types and MIME types.

• Payload: Publicly accessible URL that is a direct link to the media.

👍

WhatsApp Media Best Practices

• While uploading the media and setting the mime-type make sure you are following the guidelines mentioned in this documentation.
• The publicly accessible URL used while configuring the message must end in the same file format set under the 'File MIME type'. It should not have any geo-restriction and should be accessible from a server located within USA premises.
• Supported incoming media message mime-types are identical to outbound message media mime-types in Send node and Messaging API. The mime-type of the incoming media message can be captured as part of the following:
  • Start node and Receive node output variable i.e., "whatsApp.mimetype",
  • Outbound webhooks, Debug logs and Export logs with JSON path "attachments.mime_type"
• WebP is a modern image format that provides superior lossless compression and creates smaller and richer images that makes web faster. The source libraries to use for converting an image to WebP file-format are available here. You can also use various third-party converters publicly available to convert images to WebP file-format.

• File Name - Applicable for document media type. The document file will be saved as the entered 'file name' on the user’s device.

• Caption: Applicable for images and videos. The caption text is displayed along with the attachment.
  Caption field had been previously used to identify filename for a document attachment in some scenarios. Make sure to copy the filename here as well for a document media attachment.

Stickers

Users can now send and receive custom Stickers through WhatsApp. You need to follow the below steps if you want to send a sticker.

• Select WhatsApp from the panel and double-click.
• Select Message Type as 'Media'.
• Select Sticker from the File Type dropdown in the Message Configuration
• Select WebP from the MIME Type dropdown (currently only WebP is available).

📘

Note

WebP is a modern image format that provides superior lossless compression and creates smaller and richer images that makes web faster. The source libraries to use for converting an image to WebP file-format are available here [<https://developers.google.com/speed/webp>]. You can also use various third-party converters publicly available to convert images to WebP file-format.

• Enter the direct URL pointing to the sticker in Payload.

🚧

Note

Custom stickers must meet the following requirements:

• Each sticker has a transparent background.
• Stickers must be exactly 512x512 pixels.
• Each sticker must be less than 100 KB.

Apart from the above, the below points are also recommended while customizing a sticker:

• Adding an 8-pixel #FFFFFF stroke to the outside of each sticker is advised to be able to work with a variety of backgrounds, including white, black, colored, and patterned.
• The sticker image and the edge of the 512x512 pixel canvas should have a 16-pixel margin in between.

Notification Messages using Templates

Once a user contacts a business, the business can respond with any type of message in the next 24 hours. These types of messages are free.

But if the business is contacting a user before the user sends a message or after more than 24 hours have passed, it can only send a message template. This is a paid notification.

Free-form text messages, media, document, or a contact message will not work outside this 24 hour window. They will result in a failure callback with error.

Template

📘

24-hour rolling window

Once a user contacts a business, the business can respond with any type of message in the next 24 hours. But if the business is contacting a user before the user sends a message or after more than 24 hours have passed, it can only send message using the template message type using an approved template from within Tools->Templates section.

Free-form text messages, media, document, contact message, reply buttons or list messages will not work outside this 24 hour window. They will result in a failure callback with error.

This message type allows you to send proactive messages using a pre-defined template to your users. A template should be registered from Tools > Templates section within Webex Connect platform. Include the following as part of a notification message using the template message type:

• Attachment (Video, Image and Document)
• Header and Footer text.
• Interactive buttons (Quick Reply and Call-to-action buttons)

For more information on how to create a template, refer Template doc.

Provide the following details under Message Configuration:

You can create your own templates, submit them for approval to WhatsApp, and track approval status using Webex Connect's Template Management section accessible under 'Tools > Templates'.

When you select a template that has interactive buttons within it you need to configure it. In the case of a template with CTA buttons, you need to provide the URL Suffix. The URL Suffix appends to the pre-defined URL and personalizes the link for the users. For QR buttons, you need to provide the button payload. The payload that you configure here identifies the QR button.

The following image shows the configuration for an interactive template with CTA buttons:

The following image shows the configuration for an interactive template with QR buttons:

The following image shows the configuration for an authentication template with the Auto-fill option enabled:

Supported Media Types for Marketing and Utility category templates

Location

This message type allows you to send location details to your users. Provide the following details under Message Configuration:

Contact

This message type allows you to send contact details to your users. Provide the following details under Message Configuration:

List Message

• Header Text – Description about the list. It must be in text format. This is an optional field. Maximum of 60 characters is supported.
• Message Body – Body of the message. Maximum of 1024 characters is supported.
• Footer Text – Additional notes. It must be in text format. This is an optional field. Maximum of 60 characters is supported.
• List Title – Title of the list button. Maximum of 24 characters is supported.
• Configure List Items – Click this to configure the list of the options.
• List Section: Must contain a title and at least one row. You can add a maximum of 10 sections.
  • Row Title: Title of the row.
  • Identifier: A unique identifier for the row. This is returned as part of the incoming event when the row is selected by the user. Maximum of 200 characters is supported.
  • Description: Optional description about the row. Maximum of 72 characters is supported.
  • Add Row: Click this to add another row in the section.
  • '+' icon: Click this to add another section in your list.
  • '>' icon: Use this to navigate between sections.
  • Save: Click this to save the list options.
• List Messages are best for presenting several options, such as:
  • A customer care or FAQ menu
  • A take-out menu
  • Selection of nearby stores or locations
  • Available reservation times
  • Choosing a recent order to repeat

Reply Buttons

• Reply Buttons: Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.
• Header Type – Text, image, video, or document. Provide a media URL for video, image, and document. For text, add a text field with the required content. Maximum of 60 characters is supported for text.
• Message Body – Body of the message. Maximum of 1024 characters is supported.
• Footer Text – Additional notes. It must be in text format. This is an optional field. Maximum of 60 characters is supported.
• Replies – You can configure up to 3 reply buttons.
• Reply Title: Unique title for the reply option. Maximum of 20 characters is supported.
• Identifier: A unique identifier for the reply option. This is returned as part of the incoming event when the option is selected by the user. Maximum of 200 characters is supported.
• Add New: Click this to add a new reply option.
• Save: Click this to save the configuration.

Reply Buttons are best for offering quick responses from a limited set of options, such as:

• Airtime recharge
• Changing personal details
• Reordering a previous order
• Requesting a return
• Adding optional extras to a food order
• Choosing a payment method

Reply buttons are particularly valuable for ‘personalized’ use cases where a generic response is not adequate.

List Message and Reply Buttons Specifications

• List Messages and Reply Buttons can be combined together in the same flow.
• A user can only select one option at the same time from a list or button message, but they can go back and re-select a previous message.
• List or reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you get an error message.
• Supported platforms: iOS, Android, and web.

See how text messages compare to interactive messages:

See an example of how List messages and Reply buttons can be combined in the same flow:

Identity key hash

WhatsApp enables you to authenticate the identity of the customer to make sure you are communicating with the intended person. This becomes critical for use-cases such as sending OTP messages. As a solution for this, businesses can utilise the cryptographic identity key hash field managed by WhatsApp against customer’s identity.
The hash is matched with the hash in the message requests sent from Webex Connect platform.

You can capture the Identity key hash of a trusted WhatsApp customer (at the time) as part of the output variables of Start Node, Receive Node, and within the Delivery Receipt payloads

When sending any sensitive information, PII data or an authentication template message (containing one-time password), business should include the Identity key hash within the WhatsApp send node or messaging API.

Whenever there is a potential identity change (due to theft or user updating to a new device), WhatsApp updates the cryptographic hash. When business sends a message to the WhatsApp user with the old hash, the delivery of the message fails as the hashes do not match. Subsequently, an error code is sent to notify about the message delivery failure as part of the delivery receipts. This indicates that the customer’s phone number can no longer be authenticated.

📘

Messages without Identity key hash

Messages sent without including the Identity key hash will continue to be delivered as expected, disregarding any number ownership change or potential impersonation of the intended customer.

Getting new Identity key hash

Business might need to resume communication with the WhatsApp customer in-case the potential identity change was inaccurately suggested by WhatsApp. To identify such scenario business should re-authenticate the customer using a trusted channel outside of WhatsApp. Once the customer is re-authenticated, business can capture the new Identity key hash by either of the following two methods:

• Sending a message to the WhatsApp customer without including the Identity key hash. The updated hash can be captured as part of the delivery receipt.
• When a messages is received from the customer, the new hash can be captured as part of incoming message payload within Outbound webhooks, Export Logs, Debug logs, Start Node, and Receive Node.

🚧

Managing Hash

Business should save and manage the hash for their customers and include the hash in the messages containing any sensitive information, PII data or an authentication template message (containing one-time password).

Correlation ID

You can assign a unique ID of your choice to each WhatsApp message. This ID is returned to the platform with the delivery report and can be used to identify the message.

Callback Data

In case there is additional data to be sent along with the delivery reports to the URL, you must specify that here.

Validations forCallback Data & Correlation ID:

1. Callback Data, Correlation Id fields are optional for all the channels. Send node can be saved without providing these fields.
2. All characters, Alphabets, Numbers, and special characters are accepted.
3. Variables can be added.
4. Hard coded values are accepted.
5. On Platform side, there is no Max or Min length validation for these fields.

Notify URL

You can choose to notify a URL with the delivery report for WhatsApp message. This field accepts only a valid URL or a variable. If an invalid URL is passed in API request or via a variable, then such request will not be considered eligible for retries.

Validations for Notify URL:

1. It is an optional field optional for all the channels. Send node can be saved without providing these fields.
2. Notify URL should be filled with proper URL format. Otherwise, error message ‘Invalid URL, field accepts only valid URL or variable’ will be displayed.
3. When space is provided in front of the URL, Invalid URL, field accepts only valid URL or variable’ will be displayed.
4. When space is provided at the end of the URL, space gets trimmed and ignored and DRs are received to the URL.
5. No Max length validation.
6. Variables can be added to this field.

Optional Parameters

• Wait For: The flow waits for one of the following conditions to be met for exiting the node.
  • None: The default option, exits the node immediately after executing the send
  • Gateway Submit: Exits the node upon submitting the message to WhatsApp
  • Delivery Report: Waits until receiving the delivery receipt for the message sent
  • Read: Waits until the customer has read the message.
• Timeout: Maximum time in seconds until which the node should wait for one of the 'Wait for' conditions to be met. The node exits via the 'onDeliveryReportFail' node outcome edge when the set time elapses.

📘

Wait for condition on Read

If a customer disables read receipt in their WhatsApp privacy settings, the node keeps waiting for the read receipt until the set expiry time.

• Expiry: 2 types of message expiry checks are supported
• UTC: Time in UTC within which the message send should be attempted. For example, if the value is set to 2019-23-04 03:06:48 AM, the message is suppressed if a send attempt is made beyond the set time.
• Seconds: Maximum time in seconds within which the message must be submitted to WhatsApp.

The node exits via the 'onPolicyFail' node outcome edge when the expiry condition cannot be met.

Output Variables

You can see the data that this node generates as output variables. These variables are available for use in subsequent nodes.

Node Outcomes

The node exits via one of the node edges correspondings to the outcome of the node.

WhatsApp Business Platform Onboarding Guide for Developers

By now, you would have set yourself up on Webex Connect with your WhatsApp number. If not, click here to know how.

1. Testing

After adding your number to Webex Connect, you can test it by sending a message to the number from your phone. You will be able to respond to it using the APIs or Flows.

To send proactive outbound messages, you will need to submit a template for approval. You can do this from Tools > Templates within your Webex Connect account.

2. Receiving Messages & Webhooks

To receive incoming messages and events from your customers, you can configure outbound webhooks under integrations by choosing the WhatsApp Business API app from the entity dropdown.

Once you set up your webhook successfully, you will see that your messages start landing on your webhook endpoint.

3. Messaging API

You can also test outbound messages through our API collection here

You will need to update your service key in the API collection.

4. Message Types

We support the following message types offered by WhatsApp today:

• Text
• Media
• Contact
• Location
• Templates
• Reply Buttons Message
• List Message

5. Entry Points

WhatsApp supports free entry points that are user generated. You can send a link, like the one below, to your customers to get them to initiate a chat.

https://wa.me/15551234567?text=I'm%20interested%20in%20your%20car%20for%20sale

This link can also be converted to a QR code or embedded as a button on a website or an email.