WhatsApp

WhatsAppTools enable an Agent to interact with the WhatsApp Business API, allowing it to send text and template messages.

Prerequisites

This cookbook demonstrates how to use WhatsApp integration with Agno. Before running this example, you'''ll need to complete these setup steps:

1. Create Meta Developer Account

   • Go to Meta Developer Portal and create a new account
   • Create a new app at Meta Apps Dashboard
   • Enable WhatsApp integration for your app here

2. Set Up WhatsApp Business API You can get your WhatsApp Business Account ID from Business Settings

3. Configure Environment

   • Set these environment variables:
     export WHATSAPP_ACCESS_TOKEN=your_access_token          # Access Token
     export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id    # Phone Number ID
     export WHATSAPP_RECIPIENT_WAID=your_recipient_waid      # Recipient WhatsApp ID (e.g. 1234567890)
     export WHATSAPP_VERSION=your_whatsapp_version           # WhatsApp API Version (e.g. v22.0)
     

Important Notes:

• For first-time outreach, you must use pre-approved message templates here
• Test messages can only be sent to numbers that are registered in your test environment

The example below shows how to send a template message using Agno'''s WhatsApp tools. For more complex use cases, check out the WhatsApp Cloud API documentation: here

Example

The following agent will send a template message using WhatsApp:

cookbook/tools/whatsapp_tool.py

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.whatsapp import WhatsAppTools

agent = Agent(
    name="whatsapp",
    model=Gemini(id="gemini-2.0-flash"),
    tools=[WhatsAppTools()],
    show_tool_calls=True
)

# Example: Send a template message
# Note: Replace '''hello_world''' with your actual template name
# and [phone] with the recipient's WhatsApp ID
agent.print_response(
    "Send a template message using the '''hello_world''' template in English to [phone]"
)

Toolkit Params

Parameter	Type	Default	Description
access_token	Optional[str]	None	WhatsApp Business API access token. If not provided, uses WHATSAPP_ACCESS_TOKEN environment variable.
phone_number_id	Optional[str]	None	WhatsApp Business Account phone number ID. If not provided, uses WHATSAPP_PHONE_NUMBER_ID environment variable.
version	str	"v22.0"	API version to use. If not provided, uses WHATSAPP_VERSION environment variable or defaults to “v22.0”.
recipient_waid	Optional[str]	None	Default recipient WhatsApp ID (e.g., “1234567890”). If not provided, uses WHATSAPP_RECIPIENT_WAID environment variable.
async_mode	bool	False	Enable asynchronous methods for sending messages.

Toolkit Functions

Function	Description
send_text_message_sync	Sends a text message to a WhatsApp user (synchronous). Parameters: text (str), recipient (Optional[str]), preview_url (bool), recipient_type (str).
send_template_message_sync	Sends a template message to a WhatsApp user (synchronous). Parameters: recipient (Optional[str]), template_name (str), language_code (str), components (Optional[List[Dict[str, Any]]]).
send_text_message_async	Sends a text message to a WhatsApp user (asynchronous). Parameters: text (str), recipient (Optional[str]), preview_url (bool), recipient_type (str).
send_template_message_async	Sends a template message to a WhatsApp user (asynchronous). Parameters: recipient (Optional[str]), template_name (str), language_code (str), components (Optional[List[Dict[str, Any]]]).

Developer Resources

• View Tools
• View Cookbook