Twilio Conversations API: Multi-Channel Chat and Messaging Platform

import os
from twilio.rest import Client

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

# Create a conversation
def create_conversation(friendly_name, service_sid=None):
    params = {
        "friendly_name": friendly_name
    }
    if service_sid:
        params["chat_service_sid"] = service_sid
    conversation = client.conversations.conversations.create(**params)
    print(f"Conversation SID: {conversation.sid}")
    print(f"Name: {conversation.friendly_name}")
    print(f"State: {conversation.state}")
    print(f"Created: {conversation.date_created}")
    return conversation

conv = create_conversation("DodaTech Support - Order ORD-12345")
# Expected output:
# Conversation SID: CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Name: DodaTech Support - Order ORD-12345
# State: active
# Created: 2026-06-28 10:00:00

# Add an SMS participant
def add_sms_participant(conversation_sid, phone_number, messaging_service_sid):
    participant = client.conversations \
        .conversations(conversation_sid) \
        .participants.create(
            messaging_binding_address=phone_number,
            messaging_binding_proxy_address=messaging_service_sid
        )
    print(f"SMS Participant SID: {participant.sid}")
    print(f"Identity: {participant.identity or phone_number}")
    print(f"Type: SMS")
    return participant

# Add a WhatsApp participant
def add_whatsapp_participant(conversation_sid, whatsapp_number):
    participant = client.conversations \
        .conversations(conversation_sid) \
        .participants.create(
            messaging_binding_address=f"whatsapp:{whatsapp_number}",
            messaging_binding_proxy_address="whatsapp:+14155238886"
        )
    print(f"WhatsApp Participant: {participant.sid}")
    return participant

# Add a chat participant (in-app)
def add_chat_participant(conversation_sid, identity):
    participant = client.conversations \
        .conversations(conversation_sid) \
        .participants.create(
            identity=identity
        )
    print(f"Chat Participant: {participant.sid} ({identity})")
    return participant

# Expected output:
# SMS Participant SID: MBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Identity: +14155551234
# Type: SMS

# Send a message to the conversation (appears on all channels)
def send_message_to_conversation(conversation_sid, author, body):
    message = client.conversations \
        .conversations(conversation_sid) \
        .messages.create(
            author=author,
            body=body
        )
    print(f"Message SID: {message.sid}")
    print(f"Author: {message.author}")
    print(f"Body: {message.body}")
    print(f"Index: {message.index}")
    return message

msg = send_message_to_conversation(
    conv.sid,
    "DodaTech Support Agent",
    "Hi there! I see your order ORD-12345 is on its way."
)
# Expected output:
# Message SID: IMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Author: DodaTech Support Agent
# Body: Hi there! I see your order ORD-12345 is on its way.
# Index: 1

# Retrieve conversation messages
def get_conversation_messages(conversation_sid, limit=20):
    messages = client.conversations \
        .conversations(conversation_sid) \
        .messages.list(limit=limit)
    print(f"Messages in conversation: {len(messages)}")
    for msg in messages:
        print(f"  [{msg.index}] {msg.author}: {msg.body[:60]}")
    return messages

# get_conversation_messages(conv.sid)
# Expected output:
# Messages in conversation: 2
#   [1] DodaTech Support Agent: Hi there! I see your order ORD-12345...
#   [2] +14155551234: Thanks! When will it arrive?

def update_conversation_state(conversation_sid, new_state):
    """States: active, inactive, closed"""
    valid_states = ["active", "inactive", "closed"]
    if new_state not in valid_states:
        raise ValueError(f"Invalid state: {new_state}")
    conversation = client.conversations \
        .conversations(conversation_sid) \
        .update(state=new_state)
    print(f"Conversation: {conversation.sid}")
    print(f"State changed to: {conversation.state}")
    return conversation

# Close a resolved conversation
update_conversation_state(conv.sid, "closed")
# Expected output:
# Conversation: CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# State changed to: closed

# Set conversation timers
def set_conversation_timers(conversation_sid, after=86400):
    """Auto-close conversation after N seconds of inactivity."""
    conversation = client.conversations \
        .conversations(conversation_sid) \
        .update(
            timers_inactive=after,
            timers_closed=after * 7  # Close after 7 days inactive
        )
    print(f"Timers set: inactive={after}s, closed={after*7}s")
    return conversation