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

# 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](https://business.facebook.com)    |
| 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.

<Tabs>
  <Tab title="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** — Odin AI Platform will validate the credentials before saving
  </Tab>

  <Tab title="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** — Odin AI Platform will validate the credentials before saving
  </Tab>
</Tabs>

## 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