Skip to main content

Twilio WhatsApp

Send automated WhatsApp messages directly from your agents using Twilio.

This guide will walk you through setting up Twilio credentials, configuring your agent, and sending messages.

💡 Core Concepts​

To configure this tool, you need to understand the required credentials and message structure.

1. What credentials are required?​

To authorize the agent, you need your Twilio Account SID and Auth Token. These act as the username and password for the API.

2. How does the message routing work?​

  • From Number (from): The WhatsApp-enabled number (or Twilio Sandbox number) sending the message.
  • To Number (to): The recipient's phone number.
  • Prefixes: The tool automatically handles the whatsapp: prefix, so you can provide numbers in E.164 format (e.g., +15550001234) or with the prefix included.

⚙️ Configuration Steps​

Follow these steps to integrate Twilio WhatsApp with SVAHNAR.

Get Twilio Credentials​

  1. Log in to your Twilio Console.
  2. Locate the Account Info section on the dashboard.
  3. Copy your Account SID and Auth Token.
tip

If you are testing, enable the Twilio WhatsApp Sandbox in your console to send messages without waiting for business verification.

Configure the Tool​

  1. Open your agent configuration YAML.
  2. Add the Twilio_whatsapp tool.
  3. Paste your credentials into the config section.
Format Check

Ensure phone numbers are in E.164 format (e.g., whatsapp:+15550001234).

Define Agent Instructions​

  1. In the agent_function, explicitly tell the agent what information to send.
  2. Example: "Send a WhatsApp message to the user with their appointment details."

📚 Practical Recipes (Examples)​

Recipe 1: Standard Notification Agent​

Use Case: An agent that sends a confirmation message to a specific user.

create_vertical_agent_network:
  agent-1:
    agent_name: whatsapp_notifier
    LLM_config:
        params:
          model: gpt-4o
    tools:
      tool_assigned:
        - name: Twilio_whatsapp
          config:
            # Twilio Credentials (Best practice: use SVAHNAR Key Vault)
            TWILIO_SID: ${TWILIO_SID}
            TWILIO_AUTH_TOKEN: ${TWILIO_AUTH_TOKEN}
            
            # The sender number (Twilio Sandbox or Verified Business Number)
            from: "whatsapp:+14155238886"
            CONTENT_SID: "" #OPTIONAL: Use this for template messages
            CONTENT_VARIABLES:  #OPTIONAL: Use this for template messages
    agent_function:
      - You are a notification assistant.
      - Your goal is to send a WhatsApp message to the user: "whatsapp:+1234567890".
      - The message body should be: "Hello! Your server deployment is complete."
    incoming_edge:
      - Start
    outgoing_edge: []

💡 Tip: Dynamic vs. Static Configuration​

  • Static Config: Place items that never change (like TWILIO_SID or from) in the config block.
  • Dynamic Payload: The agent will automatically generate the to and body_message fields based on the conversation context.

🚑 Troubleshooting​

  • "Missing Required Fields" Error

    • The tool strictly requires to, from. Ensure the agent's prompt is clear enough to generate the messages and that a to number is provided either in the prompt or the config.

  • "Unverified Number" (Sandbox Mode)

    • If you are using the Twilio Sandbox, you can only send messages to numbers that have joined your sandbox (by sending a specific code to your Twilio number).
    • To message any number, you must complete Twilio's Business Verification.

  • Template Errors

    • If using CONTENT_SID (for templates), ensure your CONTENT_VARIABLES match the template's expected format in Twilio.
tip

If you are using the template message, you need to provide CONTENT_SID and CONTENT_VARIABLES. and require to use JSON format for the CONTENT_VARIABLES check out our JSON to YAML conversion guide.