WhatsApp Trigger
Description
Use the WhatsApp Trigger activity to start a workflow when a configured WhatsApp event occurs on the connected WhatsApp Business Account.
The trigger receives events from the WhatsApp Business Platform through a webhook and automatically starts the workflow when the configured event is received.
The trigger can be used for general WhatsApp automation as well as WhatsApp-based conversational experiences.
- This activity is a trigger activity and must be placed at the beginning of the workflow.
- A configured WhatsApp connection is required.
- The WhatsApp webhook must be configured in Meta for events to reach IB-X.
- Use the Message Received event when the workflow needs to respond to incoming WhatsApp messages, including WhatsApp-based Conversational Agents.
Usage
The WhatsApp Trigger can be used for scenarios such as:
- Starting a workflow when a WhatsApp message is received
- Building WhatsApp-based Conversational Agents
- Processing incoming customer messages
- Tracking outbound message status
- Monitoring message delivery
- Monitoring when messages are read
- Starting business processes from WhatsApp interactions
The workflow starts automatically whenever the event selected in the trigger configuration is received from the WhatsApp Business Platform.
Prerequisites
Before using the WhatsApp Trigger:
- Configure the Meta WhatsApp Business Platform for your organization.
- Register and verify the WhatsApp business phone number.
- Configure the Meta Developer App and WhatsApp API.
- Create a WhatsApp connection in IB-X.
- Configure the Meta webhook using the webhook information provided by the WhatsApp Trigger.
For information about configuring the Meta WhatsApp Business Platform, see Configure WhatsApp Business Platform.
For information about creating the connection in IB-X, see WhatsApp Connection.
Configuration
Double-click the WhatsApp Trigger activity on the designer canvas to configure the trigger.
The trigger configuration includes the following properties:
| Property | Description |
|---|---|
| Connection Name | The configured WhatsApp connection used by the trigger to interact with the WhatsApp Business Platform. |
| Production Webhook URL | Webhook URL used by the published Agent to receive WhatsApp events from Meta. |
| Debug Webhook URL | Webhook URL used while testing or debugging the Agent from the designer. |
| Event | Specifies the WhatsApp event that starts the workflow. |
| Verify Token | Token used during Meta webhook verification to validate the webhook configuration. |
Connection Name
Select the WhatsApp connection that identifies the WhatsApp Business Account and Meta application used by the trigger.
Click Add to create a new WhatsApp connection if the required connection is not already available.
For information about configuring a WhatsApp connection, see WhatsApp Connection.
Webhook URLs
The WhatsApp Trigger provides webhook URLs that allow the Meta WhatsApp Business Platform to deliver WhatsApp events to IB-X.
Production Webhook URL
The Production Webhook URL is used by the published Agent to receive WhatsApp events from Meta.
Use this URL when configuring the webhook for the production version of the Agent.
Click Copy to copy the URL to the clipboard.
Debug Webhook URL
The Debug Webhook URL is used while testing or debugging the Agent from the designer.
Use this URL when WhatsApp events need to be received by the Agent during design-time testing.
Click Copy to copy the URL to the clipboard.
Ensure that the webhook URL configured in Meta corresponds to the environment or mode in which you want to receive WhatsApp events.
Event
Select the WhatsApp event that should start the workflow.
The following events are available:
| Event | Description |
|---|---|
| Message Received | Starts the workflow when a WhatsApp message is received. |
| Message Sent | Starts the workflow when a WhatsApp message is reported as sent. |
| Message Delivered | Starts the workflow when a WhatsApp message is reported as delivered. |
| Message Read | Starts the workflow when a WhatsApp message is reported as read. |
Message Received
Select Message Received when the workflow needs to process incoming WhatsApp messages.
Typical scenarios include:
- Customer service conversations
- WhatsApp chatbots
- Conversational Agents
- Customer requests
- Order or service inquiries
- Business processes initiated through WhatsApp
For a WhatsApp-based Conversational Agent, use Message Received so that an incoming user message starts or continues the conversational workflow.
Message Sent
Select Message Sent when the workflow needs to react to the sent status of a WhatsApp message.
This can be useful for tracking outbound message processing or maintaining message status information.
Message Delivered
Select Message Delivered when the workflow needs to react after a WhatsApp message is reported as delivered to the recipient.
This can be used for delivery tracking, audit information, or downstream business processing.
Message Read
Select Message Read when the workflow needs to react after a WhatsApp message is reported as read by the recipient.
This can be used for message engagement tracking or workflows that depend on confirmation that a message has been read.
Verify Token
The Verify Token is used when Meta verifies the webhook configured for the WhatsApp Business Platform.
Specify a verification token and use the same value when configuring the webhook in the Meta Developer App.
During webhook verification, Meta sends a verification request to the configured IB-X webhook. IB-X validates the request using the configured Verify Token.
The Verify Token configured in Meta must match the Verify Token configured in the WhatsApp Trigger.
If the values do not match, webhook verification will fail.
Configure the Webhook in Meta
After configuring the WhatsApp Trigger, configure the webhook in the corresponding Meta Developer App.
You will need the following information from the trigger:
- Production Webhook URL or Debug Webhook URL
- Verify Token
In the Meta Developer App:
- Open the WhatsApp configuration.
- Locate the Webhooks or Callback configuration.
- Copy the appropriate webhook URL from the WhatsApp Trigger and configure it as the callback URL.
- Enter the same Verify Token configured in the WhatsApp Trigger.
- Complete webhook verification.
- Subscribe to the WhatsApp events required by the Agent.
- Save the configuration.
- Verify that the webhook is active.
The webhook URL must be reachable by Meta for webhook verification and incoming WhatsApp events to work.
For complete Meta-side configuration instructions, see Configure WhatsApp Business Platform.
Using with a Conversational Agent
The WhatsApp Trigger can be used as the starting point for a WhatsApp-based Conversational Agent.
For this scenario:
- Add WhatsApp Trigger as the starting activity of the workflow.
- Select the required WhatsApp connection.
- Select Message Received as the event.
- Configure and verify the webhook with Meta.
- Connect the trigger to the Conversational Agent.
- Use the trigger outputs required by the conversational workflow.
When a WhatsApp user sends a message:
- WhatsApp receives the message.
- Meta sends the corresponding webhook event to the configured IB-X webhook.
- The WhatsApp Trigger receives the event.
- The Agent workflow starts or continues processing the conversation.
- The Conversational Agent processes the incoming message and generates the appropriate response.
A typical flow is:
WhatsApp User
↓
Meta WhatsApp Business Platform
↓
WhatsApp Trigger
↓
Conversational Agent
↓
WhatsApp User
For conversational workflows, select Message Received. The other events — Message Sent, Message Delivered, and Message Read — represent message status events and are typically used for event tracking and automation rather than starting a user conversation.
Outputs
The WhatsApp Trigger provides outputs containing information received from the WhatsApp webhook.
The outputs available to downstream activities include:
| Output | Description |
|---|---|
| SessionId | Identifies the session associated with the WhatsApp interaction. |
| Messages JSON | Contains the message information received from WhatsApp in JSON format. |
| Message ID | Unique identifier of the WhatsApp message. |
| Message From | Identifies the sender of the incoming WhatsApp message. |
| Message Type | Indicates the type of WhatsApp message received. |
| Message Text | Contains the text of the incoming WhatsApp message, when applicable. |
| Message Media URL | Provides the URL associated with media received in the WhatsApp message, when applicable. |
| Message Media ID | Identifies the media associated with the WhatsApp message, when applicable. |
| Status JSON | Contains the WhatsApp message status information in JSON format. |
| Status ID | Identifies the WhatsApp message associated with the status event. |
| Status Value | Indicates the status reported for the WhatsApp message. |
The values populated depend on the Event selected for the trigger and the webhook payload received from WhatsApp.
SessionId
Represents the session associated with the WhatsApp interaction.
For conversational workflows, the SessionId can be used to associate incoming WhatsApp messages with the corresponding conversation session.
This allows downstream conversational activities to maintain continuity across multiple messages in the same conversation.
Messages JSON
Contains the message information received from WhatsApp in JSON format.
Use this output when the workflow requires access to message information beyond the individual message outputs exposed by the trigger.
This is particularly useful when the workflow needs to inspect or process the underlying message data.
Message ID
Represents the unique identifier associated with the WhatsApp message.
The Message ID can be used to:
- Identify a specific WhatsApp message
- Correlate message-related processing
- Track a message across workflow operations
- Associate subsequent status information with a message
Message From
Identifies the sender of the incoming WhatsApp message.
This output can be used by the workflow to identify the WhatsApp user who initiated the interaction.
Message Type
Indicates the type of WhatsApp message received.
The value can be used by downstream workflow activities to determine how the incoming message should be processed.
For example, the workflow can use the message type to distinguish between text and media-based messages.
Message Text
Contains the text of the incoming WhatsApp message.
This output is typically used when Message Received is selected and the incoming WhatsApp message contains text.
For WhatsApp-based Conversational Agents, this value can be passed to the conversational workflow as the user's message.
Message Media URL
Provides the URL associated with media received as part of the WhatsApp message, when applicable.
This output can be used by downstream activities that need to access or process media received through WhatsApp.
Message Media ID
Represents the identifier associated with media contained in the WhatsApp message, when applicable.
The Media ID can be used when subsequent processing needs to identify or retrieve the associated media.
Status JSON
Contains the message status information received from WhatsApp in JSON format.
This output is primarily useful for message status events such as:
- Message Sent
- Message Delivered
- Message Read
Use this output when the workflow needs access to the underlying status information beyond the individual status outputs.
Status ID
Identifies the WhatsApp message associated with the received status event.
This allows the workflow to correlate a status update with the corresponding WhatsApp message.
Status Value
Contains the status reported for the WhatsApp message.
Depending on the event received, this value represents the current message status, such as:
- Sent
- Delivered
- Read
This output can be used to implement message tracking, auditing, notifications, or other status-dependent workflow logic.
Outputs by Event Type
The outputs used by a workflow typically depend on the configured event.
| Event | Primary Outputs |
|---|---|
| Message Received | SessionId, Messages JSON, Message ID, Message From, Message Type, Message Text, Message Media URL, Message Media ID |
| Message Sent | Status JSON, Status ID, Status Value |
| Message Delivered | Status JSON, Status ID, Status Value |
| Message Read | Status JSON, Status ID, Status Value |
Outputs that do not apply to the received event may not contain a value.
Use the message-related outputs for Message Received events and the status-related outputs for Message Sent, Message Delivered, and Message Read events.
Testing the Trigger
Before using the WhatsApp Trigger in production:
- Configure the required WhatsApp connection.
- Configure the trigger with the required event.
- Configure the Verify Token.
- Configure the appropriate webhook URL in Meta.
- Verify the webhook successfully.
- Subscribe to the required WhatsApp events.
- Start the Agent in the appropriate testing mode.
- Perform the action corresponding to the configured event.
For example, when testing Message Received, send a WhatsApp message to the configured WhatsApp business phone number.
Verify that:
- Meta receives the WhatsApp message.
- Meta generates the corresponding webhook event.
- The event reaches the configured IB-X webhook.
- The WhatsApp Trigger receives the event.
- The Agent workflow starts successfully.
- The expected trigger outputs are populated.
- The incoming message is processed as expected.
For status events, send a WhatsApp message and verify that the workflow is triggered when the corresponding Sent, Delivered, or Read status is received.
Best Practices
- Use Message Received for WhatsApp-based Conversational Agents and workflows that process incoming customer messages.
- Use Message Sent, Message Delivered, and Message Read when workflows need to react to message status changes.
- Use Message Text for text-based incoming messages.
- Check Message Type before processing message-specific content.
- Use Message Media ID and Message Media URL when processing media messages.
- Use Status ID to correlate a status event with the corresponding WhatsApp message.
- Use the JSON outputs when the workflow requires information not exposed through the individual outputs.
- Ensure that the correct webhook URL is configured for testing and production.
- Keep the Verify Token consistent between IB-X and the Meta webhook configuration.
- Ensure that the WhatsApp connection uses the correct WABA ID, Phone Number ID, Meta application, and System User credentials.
- Test inbound WhatsApp events before publishing the Agent for production use.
- Verify that the required webhook events are subscribed in the Meta Developer App.
- Protect WhatsApp connection credentials and webhook verification information according to your organization's security policies.