# Twilio SMS Tool

Send SMS messages using the Twilio API

URL: https://agentkit.tech/docs/tools/built-in/twilio-sms.mdx

The Twilio SMS tool enables sending SMS messages using the Twilio API.

## Installation

```go
import "github.com/model-box/agent-kit/tool/twilio"
```

## Setup

### Requirements

1. **Twilio Account**: Sign up at [Twilio](https://www.twilio.com/)
2. **Twilio Phone Number**: Purchase a phone number or use trial number
3. **API Credentials**: Get Account SID and Auth Token from the Twilio Console

### Environment Variables

```bash
export TWILIO_ACCOUNT_SID="your-account-sid"
export TWILIO_AUTH_TOKEN="your-auth-token"
export TWILIO_PHONE_NUMBER="+1234567890"  # Your Twilio phone number
```

## Usage

```go
package main

import (
    "context"
    "os"
    
    "github.com/model-box/agent-kit/agent"
    "github.com/model-box/agent-kit/model"
    "github.com/model-box/agent-kit/session"
    "github.com/model-box/agent-kit/tool/twilio"
)

func main() {
    // Create Twilio tools
    twilioTools := twilio.NewTwilioTools()
    
    // Create model
    model := model.Model("gpt-4o").
        SetAPIKey(os.Getenv("OPENAI_API_KEY"))
    
    // Create agent with Twilio SMS tool
    agent := agent.New().
        SetModel(model).
        SetSystemPrompt("You are a helpful assistant that can send SMS messages.").
        AddTool(twilioTools.SendSMS())
    
    // Create session and run
    session := session.New(agent)
    ctx := context.Background()
    
    response, err := session.Run(ctx, []agent.ChatMessage{
        agent.NewUserMessage("Send an SMS to +1234567890 saying 'Hello from AgentKit!'"),
    }, nil)
    
    if err != nil {
        panic(err)
    }
    
    println(response.GetLastMessage().GetContent())
}
```

## Parameters

| Parameter   | Type   | Required | Description                               |
| ----------- | ------ | -------- | ----------------------------------------- |
| `to`        | string | Yes      | Recipient phone number in E.164 format    |
| `body`      | string | Yes      | SMS message body                          |
| `from`      | string | No       | Sender phone number (defaults to env var) |
| `media_url` | string | No       | URL of media to send (MMS)                |

## Phone Number Format

Use E.164 format: `+[country code][phone number]`

* Example: `+14155552671`

## Trial Account Limitations

* Can only send to verified phone numbers
* Messages prefixed with "Sent from your Twilio trial account"
* Limited daily message quota

## Status Values

* `queued`: Message queued for delivery
* `sending`: Message being sent
* `sent`: Message sent
* `delivered`: Message delivered
* `failed`: Message failed to send