Skip to main content
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.
export WHATSAPP_ACCESS_TOKEN=your_access_token
export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
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

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-flash-preview"),
    tools=[WhatsAppTools()],
)

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

​
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 cookbook/05_agent_os/interfaces/whatsapp/interactive_concierge.py for a full example.

​
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.

​
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