Skip to main content

Twilio SMS

Instantly send SMS notifications and alerts from your agents using Twilio.

This guide will walk you through setting up Twilio integration, configuring the required credentials, and sending your first message.

💡 Core Concepts​

To configure this tool, you need to understand two key components.

1. How does the Twilio SMS Tool work?​

The Twilio SMS tool allows your agent to send text messages to mobile phones globally.

2. What are the Twilio Credentials?​

You need three pieces of information from your Twilio console to authorize the agent:

  • Account SID (TWILIO_SID): Your unique account identifier.
  • Auth Token (TWILIO_AUTH_TOKEN): Your secret key for API access.
  • Twilio Phone Number (from): A number purchased or assigned in your Twilio account that is capable of sending SMS.

⚙️ Configuration Steps​

Follow these steps to integrate Twilio SMS into your agent network.

Get Twilio Credentials​

  1. Log in to your Twilio Console.
  2. Copy your Account SID and Auth Token from the dashboard.
  3. Navigate to Phone Numbers and copy the active number you wish to send messages from.

Configure Agent Tools​

  1. Assign the Tool:
    • In your agent's YAML configuration, add Twilio_sms to the tool_assigned list.
  2. Set Credentials:
    • Add your credentials in the config block.
    • Security Note: It is highly recommended to use SVAHNAR Key Vault (e.g., ${TWILIO_SID}) rather than hardcoding secrets directly in the YAML.
info

You can pre-define the to and from numbers in the config if your agent always messages the same recipient or uses the same sender ID.

Define Agent Function​

Give your agent a clear instruction on when to send an SMS.

📚 Practical Recipes (Examples)​

Recipe 1: Basic SMS Notification Agent​

Use Case: An agent that sends a critical alert to a specific admin number when triggered.

create_vertical_agent_network:
  agent-1:
    agent_name: alert_agent
    LLM_config:
        params:
          model: gpt-4o
    tools:
      tool_assigned:
        - name: Twilio_sms
          config:
            # Twilio Credentials (use env vars for security)
            TWILIO_SID: ${TWILIO_SID}
            TWILIO_AUTH_TOKEN: ${TWILIO_AUTH_TOKEN}
            # The Twilio number sending the SMS
            from: "+15550109988"
            # Optional: Hardcode the recipient if it's always the same
            to: "+15550199999"
    agent_function:
      - You are a monitoring assistant. When asked to send an alert, use the Twilio tool to send the message immediately.
    incoming_edge:
      - Start
    outgoing_edge: []

💡 Tip: Dynamic Payloads​

If you don't hardcode to, from, or body in the config, the agent will dynamically generate them based on the context.

  • Dynamic Recipient: "Send a text to +1555... saying 'Hello'."
  • Dynamic Body: "Text the admin the current summary of the report."

🚑 Troubleshooting​

  • Missing Required Fields

    • Ensure the agent or the config provides all three: to (recipient), from (sender), and body (message text).

  • Authentication Failed

    • Verify your TWILIO_SID and TWILIO_AUTH_TOKEN are correct.
    • Ensure SVAHNAR Key Vault is correctly configured if using ${...} syntax.

  • Invalid Phone Numbers

    • Use E.164 format for all phone numbers (e.g., +1234567890 or +919876543210).
    • Ensure the from number is a valid, active Twilio number capable of sending SMS.

  • Message Not Sent

    • The tool returns the Twilio SID on success. If you don't see an SID in the tool response, the message likely failed at the API level.