> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/tools/available-tools/message-sending-tool.md).

# Message Sending Tool

The **Message Sending** Tool lets an Agent send outbound WhatsApp messages to specific phone numbers.

Use it for alerts, summaries, handoffs, reminders, and operational notifications. Messages are sent immediately when the Agent decides to use the tool.

***

### 🔎 What It Does

With Message Sending, an Agent can:

* Send regular text messages
* Send approved WhatsApp templates on official connections
* Try text first, then fall back to a template when the 24-hour window is closed
* Choose the destination dynamically or use predefined numbers

***

### ⚙️ How the Tool Works

The Agent decides to use the tool based on its description and instructions.

At runtime:

1. The Agent decides whether a message should be sent.
2. It determines the destination phone number.
3. It uses the configured send mode.
4. Zaia sends the message through the selected connection.

***

### 📞 WhatsApp Connection Rules

#### WhatsApp (Official)

Official WhatsApp connections support three send modes:

* **Text**
* **Template**
* **Text with template fallback**

**Text**

Zaia sends a regular message.

This works when the recipient is inside an active 24-hour WhatsApp window.

**Template**

Zaia sends an approved WhatsApp template directly.

Use this mode when you need a pre-approved outbound message.

**Text with template fallback**

Zaia tries to send a regular message first.

If WhatsApp rejects the message because the 24-hour window expired, Zaia sends the configured template instead.

> ⚠️ Template fallback is not generic. It only runs for the specific WhatsApp window-expired error.

#### WhatsApp (Waha)

Waha connections support **text only**.

Templates and template fallback are not available on Waha.

***

### 📲 Predefined Phone Numbers vs Dynamic Discovery

#### Predefined phone numbers

When enabled:

* You define one or more phone numbers
* The tool sends only to those numbers
* This works well for internal alerts and fixed recipients

#### Dynamic phone number discovery

When disabled:

* The Agent determines the destination number at runtime
* The number can come from the conversation context
* This works well for context-aware notifications

***

### 🧩 Template Behavior in the Tool

When the selected connection is **WhatsApp (Official)**, Zaia only lists templates that are:

* Approved in Meta
* Available for that connection
* Valid for the linked WhatsApp account

Zaia builds the template inputs dynamically from Meta's schema. This includes:

* **Body** variables
* **Header** variables
* **Button** variables
* **Header image** input, when required

In the tool, template fields can be filled partially. Missing values can be completed during execution from context, execution data, or the LLM output.

If a value already exists in the tool configuration, Zaia keeps it. If a value is missing, Zaia can merge extra variables into the template payload.

***

### 🖼️ Image headers

Templates with an image header accept:

* A public URL
* A stored file
* A data URL

Before sending, Zaia converts the image into the format accepted by the WhatsApp API.

***

### ✍️ Defining the Message Content

For **text** mode, content is controlled by prompt instructions.

You can:

* Define a fixed message
* Instruct the Agent to generate the message dynamically

For **template** modes, content comes from the selected WhatsApp template and its variables.

#### Example instruction

> “When you create a support ticket, send a WhatsApp message to **11 984444444** containing:
>
> * A summary of the conversation so far
> * The user’s phone number as a clickable link in the format\
>   `https://wa.me/55{{user_phone}}`”

In this case, the Agent writes the text, injects context, and sends the message to the selected number.

***

### ✅ Validations and Restrictions

Zaia validates template data before sending.

This includes limits for fields such as:

* Body text
* Header text
* OTP values
* Button URL suffixes

Templates only work when the official WhatsApp connection is active and correctly configured. If the template cannot be resolved or validated by Meta, the send is blocked.

For Workflow-based outbound messaging, see [Message Sending Node](/workflows/workflow-nodes/message-sending-node.md). For official connection requirements, see [WhatsApp (Official)](/channels/channel-types/whatsapp-official.md).

***

### 📌 Recommended Usage Pattern

Use a dedicated phone number for outbound notifications whenever possible.

This helps:

* Protect your main number reputation
* Control outbound volume
* Isolate operational traffic from live conversations

***

### 🧠 Best Practices

* Be explicit in the tool description so the Agent knows when to send
* Use **text** for active conversations
* Use **template** when you need an approved outbound message
* Use **text with template fallback** only when a valid fallback template exists
* Avoid excessive outbound traffic

***

### ✅ Key Takeaway

The **Message Sending** Tool supports both text and approved WhatsApp templates.

With an official WhatsApp connection, you can send text, send templates directly, or recover from an expired 24-hour window with controlled template fallback.