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

# WhatsApp Integration for AI Agents & Workflows

> Send WhatsApp messages through the WhatsApp Cloud API (Meta Graph API). Deliver text messages with optional link previews directly to recipients on WhatsApp.

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/whatsapp.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=bb70b5df844a1dc3dd1938506f3f33f8" alt="WhatsApp logo" width="72" height="72" data-path="logos/whatsapp.svg" />

## Overview

Add **WhatsApp** to any ModuleX agent or workflow. Send WhatsApp messages through the WhatsApp Cloud API (Meta Graph API, `graph.facebook.com`). Deliver plain-text messages with optional link previews directly to recipients on WhatsApp.

<Info>
  **Categories**: Communication · Messaging · Automation · **Auth**: API Key · **Actions**: 1
</Info>

## Authentication

### API Key Authentication

Authenticate using your WhatsApp Business API access token (used as the bearer token on every request)

<Steps>
  <Step title="Step 1">
    Go to [https://developers.facebook.com](https://developers.facebook.com) and open your Meta app
  </Step>

  <Step title="Step 2">
    Add the WhatsApp product and configure a Business Phone Number
  </Step>

  <Step title="Step 3">
    Copy the WhatsApp Business API access token (a temporary token is available in the dashboard; generate a permanent System User token for production)
  </Step>

  <Step title="Step 4">
    Note your WhatsApp Business Phone Number ID for each send call
  </Step>

  <Step title="Step 5">
    Paste the access token below
  </Step>
</Steps>

#### Required Credentials

| Field                 | Description                                                       | Required | Format |
| --------------------- | ----------------------------------------------------------------- | -------- | ------ |
| WhatsApp Access Token | WhatsApp Business API access token from the Meta Developer Portal | Yes      | `-`    |

## Available Actions

<AccordionGroup>
  <Accordion title="send_message — Send a text message through the WhatsApp Cloud API.">
    ### Parameters

    <ResponseField name="phone_number" type="string" required>
      Recipient phone number with country code (e.g., +14155552671)
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Plain text message content to send
    </ResponseField>

    <ResponseField name="phone_number_id" type="string" required>
      WhatsApp Business Phone Number ID (from Meta Business Suite)
    </ResponseField>

    <ResponseField name="preview_url" type="boolean">
      Whether WhatsApp should try to render a link preview for the first URL in the message
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "MessageContact": {
          "additionalProperties": false,
          "description": "A single recipient contact record returned by the send API.",
          "properties": {
            "input": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Input"
            },
            "wa_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Wa Id"
            }
          },
          "title": "MessageContact",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "message_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message Id"
        },
        "message_status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message Status"
        },
        "messaging_product": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Messaging Product"
        },
        "input_phone_number": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Input Phone Number"
        },
        "whatsapp_user_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Whatsapp User Id"
        },
        "contacts": {
          "items": {
            "$ref": "#/$defs/MessageContact"
          },
          "title": "Contacts",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* **Messaging tiers**: WhatsApp enforces per-business-phone-number
  conversation/message throughput tiers (1K, 10K, 100K, unlimited
  business-initiated conversations per 24h), scaling with quality rating.
* **24-hour window**: free-form text messages can only be sent inside an
  open 24-hour customer service window; outside it, an approved message
  template is required (template sending is not exposed by this tool).
* **Error model**: non-2xx responses and timeouts are caught and returned
  as `success=False` + `error` rather than raising. A successful send that
  lacks a message ID is also reported as `success=False`. Plan for retries
  on the agent side based on the error string.

## Related integrations

<CardGroup cols={3}>
  <Card title="Telegram Bot" href="/integrations/tools/telegram" />

  <Card title="AgentMail" href="/integrations/tools/agentmail" />

  <Card title="Slack" href="/integrations/tools/slack" />
</CardGroup>

## Links

* [WhatsApp](https://www.whatsapp.com)