Conversations
The Conversations API turns one‑off SMS into persistent, multi‑party threads that can span SMS, MMS, WhatsApp, and in‑app chat — all unified into a single conversation object with participants, messages, and webhooks.
Use Conversations when you need history, multiple participants, or mixed channels in the same thread. For one‑way transactional sends, Messaging is simpler.
Mental Model
A Conversation has:
- Participants — phone numbers (SMS/WhatsApp) or chat user identities
- Messages — text and media exchanged in the thread
- Webhooks — your endpoints called on participant joins, new messages, delivery updates
- Optional service scoping — group conversations under a
Servicefor separate webhook configs, defaults, and limits
The Conversations Building Blocks
Conversation
Create, list, update, and delete conversation threads. Both account‑scoped and service‑scoped variants.
Conversation With Participants
Create a conversation and add participants in a single atomic request.
Participant
Add SMS/WhatsApp numbers or chat identities to a conversation. Manage roles and bindings per participant.
Message
Post messages into a conversation, list history, and update or delete individual messages.
Delivery Receipt
Per‑participant delivery status for each outbound message — see who received, read, or failed each one.
Webhook
Configure conversation‑scoped or service‑scoped webhooks for events like onMessageAdded and onParticipantAdded.
Role
Define permissions (e.g. service user, channel admin) that you can assign to participants.
User
Manage chat user identities and their state across conversations.
Service
Isolate conversations into named services — each with its own webhooks, defaults, and configuration.
Address Configuration
Tell Twilio which phone numbers or channels should auto‑create conversations when a message arrives.
Notification
Per‑service push notification config — how Twilio notifies offline participants of new activity.
Configuration & Binding
Global defaults (default service, callback URLs) and per‑device push bindings.