How to Trigger a WhatsApp Message

With WhatsApp being the world’s most popular instant messaging platform, it’s no surprise that you’d want to know how you can start sending WhatsApp messages based on various system or workflow triggers.

The platform offers two distinct ways to integrate WhatsApp functionality into your custom mobile app:

User-Initiated Messages (Action Button): Generate a dynamic WhatsApp “click-to-chat” HTML link that opens the user’s WhatsApp app with a pre-populated message when they tap an Action Button.
Using the REST Connector/Field (WhatsApp REST API): Automatically send a templated WhatsApp message to a preconfigured number in the background whenever a user submits a form. This uses our REST form connector and the WhatsApp Cloud API.

This guide will walk you through setting up both methods.

Method 1: Sending a Message via an Action Button (WhatsApp Link)

If you prefer to have the user initiate the WhatsApp message from their own device, you don’t need to configure the Meta API. Instead, you can use our platform to generate a dynamic WhatsApp “click-to-chat” HTML link and assign it to an Action Button.

When the user taps the button, it will open their WhatsApp application with a pre-populated message ready to be sent to your designated number.

1. Understand the WhatsApp Link Format WhatsApp uses a specific URL structure to open a chat and pre-fill text.

Base URL Format

https://wa.me/<number>?text=<urlencodedtext>

<number>: The recipient’s full phone number in international format. Omit any brackets, dashes, plus signs, or leading zeros. (e.g., use 15551234567, not +1-(555)-123-4567).
<urlencodedtext>: The pre-populated message. Because it is part of a URL, spaces and special characters must be URL-encoded (e.g., a space becomes %20).

2. Generate the Dynamic Link On the platform, you can dynamically construct this URL by combining static text with variable data from your app.

For example, if you want the message to say: “Hi, I have completed inspection reference code ABC123”, your base URL would look like this:

Base URLEncoded Format

https://wa.me/15551234567?text=Hi,%20I%20have%20completed%20inspection%20reference%20code%20

You would then append the dynamic Handlebar variable for the Property ID to the end of that string (e.g., {{property_id}}).

3. Configure the Action Button

Add an Action Button to your screen or form.
Set the button’s action type to open a URL/Web Link.
Bind the dynamically generated https://wa.me/... URL you created in the previous step to the button’s target.

When the user clicks the button, the device’s native OS will intercept the wa.me link and seamlessly transition the user into their WhatsApp app with your custom message ready to send!

Method 2: Using the REST Connector/Field (WhatsApp REST API)

Integrating WhatsApp with your custom mobile app lets you automatically send instant notifications to a preconfigured number whenever a user submits a form. This guide walks you through setting up the WhatsApp Cloud API and configuring the REST form connector on the platform.

Prerequisites

Before you begin, ensure you have the following:

A Meta Developer account (register at developers.facebook.com).
A WhatsApp Business Account (WABA).
A dedicated phone number for WhatsApp that is not currently registered with the consumer or standard business WhatsApp apps.

Step 1: Set Up the WhatsApp Cloud API

To send messages, you need to generate API credentials through Meta.

Create a Meta App: * Log into your Meta Developer dashboard and click Create App.
- Select Other for the use case, then choose Business as the app type.
- Fill in your app details and click Create App.
Add WhatsApp to Your App:
- In the App Dashboard, scroll down to “Add products to your app,” then locate WhatsApp. Click Set Up.
- Select your existing Meta Business Account or let the system create one for you.
Configure Your Phone Number:
- In the left-hand menu, navigate to WhatsApp > API Setup.
- Follow the prompts to add your dedicated phone number. Meta will send an SMS or voice code to verify ownership.
Generate an Access Token:
- For testing, Meta provides a temporary access token (valid for 24 hours).
- For production, you must generate a Permanent Access Token by creating a System User in your Meta Business Settings and granting it whatsapp_business_messaging permissions.

Step 2: Create a Message Template

WhatsApp requires businesses to use pre-approved templates when initiating a message to a user. Standard text messages are only allowed if the user has messaged the business within the last 24 hours.

Go to your WhatsApp Manager (accessible via your Meta Business Suite).
Navigate to Account Tools > Message Templates and click Create Template.
Choose a category (e.g., Utility for form alerts) and give your template a name (e.g., new_form_submission).
Draft your message. You can use variables to inject dynamic data from your form later.

Important Note on Handlebars (Ours vs. Meta): Our SaaS platform uses named variables (e.g., {{firstname}}), meaning it identifies data by the specific field name. Meta’s WhatsApp API, however, uses positional variables (e.g., {{1}}, {{2}}). Meta does not know what a “firstname” is; it only looks at the ordered list you send it and maps the first item to {{1}}, the second item to {{2}}, and so on.

Example Body in Meta: “Hello, a new form submission for {{1}} has been received from {{2}}.”

5. Submit the template for Meta’s approval (this usually takes only a few minutes to a few hours).

Step 3: Configure the REST Connector in Your App

Once your Whatsapp message template is approved and you have your API credentials, you can set up the REST connector call within our platform’s form connector section.

1. Set the REST Connector Use the standard WhatsApp Cloud API endpoint. Replace {PHONE_NUMBER_ID} with the ID found in your Meta API Setup dashboard.

Method: POST
URL: https://graph.facebook.com/v25.0/{PHONE_NUMBER_ID}/messages

2. Configure the Headers You need to pass your Meta access token to authorize the request.

Authorization: Bearer YOUR_PERMANENT_ACCESS_TOKEN
Content-Type: application/json

TIP: Add your permanent token key as Organization Metadata in your Org Setup on our secure web portal. This way, you can retrieve the token value on any form by simply referencing it through the ORGMETA() function (e.g., ORGMETA('Whatsapp_Token')).

3. Format the JSON Payload Construct the JSON body to send your approved template. Because Meta relies on positional variables, the order of the items in the parameters array is strictly tied to the {{1}} and {{2}} variables in your template.

Map our platform’s named form fields (like {{field_name}} and {{firstname}}) directly into the text fields. When the form submits, our platform will dynamically insert the real data into those spots before sending the payload to Meta.

JSON

JSON Body for Whatsapp API

{
  "messaging_product": "whatsapp",
  "to": "RECIPIENT_PHONE_NUMBER_WITH_COUNTRY_CODE",
  "type": "template",
  "template": {
    "name": "new_form_submission",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{{form_name}}" 
            //  This is the FIRST object in the array. Meta automatically assigns this to {{1}}.
          },
          {
            "type": "text",
            "text": "{{firstname}}" 
            //  This is the SECOND object in the array. Meta automatically assigns this to {{2}}.
          }
        ]
      }
    ]
  }
}

Note: Remove Comments From JSON Sample Code

Standard JSON does not technically support // comments. They are included in the example above strictly to illustrate how the mapping works. Please ensure you remove the comments in your actual API call to prevent formatting errors.

Important JSON Payload Notes:

to: The recipient’s phone number must include the country code without the + prefix or any leading zeros (e.g., 15551234567).
name: This must exactly match the name of the template you created in Step 2.
parameters: The objects inside this array map directly to the {{1}}, {{2}} variables in your template based purely on their top-to-bottom order. If your template has no variables, you can omit the components array entirely.

4. Test the Integration Setup a suitable form for testing and configure your REST form connector. Submit a test form from your mobile app. If configured correctly, your preconfigured number will instantly receive the formatted WhatsApp message (e.g., “Hello, a new form submission for Contact Inquiry has been received from Jeremy.”). If the message fails to send, check the API response logs in our platform to troubleshoot any Meta authorization or formatting errors.