WhatsApp

1. Overview

WhatsApp is represented by three distinct components on the platform, all using the WhatsApp Cloud API (Meta):

• whatsapp — sends messages (text, template, media, location, or contact).
• whatsapp-in — receives messages via webhook (entry trigger).
• whatsapp-upload-media — uploads a media file to Meta's servers, returning an ID that can later be used when sending media messages.

Use whatsapp to notify customers, whatsapp-in to react to received messages, and whatsapp-upload-media when you're going to send the same media file multiple times (avoiding resending the file in every message).

⚠️ TO CONFIRM: in the current source code, the component registered under the name whatsapp-in actually loads the same implementation as the whatsapp component (sending), not the webhook-receiving logic. Before using whatsapp-in as an entry trigger, it's worth confirming with the responsible team whether this has already been fixed, since as documented in the source code it appears to be a component-registration bug.

2. Prerequisites

• A WhatsApp Business account configured on the Meta platform (Cloud API).
• A registered phone number (phoneNumberId).
• An access token (accessToken) for the WhatsApp Cloud API.

3. Authentication and Connection

Field	Required	Type	Description	Example
phoneNumberId	Yes	Text	WhatsApp Business phone number ID.	"123456789012345"
accessToken	Yes	Text	WhatsApp Cloud API access token.	A Meta token
apiVersion	No	Text	Graph API version used. Default value: "v21.0".	"v21.0"
alternativeUri	No	Text	Alternative/custom base URI for the API (for testing or proxies).	—

4. Configuration / Supported Operations

whatsapp — send a message

Field	Required	Type	Description	Example
messageType	Yes	Text: TEXT, TEMPLATE, MEDIA, LOCATION, CONTACT	Type of message to send.	"TEXT"
phoneNumberRecipient	Yes	Text	Recipient's phone number.	"5511999998888"

TEXT: message (required) — the text to send.

TEMPLATE: templateName (required), language (optional, default "en_US"), components (optional, JSON with the template's parameters).

MEDIA: mediaType (required), caption (optional), and exactly one of link (public media URL) or wppId (ID of a media file already sent via whatsapp-upload-media); fileName (required if mediaType is a document).

LOCATION: locationName, locationAddress, latitude, longitude (all required).

CONTACT: contacts (required, JSON with the data for one or more contacts: name, phones, emails, addresses).

whatsapp-upload-media — upload a media file

Field	Required	Type	Description	Example
fileName	Yes	Text	Name of the message property where the file to upload is.	"receipt"
contentType	Yes	Text	MIME type of the file.	"application/pdf"

5. Practical Examples

Simple example: send a simple text message.

Input:

{
  "customer": { "phone": "5511999998888" }
}

Component configuration:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEXT",
    "phoneNumberRecipient": "{$.body.customer.phone}",
    "message": "Your order has been confirmed!"
  }
}

Response:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

Advanced example: send a PDF document already attached to the message, using a template with parameters.

Input:

{
  "customer": { "phone": "5511999998888", "name": "Maria Silva" }
}

Component configuration:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEMPLATE",
    "phoneNumberRecipient": "{$.body.customer.phone}",
    "templateName": "order_confirmation",
    "language": "en_US",
    "components": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"{$.body.customer.name}\"}]}]"
  }
}

Response:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"Phone number ID is empty." / "Phone number recipient is empty." / "Access token is empty."	Basic connection/recipient fields weren't filled in.	Fill in phoneNumberId, phoneNumberRecipient, and accessToken.
"Message is null"	TEXT type used without filling in message.	Fill in message.
"Template name is null"	TEMPLATE type used without filling in templateName.	Fill in templateName.
"Whatsapp ID or Link must be informed."	MEDIA type used without link or wppId (or with both at the same time).	Fill in exactly one of the two fields.
"Message Type [value] not found"	The messageType field doesn't match any supported type.	Use TEXT, TEMPLATE, MEDIA, LOCATION, or CONTACT.
Response body contains {"error": "..."} even though the flow continues normally	The WhatsApp API returned an error (invalid token, unauthorized number, message limit), but the component doesn't stop the flow in that case.	Check the error content in the response and handle that case explicitly in the flow (for example, with a Choice).