WhatsApp Node

The WhatsApp Node allows a workflow to send messages using the configured WhatsApp Business account.

Node Properties

There are many configuration options to provide when setting up the WhatsApp Node, broken up into several sections …

WhatsApp Configuration

First, choose how to authenticate the request. There are two different options …

• Choose a Service Credential: This is the recommended method; however, this method is not available in Edge Workflows. When using this method, you must provide …

  • Credential Name Template: A string template resolving to the name of one of your application’s WhatsApp Service Credentials.

• Enter Configuration: When selected, you must provide …

  • From Number ID Template: A string template resolving to the ID of the From Number that the messages should be sent from. This should be the ID of a From Number associated with your WhatsApp Business account.
  • Access Token Template: A string template resolving to an access token for your WhatsApp Business account, which should be rotated regularly.

Message Configuration

There are two different ways to form a WhatsApp message. The message can either be a free-form text message (message type Enter a free-form message...), or a templated message using a existing template in your WhatsApp business account (message type Choose a message template...).

Free-Form Message

When choosing to send a free-form text message, the content of the message can either come from a string template or payload path. In either case, the message will be converted to a string and then sent to the recipients.

Note: When sending a free-form message to a recipient, that recipient must have an open customer service window with the sending From Number, otherwise the message will not be delivered (even though the WhatsApp message send will say the message was accepted). Because of this restriction, Losant recommends using Message Templates instead whenever possible.

Message Template

When choosing to send a templated message, you must configure the following:

• Template Name: A string template resolving to the name of a WhatsApp Template in your WhatsApp Business account.
• Template Language Code: A string template resolving to a language code that is supported your template. Defaults to en_US if not provided.

• Components Source Method: You can choose how to provide the template components, either as a payload path or a JSON template. Template components are optional, as not all WhatsApp Templates require them.

  • Components Payload Path: A payload path that resolves to either a single WhatsApp template component object or an array of those objects.
  • Components JSON Template: A JSON template that resolves to either a single WhatsApp template component object or an array of those objects.

To Numbers

Provide at least one phone number to send your message to. Multiple recipients can receive the same message, and those recipients can be provided through a combination of the following methods …

• One number per line.
• Multiple numbers per line, separated by commas (,) or semicolons (;).
• A string template referencing a phone number, a string of comma- or semicolon-separated numbers, or an array of phone numbers on the payload.

For example, given the following payload …

{
  "working": {
    "numbers": [
        "7894443333, 13214567890, +13026546544",
        "+19795753838"
    ],
    "extraNumber": "+18038274238"
  }
}

… and a WhatsApp Node with “To Numbers” defined as follows …

1. +15135551212; +13753471111
2. {{working.extraNumber}}
3. {{working.numbers}}

… this would result in messages being sent to seven different recipients. (Each number is a separate send; the node does not create a group message for all recipients.)

Result

Optionally, provide a payload path where the result of the request can be placed on the current payload. If provided, the WhatsApp Node will place an array at this path, with one entry per recipient number. For a successful send, the result will include a messageId field, which will be the specific ID of the sent message.

Note: A successful send of a message does not mean the message has been or will be successfully delivered. If knowing the delivery status of a message is important to you, you must configure a WhatsApp webhook in order to get updates on the delivery of a given message.

Node Example

The following is an example of a payload after successfully sending a message to one recipient, with a result path of working.whatsAppResult:

{
  "working": {
    "whatsAppResult": [
      {
        "messageId": "wamid.HBgLMTgxMjIzMDE2MzMVAgARGBI1NkFDRDdCOTRGNkY3ODc4M0MB",
        "success": true,
        "number": "+2128675309"
      }
    ]
  }
}

Node Errors

The WhatsApp Node can fail to send for several reasons. In the case of an error, the resulting array contains objects with an error key and a message key instead of the success key.

For example, the following would be placed on the payload at a result path of working.whatsAppResult when trying to send the message with a “From” number that is not associated with your account:

{
  "working": {
    "whatsAppResult": [
      {
        "error": true,
        "message": "Unsupported post request. Object with ID '292998420553898' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api",
        "number": "+2128675309"
      }
    ]
  }
}

And, the following would be placed at the path when trying to send to an invalid phone number:

{
  "working": {
    "whatsAppResult": [
      {
        "error": true,
        "message": "Phone number invalid",
        "number": "+344454238712"
      }
    ]
  }
}

Related Nodes

• SMS Node
• Twilio Node