{ "openapi": "3.0.1", "servers": [ { "url": "https://conversations.twilio.com" } ], "info": { "title": "Conversation Orchestrator", "description": "Manage configurations, conversations, participants, and communications. Create configurations to define capture rules and channel settings, then use conversations to group related communications.", "version": "2.0.0", "x-twilio": { "apiStandards": "v1.0" } }, "components": { "securitySchemes": { "basic_apikey_or_accountsid": { "scheme": "basic", "type": "http", "description": "This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing." } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "Conflict": { "description": "Conflict", "headers": { "X-Conflicting-Resource-Id": { "description": "The ID of the existing resource that conflicts.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "ServiceUnavailable": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "description": "Client-generated UUID key to ensure idempotent behavior. Submitting the same key returns the original response without creating a duplicate operation. Keys are scoped to account + region with a 24-hour TTL.", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "example": "01890a5d-aa0f-7c80-b8e6-0242ac140004" } }, "schemas": { "conversations.v2.conversation": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } }, "conversations.v2.participant": { "type": "object", "required": [ "id", "conversationId", "accountId", "name" ], "properties": { "id": { "type": "string", "description": "Participant ID.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "name": { "type": "string", "description": "Participant display name.", "example": "Dana S." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ], "description": "Type of Participant in the Conversation.", "example": "CUSTOMER" }, "profileId": { "type": "string", "description": "Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.", "example": "mem_profile_00000000000000000000000000" }, "addresses": { "type": "array", "description": "Communication addresses for this Participant. Address format varies by channel:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- EMAIL: Email address (such as \"user@example.com\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n", "items": { "$ref": "#/components/schemas/conversations.v2.address" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was last updated.", "example": "2023-07-01T12:00:00Z" } }, "example": { "id": "conv_participant_01k1etx3jbfx88476ccja0889c", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Dana", "type": "CUSTOMER", "profileId": "mem_profile_00000000000000000000000000", "addresses": [ { "channel": "SMS", "address": "+18005550100" }, { "channel": "WHATSAPP", "address": "whatsapp:+18005550100" }, { "channel": "RCS", "address": "rcs:+18005550100" } ], "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } }, "conversations.v2.address": { "type": "object", "required": [ "channel", "address" ], "properties": { "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ], "description": "The channel for Communication.", "example": "SMS" }, "address": { "type": "string", "description": "The address value formatted according to channel type:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n- CHAT: Customer-defined string identifier\n", "example": "+18005550100" }, "channelId": { "type": "string", "description": "Channel-specific ID for correlating Communications.", "example": "SM12345678901234567890123456789012" } }, "example": { "channel": "SMS", "address": "+18005550100" } }, "conversations.v2.communication": { "type": "object", "required": [ "id", "conversationId", "accountId", "author", "content", "recipients" ], "properties": { "id": { "type": "string", "description": "Communication ID.", "example": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "author": { "$ref": "#/components/schemas/conversations.v2.participant_address" }, "content": { "description": "The content of the Communication using type field for discrimination.", "oneOf": [ { "$ref": "#/components/schemas/conversations.v2.content_text" }, { "$ref": "#/components/schemas/conversations.v2.content_transcription" } ] }, "channelId": { "type": "string", "description": "Channel-specific reference ID.", "example": "CA123456789" }, "resourceId": { "type": "string", "minLength": 1, "description": "External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.", "example": "SM12345678901234567890123456789012" }, "recipients": { "type": "array", "description": "Communication recipients.", "items": { "allOf": [ { "$ref": "#/components/schemas/conversations.v2.participant_address" }, { "type": "object", "properties": { "deliveryStatus": { "type": "string", "description": "Delivery status of the Communication to this recipient.", "enum": [ "INITIATED", "IN_PROGRESS", "DELIVERED", "COMPLETED", "FAILED" ] } } } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was created.", "example": "2023-07-01T12:15:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was last updated.", "example": "2023-07-01T12:15:00Z" }, "occurredAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the communication occurred.", "example": "2023-07-01T12:15:00Z" } }, "example": { "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "author": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "content": { "type": "TEXT", "text": "Hello, I need help with my order" }, "resourceId": "SM12345678901234567890123456789012", "recipients": [ { "address": "+18005550102", "channel": "SMS", "participantId": "conv_participant_02m2fuy4lcgy99587ddkb1990d", "deliveryStatus": "DELIVERED" } ], "createdAt": "2023-07-01T12:15:00Z", "updatedAt": "2023-07-01T12:15:05Z" } }, "conversations.v2.participant_address": { "type": "object", "required": [ "address", "channel" ], "properties": { "address": { "type": "string", "description": "The address value formatted according to channel type:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n- CHAT: Customer-defined string identifier\n", "example": "+18005550100" }, "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ], "description": "Channel type for the Participant address.", "example": "SMS" }, "participantId": { "type": "string", "description": "Participant ID associated with this address.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" } }, "example": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" } }, "conversations.v2.send_address": { "type": "object", "required": [ "address", "channel" ], "properties": { "address": { "type": "string", "description": "The address value formatted according to channel type:\n- SMS: E.164 phone number (such as \"+18005550100\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n- CHAT: Customer-defined string identifier\n", "example": "+18005550100" }, "channel": { "type": "string", "enum": [ "SMS", "RCS", "WHATSAPP", "CHAT" ], "description": "Channel type for sending communications. Note: VOICE is receive-only and not supported for send operations.", "example": "SMS" }, "participantId": { "type": "string", "description": "Optional Participant ID. If omitted, the system will resolve or create the participant based on address and channel.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" } }, "example": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" } }, "conversations.v2.content_text": { "title": "ContentText", "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ], "description": "Content type discriminator.", "example": "TEXT" }, "text": { "type": "string", "description": "Message text content.", "example": "Hello, how can I help you today?" } }, "example": { "type": "TEXT", "text": "Hello, I need help with my order #12345" } }, "conversations.v2.content_transcription": { "title": "ContentTranscription", "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TRANSCRIPTION" ], "description": "Content type discriminator.", "example": "TRANSCRIPTION" }, "text": { "type": "string", "description": "Transcribed text.", "example": "Hello, how can I help you today?" }, "transcription": { "type": "object", "description": "Transcription metadata.", "properties": { "channel": { "type": "integer", "description": "Audio channel identifier (0 for inbound, 1 for outbound).", "example": 0 }, "confidence": { "type": "number", "format": "float", "minimum": 0.0, "maximum": 1.0, "description": "Overall confidence score for the transcription (0.0-1.0).", "example": 0.95 }, "engine": { "type": "string", "description": "Transcription engine used.", "example": "twilio" }, "words": { "type": "array", "description": "Word-level transcription data with timing information.", "items": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The transcribed word.", "example": "hello" }, "startTime": { "type": "string", "format": "date-time", "description": "Start timestamp of this word." }, "endTime": { "type": "string", "format": "date-time", "description": "End timestamp of this word." } } } } } } }, "example": { "type": "TRANSCRIPTION", "text": "Hi I need to check on my order status please", "transcription": { "channel": 0, "confidence": 0.95, "engine": "twilio", "words": [ { "text": "Hi", "startTime": "2023-07-01T10:30:00.000Z", "endTime": "2023-07-01T10:30:00.200Z" }, { "text": "I", "startTime": "2023-07-01T10:30:00.250Z", "endTime": "2023-07-01T10:30:00.350Z" }, { "text": "need", "startTime": "2023-07-01T10:30:00.400Z", "endTime": "2023-07-01T10:30:00.600Z" }, { "text": "to", "startTime": "2023-07-01T10:30:00.650Z", "endTime": "2023-07-01T10:30:00.750Z" }, { "text": "check", "startTime": "2023-07-01T10:30:00.800Z", "endTime": "2023-07-01T10:30:01.000Z" } ] } } }, "conversations.v2.send_message_participant": { "type": "object", "description": "Identifies a participant for an Action. Supports three resolution modes:\n1. participantId + channel: Resolves address from participant's registered addresses\n2. participantId only: Resolves when participant has exactly one address\n3. address + channel: Uses explicit address\n", "properties": { "participantId": { "type": "string", "description": "Participant ID to resolve address from.", "example": "conv_participant_01k1etx3jbfx88476ccja0889e" }, "address": { "type": "string", "description": "Explicit address formatted according to channel type.", "example": "+15551234567" }, "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ], "description": "Channel type for address resolution." } } }, "conversations.v2.send_message_action_request": { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "type": "string", "description": "Action type discriminator. Accepted values: SEND_MESSAGE.", "example": "SEND_MESSAGE" }, "payload": { "$ref": "#/components/schemas/conversations.v2.send_message_payload" } } }, "conversations.v2.send_message_payload": { "type": "object", "required": [ "from", "to", "content" ], "properties": { "from": { "$ref": "#/components/schemas/conversations.v2.send_message_participant" }, "to": { "type": "array", "minItems": 1, "description": "The recipients of this action.", "items": { "$ref": "#/components/schemas/conversations.v2.send_message_participant" } }, "content": { "$ref": "#/components/schemas/conversations.v2.send_message_content" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings" } } }, "conversations.v2.send_message_content": { "type": "object", "description": "Content for a SEND_MESSAGE action.", "additionalProperties": false, "properties": { "text": { "type": "string", "description": "Plain text message body.", "example": "Your order has shipped!" }, "contentId": { "type": "string", "description": "Content template ID (HX... format). When provided, the template is rendered\nwith the variables map and sent to the recipient.\n", "example": "HX78e8e67abc123def456789012345678" }, "variables": { "type": "object", "description": "Variables to substitute into the content template.", "additionalProperties": { "type": "string" }, "example": { "name": "Alice", "orderNumber": "12345" } }, "mediaUrls": { "type": "array", "description": "URLs of media attachments to include with the message.", "items": { "type": "string", "format": "uri" }, "example": [ "https://example.com/image.jpg" ] } } }, "conversations.v2.action": { "type": "object", "required": [ "id", "type", "status", "conversationId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this Action.", "example": "conv_action_01k1etx3jbfx88476ccja0889e" }, "type": { "type": "string", "description": "The type of action. Accepted values: SEND_MESSAGE.", "example": "SEND_MESSAGE" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Current status of the Action.\n- PENDING: Action accepted, awaiting downstream confirmation\n- COMPLETED: Downstream backend confirmed the action\n- FAILED: Downstream backend reported a failure\n", "example": "PENDING" }, "conversationId": { "type": "string", "description": "The conversation this action belongs to.", "example": "conv_conversation_01k1etx3jbfx88476ccja0889c" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Named identifiers from downstream. For SEND_MESSAGE:\n- messageSid: The downstream message SID (present when PENDING or COMPLETED)\n- communicationId: The Communication ID (present when COMPLETED)\n", "example": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was created.", "example": "2026-03-30T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was last updated.", "example": "2026-03-30T10:30:02Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action reached a terminal status.", "example": "2026-03-30T10:30:02Z" } }, "example": { "id": "conv_action_01k1etx3jbfx88476ccja0889e", "type": "SEND_MESSAGE", "status": "COMPLETED", "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c", "related": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" }, "createdAt": "2026-03-30T10:30:00Z", "completedAt": "2026-03-30T10:30:02Z" } }, "conversations.v2.communication_endpoint": { "type": "object", "description": "Endpoint for a communication participant. Supports three resolution modes:\n\n1. **participantId + channel**: Resolves address from participant's registered addresses\n2. **participantId only**: Resolves when participant has exactly one address\n3. **address + channel**: Uses explicit address (for new recipients or cross-channel)\n", "properties": { "participantId": { "type": "string", "description": "Participant ID to resolve address from. When provided, Conversations looks up\nthe participant's registered addresses and selects based on channel.\n", "example": "conv_participant_01k1etx3jbfx88476ccja0889e" }, "address": { "type": "string", "description": "Explicit address formatted according to channel type:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n- CHAT: Customer-defined string identifier\n", "example": "+18005550100" }, "channel": { "type": "string", "enum": [ "SMS", "RCS", "WHATSAPP", "CHAT" ], "description": "Channel type. Required when participantId has multiple addresses or when using explicit address.", "example": "SMS" } }, "example": { "participantId": "conv_participant_01k1etx3jbfx88476ccja0889e", "channel": "SMS" } }, "conversations.v2.send_content": { "type": "object", "description": "Content for a send action. Supports text, templates, and media.", "additionalProperties": false, "properties": { "text": { "type": "string", "description": "Plain text message body.", "example": "Your order has shipped!" }, "contentId": { "type": "string", "description": "Content template ID (HX... format). When provided, the template is rendered\nwith the variables map and sent to the recipient.\n", "example": "HX78e8e67abc123def456789012345678" }, "variables": { "type": "object", "description": "Variables to substitute into the content template. Keys must match placeholders defined in the template.", "additionalProperties": { "type": "string" }, "example": { "name": "Alice", "orderNumber": "12345" } }, "mediaUrls": { "type": "array", "description": "URLs of media attachments to include with the message.", "items": { "type": "string", "format": "uri" }, "example": [ "https://example.com/image.jpg" ] } }, "example": { "text": "Your order has shipped!" } }, "conversations.v2.channel_settings": { "type": "object", "description": "Channel-specific parameters forwarded as-is to the downstream sending service.\nAllows passing backend-specific fields without requiring API changes.\n", "additionalProperties": true, "example": { "messagingServiceSid": "MG1234567890abcdef1234567890abcdef", "statusCallback": "https://example.com/status" } }, "conversations.v2.configuration": { "type": "object", "description": "Configuration for Conversations.", "required": [ "id", "displayName", "description", "conversationGroupingType", "memoryStoreId" ], "properties": { "id": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration. Allows spaces and special characters, typically limited to a paragraph of text. This serves as a descriptive field rather than just a name.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.configuration_channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "A list of Conversational Intelligence configuration IDs.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was created.", "readOnly": true, "example": "2023-10-14T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was last updated.", "readOnly": true, "example": "2023-10-14T15:45:30Z" }, "version": { "type": "integer", "format": "int64", "description": "Version number used for optimistic locking.", "readOnly": true, "example": 1 } }, "example": { "id": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "displayName": "Multi Channel Config", "description": "Configuration supporting SMS, WhatsApp, and RCS channels", "conversationGroupingType": "GROUP_BY_PROFILE", "memoryStoreId": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2", "channelSettings": { "SMS": { "statusTimeouts": { "inactive": 10, "closed": 15 }, "captureRules": [ { "from": "+18005550100", "to": "*", "metadata": {} } ] }, "WHATSAPP": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "whatsapp:+18005550100", "to": "*", "metadata": {} } ] }, "RCS": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "rcs:brand_acme_agent", "to": "*", "metadata": {} } ] } }, "statusCallbacks": [ { "url": "https://webhook.example.com/conversation/status", "method": "POST" } ], "intelligenceConfigurationIds": [], "memoryExtractionEnabled": false, "conversationsV1Bridge": { "serviceId": "IS00000000000000000000000000000000" }, "createdAt": "2023-10-14T10:30:00Z", "updatedAt": "2023-10-14T15:45:30Z", "version": 1 } }, "conversations.v2.configuration_channel_settings": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/conversations.v2.channel_setting" }, "description": "Channel-specific configuration settings by channel type. Keys should be valid channel types (`VOICE`, `SMS`, `RCS`, `WHATSAPP`, `CHAT`).", "example": { "SMS": { "statusTimeouts": { "inactive": 10, "closed": 15 }, "captureRules": [ { "from": "+18005550100", "to": "+18005550101", "metadata": {} }, { "from": "+18005550103", "to": "*", "metadata": {} }, { "from": "*", "to": "+18005550103", "metadata": {} } ] }, "VOICE": { "statusTimeouts": { "inactive": 5, "closed": 30 }, "captureRules": [ { "from": "+18005550104", "to": "+18005550105", "metadata": { "callType": "PSTN" } }, { "from": "+18005550106", "to": "*", "metadata": {} }, { "from": "*", "to": "+18005550106", "metadata": {} } ] }, "WHATSAPP": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "whatsapp:+18005550100", "to": "*", "metadata": {} }, { "from": "*", "to": "whatsapp:+18005550100", "metadata": {} } ] }, "RCS": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "rcs:brand_acme_agent", "to": "*", "metadata": {} }, { "from": "*", "to": "rcs:brand_acme_agent", "metadata": {} }, { "from": "rcs:+18005550107", "to": "*", "metadata": {} } ] }, "CHAT": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "*", "to": "*", "metadata": { "chatService": "IS00000000000000000000000000000000" } } ] } } }, "conversations.v2.channel_setting": { "type": "object", "properties": { "statusTimeouts": { "$ref": "#/components/schemas/conversations.v2.status_timeouts" }, "captureRules": { "type": "array", "items": { "$ref": "#/components/schemas/conversations.v2.capture_rule" }, "description": "Array of capture rules with from/to addresses and optional metadata. Use `*` for wildcard matching in either direction." } }, "description": "Configuration settings for a specific channel type." }, "conversations.v2.status_timeouts": { "type": "object", "properties": { "inactive": { "type": "integer", "description": "Inactivity timeout in minutes.", "minimum": 1, "example": 10 }, "closed": { "type": "integer", "description": "Close timeout in minutes.", "minimum": 1, "example": 15 } }, "description": "Timeout settings for channel status transitions." }, "conversations.v2.capture_rule": { "type": "object", "properties": { "from": { "type": "string", "description": "The from address. Use `*` for wildcard to match any from address.", "example": "+18005550100" }, "to": { "type": "string", "description": "The to address. Use `*` for wildcard to match any to address.", "example": "*" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional matching criteria for the capture rule. For voice calls, can include `callType` (`PSTN`, `SIP`, and similar).", "example": { "callType": "PSTN" } } }, "required": [ "from", "to" ], "description": "Defines a capture rule with from and to addresses. Supports wildcard `*` for omnidirectional matching.", "example": { "from": "+18005550100", "to": "*", "metadata": {} } }, "conversations.v2.status_callback_config": { "type": "object", "description": "Default webhook configuration for Conversation-level events under this Configuration.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Destination URL for webhooks." }, "method": { "type": "string", "default": "POST", "enum": [ "POST", "GET" ], "description": "HTTP method used to invoke the webhook URL." } } }, "conversations.v2.patch_conversation_configuration": { "type": "object", "description": "Partial configuration update for an existing conversation. Only statusCallbacks can be modified.", "properties": { "statusCallbacks": { "type": "array", "description": "List of webhook configurations for this conversation. Send an empty array to clear all callbacks and stop webhook delivery.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } } } }, "conversations.v2.conversations_v1_bridge": { "type": "object", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.", "required": [ "serviceId" ], "properties": { "serviceId": { "type": "string", "description": "The Conversations V1 Service SID (IS prefix). One configuration per V1 Service SID.", "pattern": "^IS[0-9a-f]{32}$", "example": "IS00000000000000000000000000000000" } }, "example": { "serviceId": "IS00000000000000000000000000000000" } }, "conversations.v2.operation_status": { "type": "object", "description": "Status of a long-running operation.", "required": [ "operationId", "status", "createdAt", "statusUrl" ], "properties": { "operationId": { "type": "string", "description": "Unique identifier for the long-running operation.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "CANCELLED", "COMPLETED", "FAILED" ], "description": "Current status of the operation.", "example": "COMPLETED" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the operation was created.", "example": "2025-01-15T10:30:00Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the operation completed. Only present for completed or failed operations.", "example": "2025-01-15T10:30:05Z", "nullable": true }, "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "error": { "type": "object", "description": "Error details if the operation failed. Follows RFC 9457 Problem Details.", "nullable": true, "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type.", "example": "https://www.twilio.com/docs/errors/20001" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type.", "example": "Bad request" }, "status": { "type": "integer", "description": "The HTTP status code for this occurrence of the problem.", "example": 400 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence.", "example": "The request was invalid." }, "instance": { "type": "string", "format": "uri", "description": "A URI reference that identifies the specific occurrence of the problem." } } }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "COMPLETED", "createdAt": "2025-01-15T10:30:00Z", "completedAt": "2025-01-15T10:30:05Z", "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" }, "error": null } }, "conversations.v2.operation_accepted": { "type": "object", "description": "Slim response for an accepted long-running operation.", "additionalProperties": true, "required": [ "statusUrl" ], "properties": { "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ], "tags": [ { "name": "ConversationsV2Configuration", "description": "A conversation configuration is the top-level object in Conversation Orchestrator. It contains the settings that define how Conversation Orchestrator captures traffic and connects to other services." }, { "name": "ConversationsV2Conversation", "description": "A conversation is a record of interactions between participants. It's the container for all communications that occur during an interaction, including voice calls, SMS messages, and other supported channels." }, { "name": "ConversationsV2Participant", "description": "A participant represents an actor involved in a conversation. Conversation Orchestrator assigns each participant a type that identifies their role, such as customer, human agent, or AI agent." }, { "name": "ConversationsV2Communication", "description": "A communication is the smallest unit of interaction within a conversation. Each communication represents a single event\u2014such as an SMS message or a voice utterance." }, { "name": "ConversationsV2Action", "description": "Perform actions within a Conversation. Actions trigger side effects such as sending messages and return 202 Accepted." }, { "name": "ConversationsV2Operation", "description": "Poll the status of a long-running operation." } ], "paths": { "/v2/ControlPlane/Configurations": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "list" }, "get": { "summary": "List Configurations", "description": "Retrieve a list of Configurations.", "tags": [ "ConversationsV2Configuration" ], "parameters": [ { "name": "pageSize", "in": "query", "description": "Maximum number of items to return in a single response", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "example": 50 } }, { "name": "pageToken", "in": "query", "description": "A URL-safe, base64-encoded token representing the page of results to return", "required": false, "schema": { "type": "string", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } }, { "name": "memoryStoreId", "in": "query", "description": "Filter configurations by Memory Store ID", "required": false, "schema": { "type": "string", "pattern": "^mem_(store|service)_[0-7][0-9a-z]{25}$", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" } } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "ListConfiguration", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "configurations", "meta" ], "properties": { "configurations": { "type": "array", "minItems": 0, "items": { "type": "object", "description": "Configuration for Conversations.", "required": [ "id", "displayName", "description", "conversationGroupingType", "memoryStoreId" ], "properties": { "id": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration. Allows spaces and special characters, typically limited to a paragraph of text. This serves as a descriptive field rather than just a name.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.configuration_channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "A list of Conversational Intelligence configuration IDs.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was created.", "readOnly": true, "example": "2023-10-14T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was last updated.", "readOnly": true, "example": "2023-10-14T15:45:30Z" }, "version": { "type": "integer", "format": "int64", "description": "Version number used for optimistic locking.", "readOnly": true, "example": 1 } }, "example": { "id": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "displayName": "Multi Channel Config", "description": "Configuration supporting SMS, WhatsApp, and RCS channels", "conversationGroupingType": "GROUP_BY_PROFILE", "memoryStoreId": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2", "channelSettings": { "SMS": { "statusTimeouts": { "inactive": 10, "closed": 15 }, "captureRules": [ { "from": "+18005550100", "to": "*", "metadata": {} } ] }, "WHATSAPP": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "whatsapp:+18005550100", "to": "*", "metadata": {} } ] }, "RCS": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "rcs:brand_acme_agent", "to": "*", "metadata": {} } ] } }, "statusCallbacks": [ { "url": "https://webhook.example.com/conversation/status", "method": "POST" } ], "intelligenceConfigurationIds": [], "memoryExtractionEnabled": false, "conversationsV1Bridge": { "serviceId": "IS00000000000000000000000000000000" }, "createdAt": "2023-10-14T10:30:00Z", "updatedAt": "2023-10-14T15:45:30Z", "version": 1 } } }, "meta": { "type": "object", "required": [ "key", "pageSize" ], "properties": { "key": { "type": "string", "description": "The key of the list property contains the actual data items", "example": "configurations" }, "pageSize": { "type": "integer", "description": "The actual number of items returned in this response", "example": 20 }, "previousToken": { "type": "string", "description": "Token to fetch the previous page of results", "example": "eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0=" }, "nextToken": { "type": "string", "description": "Token to fetch the next page of results", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "summary": "Create a Configuration", "description": "Create a new Configuration", "tags": [ "ConversationsV2Configuration" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "CreateConfiguration", "requestBody": { "description": "The configuration to create", "content": { "application/json": { "schema": { "type": "object", "required": [ "displayName", "description", "conversationGroupingType", "memoryStoreId" ], "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "The strategy Conversation Orchestrator uses to assign communications to conversations.", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "The memory store ID that Conversation Orchestrator uses for profile resolution.", "example": "memora_service_123" }, "channelSettings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "statusTimeouts": { "type": "object", "properties": { "inactive": { "type": "integer", "description": "The inactivity timeout in minutes. For more information, see [Conversation lifecycle](/docs/platform/conversations/concepts/lifecycle).", "minimum": 1, "example": 10 }, "closed": { "type": "integer", "description": "The close timeout in minutes. For more information, see [Conversation lifecycle](/docs/platform/conversations/concepts/lifecycle).", "minimum": 1, "example": 15 } } }, "captureRules": { "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "The from address. Use '*' for wildcard.", "example": "+18005550100" }, "to": { "type": "string", "description": "The to address. Use '*' for wildcard.", "example": "+18005550101" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "statusCallbacks": { "type": "array", "maxItems": 2, "description": "A list of webhook configurations.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The destination URL for webhooks." }, "method": { "type": "string", "default": "POST", "enum": [ "POST", "GET", "PUT", "DELETE", "PATCH" ], "description": "The HTTP method used to invoke the webhook URL." } } } }, "intelligenceConfigurationIds": { "type": "array", "description": "A list of Conversational Intelligence configuration IDs.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false } } } } } }, "responses": { "202": { "description": "Accepted - Operation created for asynchronous processing", "headers": { "Operation-Id": { "description": "Unique identifier for the long-running operation", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested number of seconds before polling operation status", "schema": { "type": "integer", "example": 5 } }, "Location": { "description": "URI of the operation status endpoint", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Slim response for an accepted long-running operation.", "additionalProperties": true, "required": [ "statusUrl" ], "properties": { "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/ControlPlane/Configurations/{Sid}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "instance" }, "parameters": [ { "name": "Sid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Configuration SID", "normalizeSid": true } } ], "get": { "summary": "Fetch Configuration", "description": "Retrieve a Configuration.", "tags": [ "ConversationsV2Configuration" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchConfiguration", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Configuration for Conversations.", "required": [ "id", "displayName", "description", "conversationGroupingType", "memoryStoreId" ], "properties": { "id": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration. Allows spaces and special characters, typically limited to a paragraph of text. This serves as a descriptive field rather than just a name.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.configuration_channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "A list of Conversational Intelligence configuration IDs.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was created.", "readOnly": true, "example": "2023-10-14T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Configuration was last updated.", "readOnly": true, "example": "2023-10-14T15:45:30Z" }, "version": { "type": "integer", "format": "int64", "description": "Version number used for optimistic locking.", "readOnly": true, "example": 1 } }, "example": { "id": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "displayName": "Multi Channel Config", "description": "Configuration supporting SMS, WhatsApp, and RCS channels", "conversationGroupingType": "GROUP_BY_PROFILE", "memoryStoreId": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2", "channelSettings": { "SMS": { "statusTimeouts": { "inactive": 10, "closed": 15 }, "captureRules": [ { "from": "+18005550100", "to": "*", "metadata": {} } ] }, "WHATSAPP": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "whatsapp:+18005550100", "to": "*", "metadata": {} } ] }, "RCS": { "statusTimeouts": { "inactive": 15, "closed": 60 }, "captureRules": [ { "from": "rcs:brand_acme_agent", "to": "*", "metadata": {} } ] } }, "statusCallbacks": [ { "url": "https://webhook.example.com/conversation/status", "method": "POST" } ], "intelligenceConfigurationIds": [], "memoryExtractionEnabled": false, "conversationsV1Bridge": { "serviceId": "IS00000000000000000000000000000000" }, "createdAt": "2023-10-14T10:30:00Z", "updatedAt": "2023-10-14T15:45:30Z", "version": 1 } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "summary": "Update Configuration", "description": "Update an existing Configuration", "tags": [ "ConversationsV2Configuration" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "UpdateConfiguration", "requestBody": { "description": "The configuration to update", "content": { "application/json": { "schema": { "type": "object", "required": [ "conversationGroupingType", "channelSettings", "description", "memoryStoreId" ], "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the configuration.", "example": "Updated Customer Support Configuration" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "The strategy Conversation Orchestrator uses to assign communications to conversations.", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "The Memory Store ID for profile resolution.", "example": "memora_service_123" }, "channelSettings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "statusTimeouts": { "type": "object", "properties": { "inactive": { "type": "integer", "minimum": 1, "example": 10 }, "closed": { "type": "integer", "minimum": 1, "example": 15 } } }, "captureRules": { "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "example": "+18005550100" }, "to": { "type": "string", "example": "+18005550101" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "statusCallbacks": { "type": "array", "maxItems": 2, "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "default": "POST", "enum": [ "POST", "GET", "PUT", "DELETE", "PATCH" ] } } } }, "intelligenceConfigurationIds": { "type": "array", "description": "A list of Conversational Intelligence configuration IDs.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false } } } } } }, "responses": { "202": { "description": "Accepted - Operation created for asynchronous processing", "headers": { "Operation-Id": { "description": "Unique identifier for the long-running operation", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested number of seconds before polling operation status", "schema": { "type": "integer", "example": 5 } }, "Location": { "description": "URI of the operation status endpoint", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Slim response for an accepted long-running operation.", "additionalProperties": true, "required": [ "statusUrl" ], "properties": { "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "summary": "Delete Configuration", "description": "Delete a Configuration", "tags": [ "ConversationsV2Configuration" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "DeleteConfiguration", "responses": { "202": { "description": "Accepted - Operation created for asynchronous processing", "headers": { "Operation-Id": { "description": "Unique identifier for the long-running operation", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested number of seconds before polling operation status", "schema": { "type": "integer", "example": 5 } }, "Location": { "description": "URI of the operation status endpoint", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Slim response for an accepted long-running operation.", "additionalProperties": true, "required": [ "statusUrl" ], "properties": { "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "list" }, "get": { "summary": "List Conversations", "description": "Retrieve a list of Conversations.", "tags": [ "ConversationsV2Conversation" ], "parameters": [ { "name": "status", "in": "query", "description": "Filters for specific statuses", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ] } } }, { "name": "channelId", "in": "query", "description": "The resource identifier (such as callSid or messageSid) to filter conversations.", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Maximum number of items to return in a single response", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "example": 50 } }, { "name": "pageToken", "in": "query", "description": "A URL-safe, base64-encoded token representing the page of results to return", "required": false, "schema": { "type": "string", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "ListConversationByAccount", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "conversations", "meta" ], "properties": { "conversations": { "type": "array", "minItems": 0, "items": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } }, "meta": { "type": "object", "required": [ "key", "pageSize" ], "properties": { "key": { "type": "string", "description": "The key of the list property contains the actual data items", "example": "conversations" }, "pageSize": { "type": "integer", "description": "The actual number of items returned in this response", "example": 20 }, "previousToken": { "type": "string", "description": "Token to fetch the previous page of results" }, "nextToken": { "type": "string", "description": "Token to fetch the next page of results" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "summary": "Create a new Conversation", "description": "Create a new conversation", "tags": [ "ConversationsV2Conversation" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "CreateConversationWithConfig", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "configurationId" ], "properties": { "configurationId": { "type": "string", "description": "The ID of an existing configuration.", "example": "conv_configuration_01k1etx3jbfx88476ccja0889d" }, "name": { "type": "string", "description": "The name of the conversation.", "example": "Support Chat" }, "configuration": { "type": "object", "description": "Conversation configuration settings.", "properties": { "intelligenceConfigurationIds": { "type": "array", "maxItems": 5, "items": { "type": "string" }, "description": "A list of Conversational Intelligence configuration IDs." } } }, "participants": { "type": "array", "description": "Optional list of Participants to create with the Conversation.", "maxItems": 50, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the Participant." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT" ], "description": "Type of Participant in the Conversation." }, "profileId": { "type": "string", "description": "Resolved profile ID." }, "addresses": { "type": "array", "description": "List of Communication addresses for the Participant.", "items": { "type": "object", "required": [ "channel", "address" ], "properties": { "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "EMAIL", "WHATSAPP", "CHAT", "API", "SYSTEM" ] }, "address": { "type": "string" }, "channelId": { "type": "string" } } } } } } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{Sid}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "instance" }, "parameters": [ { "name": "Sid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } } ], "get": { "summary": "Fetch Conversation", "description": "Retrieve a Conversation.", "tags": [ "ConversationsV2Conversation" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchConversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "summary": "Update a Conversation", "description": "Update an existing conversation", "tags": [ "ConversationsV2Conversation" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "UpdateConversationById", "requestBody": { "description": "The conversation to update", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "name": { "type": "string", "description": "The name of the Conversation.", "example": "Support Chat" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "The state of the Conversation." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "summary": "Delete a Conversation (async)", "description": "Asynchronously delete a conversation and all associated data.\nReturns 202 Accepted with an Operation-Id for status tracking via GET /v2/ControlPlane/Operations/{operationId}.\n", "tags": [ "ConversationsV2Conversation" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "DeleteConversationAsync", "responses": { "202": { "description": "Operation accepted for asynchronous processing", "headers": { "Operation-Id": { "description": "Unique identifier for the long-running operation", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested number of seconds before polling operation status", "schema": { "type": "integer", "example": 5 } }, "Location": { "description": "URI of the operation status endpoint", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Slim response for an accepted long-running operation.", "additionalProperties": true, "required": [ "statusUrl" ], "properties": { "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "summary": "Partially Update a Conversation", "description": "Partially update the details of an existing Conversation.", "tags": [ "ConversationsV2Conversation" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "PatchConversationById", "requestBody": { "description": "The conversation fields to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the Conversation.", "example": "Support Chat" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "The state of the Conversation." }, "configuration": { "description": "Partial configuration update for an existing conversation. Only statusCallbacks can be modified.", "type": "object", "properties": { "statusCallbacks": { "type": "array", "description": "List of webhook configurations for this conversation. Send an empty array to clear all callbacks and stop webhook delivery.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "accountId", "configurationId" ], "properties": { "id": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "configurationId": { "type": "string", "description": "Configuration ID.", "example": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "CLOSED" ], "description": "Conversation status.", "example": "ACTIVE" }, "name": { "type": "string", "description": "Conversation name.", "example": "Customer Support Chat", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Conversation was last updated.", "example": "2023-07-01T12:30:00Z" }, "configuration": { "type": "object", "description": "Full configuration settings for this Conversation.", "properties": { "displayName": { "type": "string", "description": "A human-readable name for the configuration. Limited to 32 characters.", "maxLength": 32, "pattern": "^[a-zA-Z0-9-_ ]+$", "example": "My Support Config" }, "description": { "type": "string", "description": "Human-readable description for the Configuration.", "example": "Customer Support Configuration for handling all inbound customer inquiries" }, "conversationGroupingType": { "type": "string", "enum": [ "GROUP_BY_PROFILE", "GROUP_BY_PARTICIPANT_ADDRESSES", "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE" ], "description": "Type of Conversation grouping strategy:\n- `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store.\n A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel.\n- `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels.\n A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS.\n- `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel.\n A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.\n", "example": "GROUP_BY_PROFILE" }, "memoryStoreId": { "type": "string", "description": "Memory Store ID for Profile resolution.", "example": "mem_store_01k1etk2y5f1y9fpe2epfdtvv2" }, "channelSettings": { "$ref": "#/components/schemas/conversations.v2.channel_settings", "description": "Channel-specific configuration settings including timeout settings and capture rules." }, "statusCallbacks": { "type": "array", "description": "List of default webhook configurations applied to Conversations under this Configuration.", "maxItems": 20, "items": { "$ref": "#/components/schemas/conversations.v2.status_callback_config" } }, "intelligenceConfigurationIds": { "type": "array", "description": "List of Intelligence Configuration IDs configured for this Configuration.", "maxItems": 5, "items": { "type": "string" }, "example": [ "agent1", "agent2" ] }, "memoryExtractionEnabled": { "type": "boolean", "default": false, "description": "Whether memory extraction is enabled for conversations under this configuration. Defaults to false.", "example": false }, "conversationsV1Bridge": { "$ref": "#/components/schemas/conversations.v2.conversations_v1_bridge", "description": "Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications." } } }, "participants": { "type": "array", "description": "Participants in this Conversation.", "items": { "$ref": "#/components/schemas/conversations.v2.participant" } } }, "example": { "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "configurationId": "conv_configuration_01k1etk2y5f1y9fpe2epfdtvv2", "status": "ACTIVE", "name": "Customer Support - Multi-channel", "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationId}/Actions": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "list" }, "parameters": [ { "name": "ConversationId", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } } ], "post": { "summary": "Create an Action", "description": "Creates an Action within a Conversation. Currently supports SEND_MESSAGE,\nwhich sends a message to recipients via the configured channel.\n\nReturns 202 Accepted with the Action in PENDING status. Poll\n`GET /v2/Conversations/{ConversationId}/Actions/{ActionId}` to check completion.\n", "tags": [ "ConversationsV2Action" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "CreateConversationAction", "requestBody": { "description": "The action to perform.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "type": "string", "description": "Action type discriminator. Accepted values: SEND_MESSAGE.", "example": "SEND_MESSAGE" }, "payload": { "$ref": "#/components/schemas/conversations.v2.send_message_payload" } } } ], "discriminator": { "propertyName": "type" } }, "examples": { "sendMessage": { "summary": "Send a message", "value": { "type": "SEND_MESSAGE", "payload": { "from": { "address": "+18005550100", "channel": "SMS" }, "to": [ { "address": "+18005550199", "channel": "SMS" } ], "content": { "text": "Hello from the Actions API!" } } } } } } } }, "responses": { "202": { "description": "Action accepted. Returns the Action in PENDING status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "status", "conversationId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this Action.", "example": "conv_action_01k1etx3jbfx88476ccja0889e" }, "type": { "type": "string", "description": "The type of action. Accepted values: SEND_MESSAGE.", "example": "SEND_MESSAGE" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Current status of the Action.\n- PENDING: Action accepted, awaiting downstream confirmation\n- COMPLETED: Downstream backend confirmed the action\n- FAILED: Downstream backend reported a failure\n", "example": "PENDING" }, "conversationId": { "type": "string", "description": "The conversation this action belongs to.", "example": "conv_conversation_01k1etx3jbfx88476ccja0889c" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Named identifiers from downstream. For SEND_MESSAGE:\n- messageSid: The downstream message SID (present when PENDING or COMPLETED)\n- communicationId: The Communication ID (present when COMPLETED)\n", "example": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was created.", "example": "2026-03-30T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was last updated.", "example": "2026-03-30T10:30:02Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action reached a terminal status.", "example": "2026-03-30T10:30:02Z" } }, "example": { "id": "conv_action_01k1etx3jbfx88476ccja0889e", "type": "SEND_MESSAGE", "status": "COMPLETED", "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c", "related": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" }, "createdAt": "2026-03-30T10:30:00Z", "completedAt": "2026-03-30T10:30:02Z" } }, "example": { "id": "conv_action_01k1etx3jbfx88476ccja0889e", "type": "SEND_MESSAGE", "status": "PENDING", "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c", "related": { "messageSid": "SM1234567890abcdef1234567890abcdef" }, "createdAt": "2026-03-30T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationId}/Actions/{ActionId}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "parameters": [ { "name": "ConversationId", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } }, { "name": "ActionId", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Action ID", "normalizeSid": true } } ], "get": { "summary": "Get Action Status", "description": "Retrieve the current status of an Action.", "tags": [ "ConversationsV2Action" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchConversationAction", "responses": { "200": { "description": "Action status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "status", "conversationId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this Action.", "example": "conv_action_01k1etx3jbfx88476ccja0889e" }, "type": { "type": "string", "description": "The type of action. Accepted values: SEND_MESSAGE.", "example": "SEND_MESSAGE" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Current status of the Action.\n- PENDING: Action accepted, awaiting downstream confirmation\n- COMPLETED: Downstream backend confirmed the action\n- FAILED: Downstream backend reported a failure\n", "example": "PENDING" }, "conversationId": { "type": "string", "description": "The conversation this action belongs to.", "example": "conv_conversation_01k1etx3jbfx88476ccja0889c" }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Named identifiers from downstream. For SEND_MESSAGE:\n- messageSid: The downstream message SID (present when PENDING or COMPLETED)\n- communicationId: The Communication ID (present when COMPLETED)\n", "example": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was created.", "example": "2026-03-30T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was last updated.", "example": "2026-03-30T10:30:02Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action reached a terminal status.", "example": "2026-03-30T10:30:02Z" } }, "example": { "id": "conv_action_01k1etx3jbfx88476ccja0889e", "type": "SEND_MESSAGE", "status": "COMPLETED", "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c", "related": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" }, "createdAt": "2026-03-30T10:30:00Z", "completedAt": "2026-03-30T10:30:02Z" } }, "example": { "id": "conv_action_01k1etx3jbfx88476ccja0889e", "type": "SEND_MESSAGE", "status": "COMPLETED", "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c", "related": { "messageSid": "SM1234567890abcdef1234567890abcdef", "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c" }, "createdAt": "2026-03-30T10:30:00Z", "completedAt": "2026-03-30T10:30:02Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationSid}/Participants": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "list" }, "parameters": [ { "name": "ConversationSid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } } ], "get": { "summary": "List Participants", "description": "Retrieve a list of Participants in a Conversation.", "tags": [ "ConversationsV2Participant" ], "parameters": [ { "name": "pageSize", "in": "query", "description": "Maximum number of items to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "example": 50 } }, { "name": "pageToken", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": "string" } } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "ListParticipantByConversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "participants", "meta" ], "properties": { "participants": { "type": "array", "items": { "type": "object", "required": [ "id", "conversationId", "accountId", "name" ], "properties": { "id": { "type": "string", "description": "Participant ID.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "name": { "type": "string", "description": "Participant display name.", "example": "Dana S." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ], "description": "Type of Participant in the Conversation.", "example": "CUSTOMER" }, "profileId": { "type": "string", "description": "Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.", "example": "mem_profile_00000000000000000000000000" }, "addresses": { "type": "array", "description": "Communication addresses for this Participant. Address format varies by channel:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- EMAIL: Email address (such as \"user@example.com\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n", "items": { "$ref": "#/components/schemas/conversations.v2.address" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was last updated.", "example": "2023-07-01T12:00:00Z" } }, "example": { "id": "conv_participant_01k1etx3jbfx88476ccja0889c", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Dana", "type": "CUSTOMER", "profileId": "mem_profile_00000000000000000000000000", "addresses": [ { "channel": "SMS", "address": "+18005550100" }, { "channel": "WHATSAPP", "address": "whatsapp:+18005550100" }, { "channel": "RCS", "address": "rcs:+18005550100" } ], "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } }, "meta": { "type": "object", "properties": { "key": { "type": "string", "example": "participants" }, "pageSize": { "type": "integer" }, "previousToken": { "type": "string" }, "nextToken": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "summary": "Create Participant", "description": "Create a Participant.", "tags": [ "ConversationsV2Participant" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "CreateParticipantInConversation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "addresses" ], "properties": { "name": { "type": "string", "example": "Dana" }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ] }, "profileId": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "required": [ "channel", "address" ], "properties": { "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ] }, "address": { "type": "string" }, "channelId": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "conversationId", "accountId", "name" ], "properties": { "id": { "type": "string", "description": "Participant ID.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "name": { "type": "string", "description": "Participant display name.", "example": "Dana S." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ], "description": "Type of Participant in the Conversation.", "example": "CUSTOMER" }, "profileId": { "type": "string", "description": "Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.", "example": "mem_profile_00000000000000000000000000" }, "addresses": { "type": "array", "description": "Communication addresses for this Participant. Address format varies by channel:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- EMAIL: Email address (such as \"user@example.com\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n", "items": { "$ref": "#/components/schemas/conversations.v2.address" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was last updated.", "example": "2023-07-01T12:00:00Z" } }, "example": { "id": "conv_participant_01k1etx3jbfx88476ccja0889c", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Dana", "type": "CUSTOMER", "profileId": "mem_profile_00000000000000000000000000", "addresses": [ { "channel": "SMS", "address": "+18005550100" }, { "channel": "WHATSAPP", "address": "whatsapp:+18005550100" }, { "channel": "RCS", "address": "rcs:+18005550100" } ], "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationSid}/Participants/{Sid}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "instance" }, "parameters": [ { "name": "ConversationSid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } }, { "name": "Sid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Participant SID", "normalizeSid": true } } ], "get": { "summary": "Fetch Participant", "description": "Retrieve a Participant.", "tags": [ "ConversationsV2Participant" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchParticipant", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "conversationId", "accountId", "name" ], "properties": { "id": { "type": "string", "description": "Participant ID.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "name": { "type": "string", "description": "Participant display name.", "example": "Dana S." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ], "description": "Type of Participant in the Conversation.", "example": "CUSTOMER" }, "profileId": { "type": "string", "description": "Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.", "example": "mem_profile_00000000000000000000000000" }, "addresses": { "type": "array", "description": "Communication addresses for this Participant. Address format varies by channel:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- EMAIL: Email address (such as \"user@example.com\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n", "items": { "$ref": "#/components/schemas/conversations.v2.address" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was last updated.", "example": "2023-07-01T12:00:00Z" } }, "example": { "id": "conv_participant_01k1etx3jbfx88476ccja0889c", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Dana", "type": "CUSTOMER", "profileId": "mem_profile_00000000000000000000000000", "addresses": [ { "channel": "SMS", "address": "+18005550100" }, { "channel": "WHATSAPP", "address": "whatsapp:+18005550100" }, { "channel": "RCS", "address": "rcs:+18005550100" } ], "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "summary": "Update a Participant", "description": "Update an existing Participant", "tags": [ "ConversationsV2Participant" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "UpdateParticipantInConversation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Dana" }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ] }, "profileId": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "required": [ "channel", "address" ], "properties": { "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ] }, "address": { "type": "string" }, "channelId": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "conversationId", "accountId", "name" ], "properties": { "id": { "type": "string", "description": "Participant ID.", "example": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "name": { "type": "string", "description": "Participant display name.", "example": "Dana S." }, "type": { "type": "string", "enum": [ "HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT", "UNKNOWN" ], "description": "Type of Participant in the Conversation.", "example": "CUSTOMER" }, "profileId": { "type": "string", "description": "Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.", "example": "mem_profile_00000000000000000000000000" }, "addresses": { "type": "array", "description": "Communication addresses for this Participant. Address format varies by channel:\n- SMS/VOICE: E.164 phone number (such as \"+18005550100\")\n- EMAIL: Email address (such as \"user@example.com\")\n- WHATSAPP: Phone number with whatsapp prefix (such as \"whatsapp:+18005550100\")\n- RCS: Sender ID or phone number with rcs prefix (such as \"rcs:brand_acme_agent\" or \"rcs:+18005550100\")\n", "items": { "$ref": "#/components/schemas/conversations.v2.address" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was created.", "example": "2023-07-01T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Participant was last updated.", "example": "2023-07-01T12:00:00Z" } }, "example": { "id": "conv_participant_01k1etx3jbfx88476ccja0889c", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Dana", "type": "CUSTOMER", "profileId": "mem_profile_00000000000000000000000000", "addresses": [ { "channel": "SMS", "address": "+18005550100" }, { "channel": "WHATSAPP", "address": "whatsapp:+18005550100" }, { "channel": "RCS", "address": "rcs:+18005550100" } ], "createdAt": "2023-07-01T12:00:00Z", "updatedAt": "2023-07-01T12:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationSid}/Communications": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "list" }, "parameters": [ { "name": "ConversationSid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation ID", "normalizeSid": true } } ], "get": { "summary": "List Communications", "description": "Retrieve a list of Communications in a Conversation.", "tags": [ "ConversationsV2Communication" ], "parameters": [ { "name": "channelId", "in": "query", "description": "Resource identifier to filter communications", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Maximum number of items to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "example": 50 } }, { "name": "pageToken", "in": "query", "description": "Page token for pagination", "required": false, "schema": { "type": "string" } } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "ListCommunicationByConversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "communications", "meta" ], "properties": { "communications": { "type": "array", "items": { "type": "object", "required": [ "id", "conversationId", "accountId", "author", "content", "recipients" ], "properties": { "id": { "type": "string", "description": "Communication ID.", "example": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "author": { "$ref": "#/components/schemas/conversations.v2.participant_address" }, "content": { "description": "The content of the Communication using type field for discrimination.", "oneOf": [ { "$ref": "#/components/schemas/conversations.v2.content_text" }, { "$ref": "#/components/schemas/conversations.v2.content_transcription" } ] }, "channelId": { "type": "string", "description": "Channel-specific reference ID.", "example": "CA123456789" }, "resourceId": { "type": "string", "minLength": 1, "description": "External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.", "example": "SM12345678901234567890123456789012" }, "recipients": { "type": "array", "description": "Communication recipients.", "items": { "allOf": [ { "$ref": "#/components/schemas/conversations.v2.participant_address" }, { "type": "object", "properties": { "deliveryStatus": { "type": "string", "description": "Delivery status of the Communication to this recipient.", "enum": [ "INITIATED", "IN_PROGRESS", "DELIVERED", "COMPLETED", "FAILED" ] } } } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was created.", "example": "2023-07-01T12:15:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was last updated.", "example": "2023-07-01T12:15:00Z" }, "occurredAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the communication occurred.", "example": "2023-07-01T12:15:00Z" } }, "example": { "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "author": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "content": { "type": "TEXT", "text": "Hello, I need help with my order" }, "resourceId": "SM12345678901234567890123456789012", "recipients": [ { "address": "+18005550102", "channel": "SMS", "participantId": "conv_participant_02m2fuy4lcgy99587ddkb1990d", "deliveryStatus": "DELIVERED" } ], "createdAt": "2023-07-01T12:15:00Z", "updatedAt": "2023-07-01T12:15:05Z" } } }, "meta": { "type": "object", "properties": { "key": { "type": "string", "example": "communications" }, "pageSize": { "type": "integer" }, "previousToken": { "type": "string" }, "nextToken": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "summary": "Create Communication", "description": "Create a Communication.", "tags": [ "ConversationsV2Communication" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "CreateCommunicationInConversation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "author", "content", "recipients" ], "properties": { "author": { "type": "object", "required": [ "address", "channel" ], "properties": { "address": { "type": "string" }, "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ] }, "participantId": { "type": "string" } } }, "content": { "description": "The content of the Communication.", "oneOf": [ { "type": "object", "title": "ContentText", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "text": { "type": "string" } } }, { "type": "object", "title": "ContentTranscription", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TRANSCRIPTION" ] }, "text": { "type": "string" }, "transcription": { "type": "object", "properties": { "channel": { "type": "integer" }, "confidence": { "type": "number" }, "engine": { "type": "string" } } } } } ] }, "channelId": { "type": "string" }, "recipients": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "address", "channel" ], "properties": { "address": { "type": "string" }, "channel": { "type": "string", "enum": [ "VOICE", "SMS", "RCS", "WHATSAPP", "CHAT" ] }, "participantId": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "conversationId", "accountId", "author", "content", "recipients" ], "properties": { "id": { "type": "string", "description": "Communication ID.", "example": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "author": { "$ref": "#/components/schemas/conversations.v2.participant_address" }, "content": { "description": "The content of the Communication using type field for discrimination.", "oneOf": [ { "$ref": "#/components/schemas/conversations.v2.content_text" }, { "$ref": "#/components/schemas/conversations.v2.content_transcription" } ] }, "channelId": { "type": "string", "description": "Channel-specific reference ID.", "example": "CA123456789" }, "resourceId": { "type": "string", "minLength": 1, "description": "External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.", "example": "SM12345678901234567890123456789012" }, "recipients": { "type": "array", "description": "Communication recipients.", "items": { "allOf": [ { "$ref": "#/components/schemas/conversations.v2.participant_address" }, { "type": "object", "properties": { "deliveryStatus": { "type": "string", "description": "Delivery status of the Communication to this recipient.", "enum": [ "INITIATED", "IN_PROGRESS", "DELIVERED", "COMPLETED", "FAILED" ] } } } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was created.", "example": "2023-07-01T12:15:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was last updated.", "example": "2023-07-01T12:15:00Z" }, "occurredAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the communication occurred.", "example": "2023-07-01T12:15:00Z" } }, "example": { "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "author": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "content": { "type": "TEXT", "text": "Hello, I need help with my order" }, "resourceId": "SM12345678901234567890123456789012", "recipients": [ { "address": "+18005550102", "channel": "SMS", "participantId": "conv_participant_02m2fuy4lcgy99587ddkb1990d", "deliveryStatus": "DELIVERED" } ], "createdAt": "2023-07-01T12:15:00Z", "updatedAt": "2023-07-01T12:15:05Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/Conversations/{ConversationSid}/Communications/{Sid}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "instance" }, "parameters": [ { "name": "ConversationSid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Conversation SID", "normalizeSid": true } }, { "name": "Sid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Communication SID", "normalizeSid": true } } ], "get": { "summary": "Fetch Communication", "description": "Retrieve a Communication.", "tags": [ "ConversationsV2Communication" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchCommunication", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "conversationId", "accountId", "author", "content", "recipients" ], "properties": { "id": { "type": "string", "description": "Communication ID.", "example": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2" }, "conversationId": { "type": "string", "description": "Conversation ID.", "example": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2" }, "accountId": { "type": "string", "description": "Account ID.", "example": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "author": { "$ref": "#/components/schemas/conversations.v2.participant_address" }, "content": { "description": "The content of the Communication using type field for discrimination.", "oneOf": [ { "$ref": "#/components/schemas/conversations.v2.content_text" }, { "$ref": "#/components/schemas/conversations.v2.content_transcription" } ] }, "channelId": { "type": "string", "description": "Channel-specific reference ID.", "example": "CA123456789" }, "resourceId": { "type": "string", "minLength": 1, "description": "External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.", "example": "SM12345678901234567890123456789012" }, "recipients": { "type": "array", "description": "Communication recipients.", "items": { "allOf": [ { "$ref": "#/components/schemas/conversations.v2.participant_address" }, { "type": "object", "properties": { "deliveryStatus": { "type": "string", "description": "Delivery status of the Communication to this recipient.", "enum": [ "INITIATED", "IN_PROGRESS", "DELIVERED", "COMPLETED", "FAILED" ] } } } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was created.", "example": "2023-07-01T12:15:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when this Communication was last updated.", "example": "2023-07-01T12:15:00Z" }, "occurredAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the communication occurred.", "example": "2023-07-01T12:15:00Z" } }, "example": { "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2", "conversationId": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2", "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "author": { "address": "+18005550100", "channel": "SMS", "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c" }, "content": { "type": "TEXT", "text": "Hello, I need help with my order" }, "resourceId": "SM12345678901234567890123456789012", "recipients": [ { "address": "+18005550102", "channel": "SMS", "participantId": "conv_participant_02m2fuy4lcgy99587ddkb1990d", "deliveryStatus": "DELIVERED" } ], "createdAt": "2023-07-01T12:15:00Z", "updatedAt": "2023-07-01T12:15:05Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v2/ControlPlane/Operations/{Sid}": { "servers": [ { "url": "https://conversations.twilio.com" } ], "x-twilio": { "pathType": "instance" }, "parameters": [ { "name": "Sid", "in": "path", "required": true, "schema": { "type": "string" }, "x-twilio": { "shortDescription": "Operation ID", "normalizeSid": true } } ], "get": { "summary": "Get Operation Status", "description": "Retrieve the current status of a long-running operation.\nOperations progress through: PENDING -> RUNNING -> COMPLETED or FAILED.\n", "tags": [ "ConversationsV2Operation" ], "security": [ { "basic_apikey_or_accountsid": [] } ], "operationId": "FetchOperationStatus", "responses": { "200": { "description": "Operation status", "content": { "application/json": { "schema": { "type": "object", "description": "Status of a long-running operation.", "required": [ "operationId", "status", "createdAt", "statusUrl" ], "properties": { "operationId": { "type": "string", "description": "Unique identifier for the long-running operation.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "CANCELLED", "COMPLETED", "FAILED" ], "description": "Current status of the operation.", "example": "COMPLETED" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the operation was created.", "example": "2025-01-15T10:30:00Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the operation completed. Only present for completed or failed operations.", "example": "2025-01-15T10:30:05Z", "nullable": true }, "statusUrl": { "type": "string", "format": "uri", "description": "URL to poll for operation status.", "example": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "error": { "type": "object", "description": "Error details if the operation failed. Follows RFC 9457 Problem Details.", "nullable": true, "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type.", "example": "https://www.twilio.com/docs/errors/20001" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type.", "example": "Bad request" }, "status": { "type": "integer", "description": "The HTTP status code for this occurrence of the problem.", "example": 400 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence.", "example": "The request was invalid." }, "instance": { "type": "string", "format": "uri", "description": "A URI reference that identifies the specific occurrence of the problem." } } }, "related": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "Named resource identifiers associated with this operation. Keys depend on the operation type:\n- config-create, config-update, config-delete: configurationId\n- conversation-delete: conversationId\n", "example": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" } } }, "example": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "COMPLETED", "createdAt": "2025-01-15T10:30:00Z", "completedAt": "2025-01-15T10:30:05Z", "statusUrl": "https://conversations.twilio.com/v2/ControlPlane/Operations/proc_job_01h9d8r0vte3hz8tykdj329t7r", "related": { "configurationId": "cfg_configuration_01h9d8r0vte3hz8tykdj329t7r" }, "error": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } } }