twilio-conversations-classic-api

What this skill does

## Overview

Conversations (classic) API provides persistent, multi-channel threads where participants on SMS, WhatsApp, and web chat can message together. Unlike single-message APIs, Conversations maintains history and supports multi-agent access.

**Note:** This is the Conversations (classic) API (v1).

---

## Prerequisites

- Twilio account with Conversations (classic) enabled
  — New to Twilio? See `twilio-account-setup`
  — Enable at: [Console > Conversations > Manage > Overview](https://console.twilio.com/us1/develop/conversations/manage/overview) > **Enable Conversations**
- Environment variables:
  - `TWILIO_ACCOUNT_SID`
  - `TWILIO_AUTH_TOKEN`
  — See `twilio-iam-auth-setup` for credential setup and best practices
- SDK: `pip install twilio` / `npm install twilio`
- For SMS/WhatsApp participants: a Twilio number assigned to a Conversations Service

---

## Setup: Create a Conversation Service (classic)

A Conversation Service is the parent configuration container for all your conversations in the classic API. You need one before creating conversations with SMS/WhatsApp participants.

**Python**
```python
import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

# Create a Conversation Service
service = client.conversations.v1.services.create(
    friendly_name="Customer Support Service"
)
print(f"Service SID: {service.sid}")
```

**Node.js**
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

// Create a Conversation Service
const service = await client.conversations.v1.services.create({
    friendlyName: "Customer Support Service"
});
console.log(`Service SID: ${service.sid}`);
```

**Next:** Assign your Twilio phone number to this service at [Console > Conversations > Manage > Services](https://console.twilio.com/us1/develop/conversations/manage/services) > Select your service > Add phone number.

---

## Quickstart

**Python**
```python
import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

# Create a conversation (use default service or specify service_sid)
conversation = client.conversations.v1.conversations.create(
    friendly_name="Customer Support - Order #12345"
)

# Add an SMS participant
client.conversations.v1 \
    .conversations(conversation.sid) \
    .participants \
    .create(
        messaging_binding_address="+15558675310",
        messaging_binding_proxy_address="+15017122661"
    )

# Send a message
client.conversations.v1 \
    .conversations(conversation.sid) \
    .messages \
    .create(body="Hello! How can I help you today?", author="support-agent")
```

**Node.js**
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

// Create a conversation (use default service or specify serviceSid)
const conversation = await client.conversations.v1.conversations.create({
    friendlyName: "Customer Support - Order #12345",
});

// Add an SMS participant
await client.conversations.v1
    .conversations(conversation.sid)
    .participants.create({
        messagingBindingAddress: "+15558675310",
        messagingBindingProxyAddress: "+15017122661",
    });

// Send a message
await client.conversations.v1
    .conversations(conversation.sid)
    .messages.create({ body: "Hello! How can I help you today?", author: "support-agent" });
```

---

## Key Patterns

### Add Participants by Channel

**WhatsApp participant — Python**
```python
client.conversations.v1 \
    .conversations(conversation.sid) \
    .participants \
    .create(
        messaging_binding_address="whatsapp:+15558675310",
        messaging_binding_proxy_address="whatsapp:+14155238886"
    )
```

**WhatsApp participant — Node.js**
```node
await client.conversations.v1
    .conversations(conversationSid)
    .participants.create({
        messagingBindingAddress: "whatsapp:+15558675310",
        messagingBindingProxyAddress: "whatsapp:+14155238886",
    });
```

**Chat participant (web/mobile) — Python**
```python
client.conversations.v1 \
    .conversations(conversation.sid) \
    .participants \
    .create(identity="user-123")
```

**Chat participant (web/mobile) — Node.js**
```node
await client.conversations.v1
    .conversations(conversationSid)
    .participants.create({ identity: "user-123" });
```

### Send Media (All Channels)

**Python**
```python
# Send a message with media
client.conversations.v1 \
    .conversations(conversation.sid) \
    .messages \
    .create(
        body="Check out this image!",
        author="support-agent",
        media_url="https://example.com/image.jpg"
    )

# Multiple media URLs (up to 10)
client.conversations.v1 \
    .conversations(conversation.sid) \
    .messages \
    .create(
        body="Here are the documents",
        author="support-agent",
        media_url=[
            "https://example.com/doc1.pdf",
            "https://example.com/doc2.pdf"
        ]
    )
```

**Node.js**
```node
// Send a message with media
await client.conversations.v1
    .conversations(conversationSid)
    .messages.create({
        body: "Check out this image!",
        author: "support-agent",
        mediaUrl: "https://example.com/image.jpg"
    });

// Multiple media URLs (up to 10)
await client.conversations.v1
    .conversations(conversationSid)
    .messages.create({
        body: "Here are the documents",
        author: "support-agent",
        mediaUrl: [
            "https://example.com/doc1.pdf",
            "https://example.com/doc2.pdf"
        ]
    });
```

Media must be publicly accessible URLs. Supported: JPG, PNG, GIF, PDF, vCard. Max 10 URLs per message. Works across all channels: SMS (as MMS), WhatsApp, and chat participants all receive media.

### Add Multiple Participants

**Python**
```python
# Add multiple SMS participants to a conversation
participant_numbers = [
    "+15558675310",
    "+15558675311",
    "+15558675312"
]

twilio_number = "+15017122661"

for phone_number in participant_numbers:
    client.conversations.v1 \
        .conversations(conversation.sid) \
        .participants \
        .create(
            messaging_binding_address=phone_number,
            messaging_binding_proxy_address=twilio_number
        )
```

**Node.js**
```node
// Add multiple SMS participants to a conversation
const participantNumbers = [
    "+15558675310",
    "+15558675311",
    "+15558675312"
];

const twilioNumber = "+15017122661";

for (const phoneNumber of participantNumbers) {
    await client.conversations.v1
        .conversations(conversationSid)
        .participants.create({
            messagingBindingAddress: phoneNumber,
            messagingBindingProxyAddress: twilioNumber
        });
}
```

### Fetch Message History

**Python**
```python
# Get all messages from a conversation
messages = client.conversations.v1 \
    .conversations(conversation.sid) \
    .messages \
    .list(limit=50)

for message in messages:
    print(f"{message.author}: {message.body}")
```

**Node.js**
```node
// Get all messages from a conversation
const messages = await client.conversations.v1
    .conversations(conversationSid)
    .messages
    .list({ limit: 50 });

messages.forEach(message => {
    console.log(`${message.author}: ${message.body}`);
});
```

### List Conversations

**Python**
```python
# List all conversations
conversations = client.conversations.v1.conversations.list(limit=20)

for conv in conversations:
    print(f"{conv.friendly_name} - {conv.sid}")

# Filter by state
active_conversations = client.conversations.v1.conversations.list(
    state="active",
    limit=20
)
```

**Node.js**
```node
// List all conversations
const conversations = await client.conversations.v1.conversations.list({ limit: 20 });

conversations.forEach(conv => {
    console.log(`${conv.friendlyName} - ${conv.sid}`);
});

// Filter by state