> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tedro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Nodes

> Send messages, use templates, and escalate to human agents in Tedro workflows.

# WhatsApp Nodes

WhatsApp nodes handle outbound communication with customers through the **WhatsApp** channel. They send messages, deliver pre-approved templates, and escalate conversations to human agents.

***

## wa.send\_message

**Send a free-form text message to the customer.**

This node sends a text message back through WhatsApp. It supports dynamic variables from the workflow context, allowing you to personalize messages.

<Warning>
  **24-Hour Window**: This node only works within the 24-hour customer service window (since the customer's last inbound message). If the window has expired, the runtime blocks the send and logs an error. Use `wa.send_template` for messages outside the window.
</Warning>

### Configuration

| Option | Type   | Required | Description                                                                                                  |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `body` | string | Yes      | Message text. Supports context variables like `{{contact.name}}`, `{{contact.phone}}`, and any custom fields |

### Variable Substitution

Use double curly braces to inject dynamic values:

```
Hi {{contact.name}}, thanks for reaching out!
Your order {{conversation.fields.order_id}} is being processed.
```

Available variables include:

* `{{contact.name}}` -- The customer's WhatsApp profile name
* `{{contact.phone}}` -- The customer's phone number
* `{{contact.fields.*}}` -- Any custom fields set on the contact via `state.set_field`
* `{{conversation.fields.*}}` -- Any custom fields set on the conversation

### Outputs

| Output      | Type   | Description                                             |
| ----------- | ------ | ------------------------------------------------------- |
| `messageId` | string | The WhatsApp message ID returned by the API             |
| `status`    | string | Delivery status (`sent`, `delivered`, `read`, `failed`) |

### Connections

* **Inputs**: Single input handle from the previous node (typically an AI Respond node)
* **Outputs**: Single output handle for chaining additional actions

### Example Use Case

After an AI Respond node generates a support answer, connect it to a Send Message node to deliver the response. The message body can include the AI's generated text along with a personalized greeting.

<Note>
  WhatsApp has a **4,096 character limit** per message. If the AI generates a longer response, Tedro automatically splits it into multiple messages (splitting at paragraph boundaries, then sentence boundaries, then word boundaries).
</Note>

***

## wa.send\_template

**Send a pre-approved WhatsApp message template.**

Template messages are required for outbound communication when the 24-hour customer service window has expired. Templates must be created and approved in Meta Business Suite before use.

### Configuration

| Option               | Type   | Required | Description                                            |
| -------------------- | ------ | -------- | ------------------------------------------------------ |
| `templateName`       | string | Yes      | The exact name of the approved Meta template           |
| `templateLanguage`   | string | Yes      | Template language code (e.g., `en_US`, `he`)           |
| `parameters`         | array  | No       | Dynamic parameter values to fill template placeholders |
| `parameters[].type`  | string | Yes      | Parameter type: `body`, `header`, `button`             |
| `parameters[].value` | string | Yes      | The value to substitute (supports context variables)   |

### Outputs

| Output      | Type   | Description                                 |
| ----------- | ------ | ------------------------------------------- |
| `messageId` | string | The WhatsApp message ID returned by the API |
| `status`    | string | Delivery status                             |

### Connections

* **Inputs**: Single input handle from the previous node
* **Outputs**: Single output handle for chaining additional actions

### Example Use Case

Send an order confirmation template 2 hours after a purchase: template name `order_confirmation`, with parameters for the customer name and order number. Since this is outside the 24-hour window, a template is required.

<Note>
  Template approval is managed by Meta, not Tedro. Create and submit templates in the [Meta Business Suite](https://business.facebook.com). Approval typically takes minutes to a few hours.
</Note>

***

## wa.handoff

**Escalate the conversation to a human agent.**

The Handoff node moves the conversation from automated workflow processing to the human agent inbox. The conversation appears in the **Inbox** with a "handoff" status, where a team member can pick it up and respond directly.

### Configuration

| Option   | Type   | Required | Description                                                                        |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `reason` | string | No       | Optional note explaining why the handoff occurred (visible to agents in the inbox) |

### Outputs

| Output           | Type   | Description                                               |
| ---------------- | ------ | --------------------------------------------------------- |
| `handoff.status` | string | Always `handoff` -- the conversation is now in agent mode |

### Connections

* **Inputs**: Single input handle from the previous node
* **Outputs**: Single output handle (typically connected to a `logic.end` node or left unconnected)

### Example Use Case

After the AI Router classifies a message as "complaint" or the AI Respond node detects frustration, route to a Handoff node with reason "Customer expressing frustration - needs human attention." The conversation appears in the Inbox for an agent to handle.

<Warning>
  **Publish-time validation**: Every published workflow must have at least one reachable `wa.handoff` node. This is enforced by the platform to ensure customers can always reach a human agent. If no handoff path exists, the workflow cannot be published.
</Warning>