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:
The Agent decides whether a message should be sent.
It determines the destination phone number.
It uses the configured send mode.
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. For official connection requirements, see WhatsApp (Official).
📌 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.
Last updated