WhatsApp

WhatsAppTools enables an Agent to send text, template, image, document, location, and interactive messages through the WhatsApp Business Cloud API.

WhatsAppTools enable an Agent to send messages via the WhatsApp Business API: text, templates, images, documents, locations, reactions, and interactive messages (reply buttons, list menus).

Prerequisites

  1. Create a Meta Developer Account at the Meta Developer Portal.
  2. Create a new app at the Apps Dashboard and add the WhatsApp product.
  3. Get your Access Token and Phone Number ID from WhatsApp > API Setup.

Install the model provider for the example below:

uv pip install agno google-genai
export WHATSAPP_ACCESS_TOKEN=your_access_token
export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
export GOOGLE_API_KEY=your_google_api_key

For standalone use (outside the WhatsApp interface), also set a default recipient:

export WHATSAPP_RECIPIENT_WAID=recipient_phone_number # e.g. 1234567890

For first-time outreach to a user, you must use pre-approved message templates. Test messages can only be sent to numbers registered in your test environment.

Example

Replace the dummy recipient in the prompt with your registered test recipient (or an eligible production recipient). A recipient supplied in the tool call overrides WHATSAPP_RECIPIENT_WAID. The following agent sends a template message using WhatsApp:

cookbook/91_tools/whatsapp_tools.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-3.5-flash"),
    tools=[WhatsAppTools()],
)

agent.print_response(
    "Send a template message using the 'hello_world' template in English to +1 123456789"
)

Interactive Concierge Example

Use interactive features like reply buttons, list messages, and location pins:

from agno.tools.whatsapp import WhatsAppTools

tools = WhatsAppTools(
    enable_send_reply_buttons=True,
    enable_send_list_message=True,
    enable_send_location=True,
    enable_send_reaction=True,
    enable_send_image=True,
)

See the interactive WhatsApp example for a complete AgentOS application.

Toolkit Params

ParameterTypeDefaultDescription
access_tokenOptional[str]NoneWhatsApp Business API access token. Falls back to WHATSAPP_ACCESS_TOKEN env var.
phone_number_idOptional[str]NoneWhatsApp Business phone number ID. Falls back to WHATSAPP_PHONE_NUMBER_ID env var.
versionOptional[str]NoneAPI version (e.g., "v22.0"). Falls back to WHATSAPP_VERSION env var, then defaults to v22.0.
recipient_waidOptional[str]NoneDefault recipient WhatsApp ID. Falls back to WHATSAPP_RECIPIENT_WAID env var.
enable_send_text_messageboolTrueEnable the send_text_message tool.
enable_send_template_messageboolTrueEnable the send_template_message tool.
enable_send_reply_buttonsboolFalseEnable the send_reply_buttons tool.
enable_send_list_messageboolFalseEnable the send_list_message tool.
enable_send_imageboolFalseEnable the send_image tool.
enable_send_documentboolFalseEnable the send_document tool.
enable_send_locationboolFalseEnable the send_location tool.
enable_send_reactionboolFalseEnable the send_reaction tool.
allboolFalseEnable all tools when set to True.
timeoutint30Request timeout in seconds.

Toolkit Functions

FunctionDescription
send_text_messageSend a text message. Params: text, recipient (optional), preview_url (bool).
send_template_messageSend a pre-approved template. Params: template_name, recipient (optional), language_code, components.
send_reply_buttonsSend an interactive reply-button message (max 3 buttons). Params: body_text, buttons (list of ReplyButton), recipient, header, footer.
send_list_messageSend an interactive list menu (max 10 sections, 10 rows total). Params: body_text, button_text, sections (list of ListSection), recipient, header, footer.
send_imageSend an image by URL or media ID. Params: recipient, image_url, media_id, caption.
send_documentSend a document by URL or media ID. Params: recipient, document_url, media_id, filename, caption.
send_locationSend a location pin. Params: latitude, longitude, name, address, recipient.
send_reactionReact to a message with an emoji. Params: message_id, emoji, recipient.

Interactive Message Models

The toolkit includes Pydantic models for structured interactive messages:

ReplyButton: A quick-reply button for send_reply_buttons.

  • id (str): Unique button identifier (e.g., "yes", "no").
  • title (str): Button display text, max 20 characters.

ListSection: A section for send_list_message, containing ListRow items.

  • title (str): Section heading.
  • rows (list of ListRow): Selectable rows.

ListRow: A selectable row inside a ListSection.

  • id (str): Unique row identifier.
  • title (str): Row title text.
  • description (str, optional): Row description.
from agno.tools.whatsapp import ReplyButton, ListSection, ListRow

Developer Resources