WhatsApp Toolkit

Send outbound messages, media, and pre-approved templates through the WhatsApp Business API from your agents and workflows.

The WhatsApp Toolkit provides programmatic access to the WhatsApp Business Platform (Cloud API). It enables agents and workflows to send outbound messages including text, media, pre-approved templates, and advanced message types via the Meta Graph API. Receiving or processing inbound WhatsApp messages is not supported.

Prerequisites

Before creating a connection, you will need the following from Meta:

Requirement	Where to Get It
WhatsApp Business Account (verified)	Meta Business Manager
System User Access Token	Meta Business Manager → System Users
Phone Number ID	WhatsApp Manager → Phone Numbers
Business Account ID	Optional — required for advanced Graph API calls
Approved message templates	Meta Business Manager → Account Tools → Message Templates

Creating a Connection

The WhatsApp Toolkit is available in both the Agent Builder and the Workflow Builder. The connection setup is the same in both, but the navigation path differs.

Agent Toolkit

1. Open your agent in the Agent Builder
2. Go to the Toolkits tab in the left sidebar
3. Find WhatsApp and click Add to Agent
4. In the Toolkit panel, click Select a Connection > Create a Connection
5. In the pop-up that appears, enter a Connection Name, your System User Access Token, Business Account ID.
6. Enter your Access Token, Business Account ID (optional), and a display Name for the connection
7. Click Save — EKB will validate the credentials before saving

Workflow Toolkit

1. Open your workflow in the Workflow Builder
2. Add a new step and select WhatsApp from the toolkit list
3. Click Add Connection
4. Enter your Access Token, Phone Number ID, Business Account ID (optional), and a display Name for the connection
5. Click Save — EKB will validate the credentials before saving

Available Tools

Tool	Description
Send Message	Send a plain text message (up to 4,096 characters, UTF-8) within the 24-hour session window
Send Media	Send an image, video, audio, or document via a public HTTPS URL, with optional caption or filename
Send Template	Send a pre-approved template message — required for outbound messaging outside the 24-hour session window
Custom API Call	Make a direct call to any Meta Graph API endpoint for advanced use cases (see below)

Custom API Call

The Custom API Call tool is the most extensible option. It allows direct access to WhatsApp Graph API endpoints beyond what the other tools cover, including:

• Interactive messages (buttons, lists)
• Location and contact cards
• Product catalog messages
• Programmatic template management
• Business profile updates
• Messaging analytics and insights

Configuration Notes

• Phone number format: Always use E.164 international format (e.g., +1..., +52...). Spaces, dashes, or a missing country code will cause delivery failures (error 1006).
• Session window: Plain text and media messages can only be sent within a 24-hour window of the recipient’s last message. Outside that window, use a Send Template instead.
• Media URLs: Must be publicly accessible over HTTPS. Private, localhost, or expired URLs will cause download failures (error 1011). Verify MIME types match the file content.
• Templates: Must be approved in Meta Business Manager before use. Parameter count and order must match the approved template exactly. Monitor your template quality rating — a low rating can result in a template being paused (error 131056).
• Rate limits: WhatsApp Business API enforces per-number and per-day messaging limits. For bulk sending, use queues and implement retry logic with exponential backoff.
• Security: Store access tokens securely and rotate credentials periodically. Ensure user consent is obtained before sending marketing messages.

Practical Examples

• Customer Support: An agent receives a support request, looks up the customer record, and sends a WhatsApp message with the ticket number and next steps — or uses an interactive button template to route the user to the right team.
• Transactional Notifications: A workflow triggers after an order is placed and sends a template with order confirmation, shipping updates, or payment notifications.
• Document Delivery: An agent generates a PDF invoice or contract and delivers it via the Send Media tool with a descriptive caption.
• Broadcast Campaigns: A workflow iterates over a contact list and sends an approved marketing template with personalized parameter substitution.

Troubleshooting

Error Code	Symptom	Fix
401 / 190	Invalid access token	Regenerate the System User token in Meta Business Manager and update the connection
33	Invalid Phone Number ID	Verify the Phone Number ID in WhatsApp Manager
1006	Invalid phone number format	Use E.164 format — include + and country code, no spaces or dashes
131005	Template not found	Confirm the template name and that it exists in Meta Business Manager
131056	Template paused	Check the template’s quality rating in Meta Business Manager
1011	Media download failed	Use a public HTTPS URL and confirm the file type and MIME type are supported

If the error is not listed above, use the Debug Checklist:

1. Verify credentials and that the connection is valid
2. Confirm the recipient’s phone number is registered on WhatsApp
3. Validate the message format and payload structure
4. Confirm template approval status
5. Check whether API rate limits have been reached