Skip to content

Models

tac.models

Shared models for the Twilio Agent Connect.

ActionChannelSettings pydantic-model

Bases: BaseModel

Channel-specific settings forwarded to the downstream backend.

Open pass-through: any field not explicitly modeled here (e.g. messagingServiceSid, statusCallback, Attributes) can be set by callers and will be forwarded as-is.

Config:

  • default: {'populate_by_name': True, 'extra': 'allow'}

Fields:

channel_id pydantic-field 

channel_id: str | None = None

Backend-specific channel identifier (e.g. V1 Chat channel SID)

ActionParticipantRef pydantic-model

Bases: BaseModel

Participant reference for the Actions API (from/to entries).

Either participant_id or address must be supplied; channel is always required. When both are provided, Conversation Orchestrator uses participant_id and channel disambiguates which of the participant's addresses to use.

Config:

  • default: {'populate_by_name': True}

Fields:

Validators:

  • _require_participant_id_or_address

participant_id pydantic-field 

participant_id: str | None = None

Participant ID

address pydantic-field 

address: str | None = None

Participant address

channel pydantic-field 

channel: Literal[
    "VOICE",
    "SMS",
    "RCS",
    "EMAIL",
    "WHATSAPP",
    "CHAT",
    "API",
    "SYSTEM",
]

Channel type

ActionResponse pydantic-model

Bases: BaseModel

Response from POST /v2/Conversations/{id}/Actions (202 Accepted).

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Action ID

type pydantic-field 

type: str

Action type. Known values: SEND_MESSAGE. Kept as str to tolerate future additions.

status pydantic-field 

status: str

Current action status. Known values: PENDING, COMPLETED, FAILED. Kept as str to tolerate future additions.

conversation_id pydantic-field 

conversation_id: str

Conversation ID

created_at pydantic-field 

created_at: str | None = None

Action creation timestamp

ActionTextContent pydantic-model

Bases: BaseModel

Plain-text content for a SEND_MESSAGE action.

Config:

  • default: {'populate_by_name': True}

Fields:

text pydantic-field 

text: str

Message text content

Communication pydantic-model

Bases: BaseModel

A communication representing a message exchanged in a conversation.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Unique communication identifier

conversation_id pydantic-field 

conversation_id: str

Conversation ID

account_id pydantic-field 

account_id: str

Account ID

author pydantic-field 

author: CommunicationParticipant

Author of the communication

content pydantic-field 

content: CommunicationContent

The content of the Communication using type field for discrimination

recipients pydantic-field 

recipients: list[CommunicationParticipant]

Communication recipients

channel_id pydantic-field 

channel_id: str | None = None

Channel-specific reference ID

created_at pydantic-field 

created_at: str | None = None

Timestamp when this Communication was created

updated_at pydantic-field 

updated_at: str | None = None

Timestamp when this Communication was last updated

CommunicationContent pydantic-model

Bases: BaseModel

Content of a communication (ContentText or ContentTranscription).

Config:

  • default: {'populate_by_name': True}

Fields:

type pydantic-field 

type: Literal['TEXT', 'TRANSCRIPTION']

Content type discriminator

text pydantic-field 

text: str

Message text content

transcription pydantic-field 

transcription: Transcription | None = None

Transcription metadata (only present when type=TRANSCRIPTION)

CommunicationParticipant pydantic-model

Bases: BaseModel

Author or recipient in a communication.

Config:

  • default: {'populate_by_name': True}

Fields:

  • address (str)
  • channel (Literal['VOICE', 'SMS', 'RCS', 'EMAIL', 'WHATSAPP', 'CHAT', 'API', 'SYSTEM'])
  • participant_id (str)
  • delivery_status (Literal['INITIATED', 'IN_PROGRESS', 'DELIVERED', 'COMPLETED', 'FAILED'] | None)

address pydantic-field 

address: str

Address of the participant formatted according to channel type

channel pydantic-field 

channel: Literal[
    "VOICE",
    "SMS",
    "RCS",
    "EMAIL",
    "WHATSAPP",
    "CHAT",
    "API",
    "SYSTEM",
]

Channel type for the participant address

participant_id pydantic-field 

participant_id: str

Participant ID associated with this address

delivery_status pydantic-field 

delivery_status: (
    Literal[
        "INITIATED",
        "IN_PROGRESS",
        "DELIVERED",
        "COMPLETED",
        "FAILED",
    ]
    | None
) = None

Delivery status of the Communication to this recipient (recipients only)

CommunicationRequest pydantic-model

Bases: BaseModel

Request payload for adding a communication.

Config:

  • default: {'populate_by_name': True}

Fields:

author pydantic-field 

author: CommunicationParticipant

Author of the communication

content pydantic-field 

content: CommunicationContent

Content of the communication

recipients pydantic-field 

recipients: list[CommunicationParticipant]

List of recipients for the communication

channel_id pydantic-field 

channel_id: str | None = None

Store Call ID/Record ID/etc. for channel reference

ConversationRequest pydantic-model

Bases: BaseModel

Request payload for creating a conversation.

Config:

  • default: {'populate_by_name': True}

Fields:

configuration_id pydantic-field 

configuration_id: str

Configuration ID settings to use for this conversation

name pydantic-field 

name: str | None = None

Conversation name

participants pydantic-field 

participants: list[ParticipantRequest] | None = None

Optional inline participants created atomically with the conversation

ConversationResponse pydantic-model

Bases: BaseModel

Response from creating a conversation.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Conversation ID

account_id pydantic-field 

account_id: str

Twilio Account SID

status pydantic-field 

status: Literal["ACTIVE", "INACTIVE", "CLOSED"] | None = (
    None
)

Conversation status

name pydantic-field 

name: str | None = None

Conversation name

configuration_id pydantic-field 

configuration_id: str | None = None

Configuration used to create this conversation

created_at pydantic-field 

created_at: str | None = None

Creation timestamp

updated_at pydantic-field 

updated_at: str | None = None

Last update timestamp

ParticipantAddress pydantic-model

Bases: BaseModel

Communication address for a conversation participant.

Config:

  • default: {'populate_by_name': True}

Fields:

  • channel (Literal['VOICE', 'SMS', 'RCS', 'EMAIL', 'WHATSAPP', 'CHAT', 'API', 'SYSTEM'])
  • address (str)
  • channel_id (str | None)

channel pydantic-field 

channel: Literal[
    "VOICE",
    "SMS",
    "RCS",
    "EMAIL",
    "WHATSAPP",
    "CHAT",
    "API",
    "SYSTEM",
]

The channel for Communication (VOICE, SMS, EMAIL, etc.)

address pydantic-field 

address: str

The address value (phone number, email, etc.)

channel_id pydantic-field 

channel_id: str | None = None

Channel-specific ID for correlating Communications

ParticipantRequest pydantic-model

Bases: BaseModel

Request payload for creating a conversation participant.

Config:

  • default: {'populate_by_name': True}

Fields:

name pydantic-field 

name: str | None = None

Display name for the Participant

type pydantic-field 

type: (
    Literal[
        "HUMAN_AGENT",
        "CUSTOMER",
        "AI_AGENT",
        "AGENT",
        "UNKNOWN",
    ]
    | None
) = None

Type of Participant in the Conversation

profile_id pydantic-field 

profile_id: str | None = None

Resolved segment profile

addresses pydantic-field 

addresses: list[ParticipantAddress] | None

List of Communication addresses for the Participant

ParticipantResponse pydantic-model

Bases: BaseModel

Response from creating a participant.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Participant ID

conversation_id pydantic-field 

conversation_id: str

Conversation ID

account_id pydantic-field 

account_id: str

Account ID

name pydantic-field 

name: str

Participant display name

type pydantic-field 

type: (
    Literal[
        "HUMAN_AGENT",
        "CUSTOMER",
        "AI_AGENT",
        "AGENT",
        "UNKNOWN",
    ]
    | None
) = None

Type of Participant in the Conversation

profile_id pydantic-field 

profile_id: str | None = None

Segment profile ID

addresses pydantic-field 

addresses: list[ParticipantAddress]

Communication addresses for this Participant

created_at pydantic-field 

created_at: str | None = None

Timestamp when this Participant was created

updated_at pydantic-field 

updated_at: str | None = None

Timestamp when this Participant was last updated

SendMessageActionPayload pydantic-model

Bases: BaseModel

Inner payload for a SEND_MESSAGE action.

Config:

  • default: {'populate_by_name': True}

Fields:

from_ pydantic-field 

from_: ActionParticipantRef

Sender

to pydantic-field 

to: list[ActionParticipantRef]

Recipients (minimum 1)

content pydantic-field 

content: ActionTextContent

Message content

channel_settings pydantic-field 

channel_settings: ActionChannelSettings | None = None

Channel-specific pass-through settings

SendMessageActionRequest pydantic-model

Bases: BaseModel

Request for POST /v2/Conversations/{id}/Actions with type=SEND_MESSAGE.

Body is discriminated by type with the action-specific fields under payload.

Config:

  • default: {'populate_by_name': True}

Fields:

type pydantic-field 

type: Literal['SEND_MESSAGE'] = 'SEND_MESSAGE'

Action type

payload pydantic-field 

payload: SendMessageActionPayload

SEND_MESSAGE payload

HandoffPayload pydantic-model

Bases: BaseModel

Structured payload generated during a handoff.

Contains conversation context and developer-defined attributes for routing to the target system (e.g., Flex TaskRouter).

Config:

  • populate_by_name: True

Fields:

  • conversation_id (str)
  • memory_store_id (str)
  • profile_id (str)
  • attributes (dict[str, Any])

CommunicationsRange pydantic-model

Bases: BaseModel

Range of communications used in the operator execution.

Config:

  • default: {'populate_by_name': True}

Fields:

first pydantic-field 

first: str | None = None

Starting Communication ID TTID of Operator Execution

last pydantic-field 

last: str | None = None

Ending Communication ID TTID of Operator Execution

ExecutionDetails pydantic-model

Bases: BaseModel

Execution context details for the operator result.

Config:

  • default: {'populate_by_name': True}

Fields:

trigger pydantic-field 

trigger: TriggerDetails | None = None

Trigger details

communications pydantic-field 

communications: CommunicationsRange | None = None

Range of communications used

channels pydantic-field 

channels: list[str] | None = None

List of unique channels in a conversation (e.g., Voice, SMS, Email)

participants pydantic-field 

participants: list[Participant] | None = None

Participants involved in the conversation

context pydantic-field 

context: dict[str, str] | None = None

Additional execution context key/value pairs

IntelligenceConfiguration pydantic-model

Bases: BaseModel

Intelligence configuration details from the CI service.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Unique Identifier for IntelligenceConfiguration (TTID)

friendly_name pydantic-field 

friendly_name: str | None = None

Unique name of the intelligence configuration

version pydantic-field 

version: int

Version of the IntelligenceConfiguration used

rule_id pydantic-field 

rule_id: str | None = None

Id of the associated rule

Operator pydantic-model

Bases: BaseModel

Operator details from the CI service.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str | None = None

Operator Sid (Sid) or TTID

friendly_name pydantic-field 

friendly_name: str | None = None

Operator Friendly Name

version pydantic-field 

version: int | None = None

Version of the Operator used

parameters pydantic-field 

parameters: dict[str, str] | None = None

Snapshot of the parameters passed to the Operator as key/value pairs

OperatorResultEvent pydantic-model

Bases: BaseModel

Operator result event from Conversation Intelligence webhook.

This model represents the webhook payload received from the CI service. It contains metadata about the conversation and an array of operator results.

Config:

  • default: {'populate_by_name': True}

Fields:

account_id pydantic-field 

account_id: str

Twilio Account SID (Sid)

conversation_id pydantic-field 

conversation_id: str

Conversation ID (TTID) associated with the execution

memory_store_id pydantic-field 

memory_store_id: str | None = None

Memory store id

intelligence_configuration pydantic-field 

intelligence_configuration: IntelligenceConfiguration

Intelligence configuration details

operator_results pydantic-field 

operator_results: list[OperatorResult]

List of operator results from this event

Participant pydantic-model

Bases: BaseModel

Participant in a conversation.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Participant ID TTID

profile_id pydantic-field 

profile_id: str | None = None

Conversation Memory profile id of the participant

type pydantic-field 

type: str | None = None

Type of participant (e.g., HUMAN_AGENT, CUSTOMER, AI_AGENT)

TriggerDetails pydantic-model

Bases: BaseModel

Trigger details for the operator execution.

Config:

  • default: {'populate_by_name': True}

Fields:

on pydantic-field 

on: str | None = None

Trigger type (e.g., utterance, conversation_closed)

timestamp pydantic-field 

timestamp: str | None = None

Trigger timestamp (ISO-8601)

Knowledge pydantic-model

Bases: BaseModel

Represents a Twilio Knowledge resource.

Fields:

  • id (str)
  • name (str)
  • description (str)
  • type (Literal['Web', 'File', 'Text', 'DB'])

KnowledgeBase pydantic-model

Bases: BaseModel

Represents a Twilio Knowledge Base resource.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

The unique identifier for the Knowledge Base

display_name pydantic-field 

display_name: str

Human-readable name for the Knowledge Base

description pydantic-field 

description: str

Description of the Knowledge Base

status pydantic-field 

status: Literal[
    "QUEUED", "PROVISIONING", "ACTIVE", "FAILED", "DELETING"
]

The provisioning status of the Knowledge Base

created_at pydantic-field 

created_at: str

Creation timestamp in ISO 8601 format

updated_at pydantic-field 

updated_at: str

Last updated timestamp in ISO 8601 format

version pydantic-field 

version: int

Version number of the Knowledge Base

KnowledgeChunkResult pydantic-model

Bases: BaseModel

Represents a search result chunk from knowledge base search.

Config:

  • default: {'populate_by_name': True}

Fields:

content pydantic-field 

content: str

The chunk content

knowledge_id pydantic-field 

knowledge_id: str

The knowledge source ID

created_at pydantic-field 

created_at: str

Creation timestamp in ISO 8601 format

score pydantic-field 

score: float | None = None

Relevance score for the search result

MemoryCommunication pydantic-model

Bases: BaseModel

A communication from Memory API (historical conversation data).

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Unique communication identifier

author pydantic-field 

author: MemoryParticipant

Author of the communication

content pydantic-field 

content: MemoryCommunicationContent

Content of the communication

recipients pydantic-field 

recipients: list[MemoryParticipant]

Communication recipients

channel_id pydantic-field 

channel_id: str | None = None

Channel-specific ID (optional)

created_at pydantic-field 

created_at: str

When communication was created

updated_at pydantic-field 

updated_at: str | None = None

When communication was last updated

MemoryCommunicationContent pydantic-model

Bases: BaseModel

Content of a Memory communication.

Config:

  • default: {'populate_by_name': True}

Fields:

text pydantic-field 

text: str | None = None

Primary text content (optional)

MemoryParticipant pydantic-model

Bases: BaseModel

Participant in a Memory communication (author or recipient).

Config:

  • default: {'populate_by_name': True}

Fields:

  • id (str)
  • name (str)
  • address (str)
  • channel (Literal['VOICE', 'SMS', 'RCS', 'EMAIL', 'WHATSAPP', 'CHAT', 'API', 'SYSTEM'])
  • type (Literal['HUMAN_AGENT', 'CUSTOMER', 'AI_AGENT', 'AGENT', 'UNKNOWN'] | None)
  • profile_id (str | None)
  • delivery_status (Literal['INITIATED', 'IN_PROGRESS', 'DELIVERED', 'COMPLETED', 'FAILED'] | None)

id pydantic-field 

id: str

Participant identifier

name pydantic-field 

name: str

Participant display name

address pydantic-field 

address: str

Address of the Participant (e.g., phone number, email address)

channel pydantic-field 

channel: Literal[
    "VOICE",
    "SMS",
    "RCS",
    "EMAIL",
    "WHATSAPP",
    "CHAT",
    "API",
    "SYSTEM",
]

The channel on which the message originated

type pydantic-field 

type: (
    Literal[
        "HUMAN_AGENT",
        "CUSTOMER",
        "AI_AGENT",
        "AGENT",
        "UNKNOWN",
    ]
    | None
) = None

Type of Participant in the Conversation

profile_id pydantic-field 

profile_id: str | None = None

The canonical profile ID

delivery_status pydantic-field 

delivery_status: (
    Literal[
        "INITIATED",
        "IN_PROGRESS",
        "DELIVERED",
        "COMPLETED",
        "FAILED",
    ]
    | None
) = None

Delivery status of the Communication to this recipient (only for recipients)

MemoryRetrievalRequest pydantic-model

Bases: BaseModel

Request payload for retrieving conversation memories.

Config:

  • default: {'populate_by_name': True}

Fields:

conversation_id pydantic-field 

conversation_id: str | None = None

A unique identifier for the conversation using Twilio Type ID (TTID) format

query pydantic-field 

query: str | None = None

Semantic search query for finding relevant memories

begin_date pydantic-field 

begin_date: str | None = None

Start date for filtering memories (inclusive)

end_date pydantic-field 

end_date: str | None = None

End date for filtering memories (exclusive)

observations_limit pydantic-field 

observations_limit: int | None = 20

Max observations to return (0-100). Set to 0 to disable.

summaries_limit pydantic-field 

summaries_limit: int | None = 5

Max summaries to return (0-100). Set to 0 to disable.

communications_limit pydantic-field 

communications_limit: int | None = 0

Max communications to return (0-100). Set to 0 to disable.

relevance_threshold pydantic-field 

relevance_threshold: float | None = 0.0

Min relevance score (0.0-1.0). Only applies when results are ranked by relevance.

MemoryRetrievalResponse pydantic-model

Bases: BaseModel

Response from the Memory API /Recall endpoint.

Config:

  • default: {'populate_by_name': True}

Fields:

observations pydantic-field 

observations: list[ObservationInfo]

Array of observation memories

summaries pydantic-field 

summaries: list[SummaryInfo]

Array of summary memories from end of conversations

communications pydantic-field 

communications: list[MemoryCommunication]

Array of communication memories from Memory API

meta pydantic-field 

meta: MemoryRetrievalMeta

Metadata about the retrieval operation

ObservationInfo pydantic-model

Bases: BaseModel

An observation memory from the API response.

Config:

  • default: {'populate_by_name': True}

Fields:

content pydantic-field 

content: str

The main content of the observation

source pydantic-field 

source: str

Source system that generated this observation

id pydantic-field 

id: str

Unique identifier for the observation using Twilio Type ID (TTID) format

created_at pydantic-field 

created_at: str

Timestamp when the observation was created

updated_at pydantic-field 

updated_at: str

Timestamp when the observation was last updated

occurred_at pydantic-field 

occurred_at: str | None = None

Timestamp when the observation originally occurred

conversation_ids pydantic-field 

conversation_ids: list[str] | None = None

Array of conversation IDs associated with this observation

ProfileResponse pydantic-model

Bases: BaseModel

Response from the profile retrieval API.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Unique identifier for the profile

created_at pydantic-field 

created_at: str

Timestamp when the profile was created

traits pydantic-field 

traits: dict[str, Any]

Profile traits organized by trait groups

SummaryInfo pydantic-model

Bases: BaseModel

A summary memory derived from observations at the end of conversations.

Config:

  • default: {'populate_by_name': True}

Fields:

content pydantic-field 

content: str

The main content of the summary

conversation_id pydantic-field 

conversation_id: str | None = None

Unique identifier for the conversation using Twilio Type ID (TTID) format

id pydantic-field 

id: str

Unique identifier for the summary using Twilio Type ID (TTID) format

created_at pydantic-field 

created_at: str

Timestamp when the summary was created

updated_at pydantic-field 

updated_at: str

Timestamp when the summary was last updated

source pydantic-field 

source: str | None = None

Source system that generated the summary

occurred_at pydantic-field 

occurred_at: str | None = None

Timestamp when the summary was originally created

CallOptions pydantic-model

Bases: BaseModel

Parameters for Twilio's client.calls.create().

Typed below are the ones outbound ConversationRelay reaches for; any other param calls.create() accepts is forwarded too. Unknown keys are rejected at construction against the SDK signature, so typos fail here.

Example 
CallOptions(machine_detection="Enable", async_amd=True, record=True)

Config:

  • default: {'populate_by_name': True, 'extra': 'allow'}

Fields:

  • machine_detection (Literal['Enable', 'DetectMessageEnd'] | None)
  • async_amd (bool | None)
  • async_amd_status_callback (str | None)
  • async_amd_status_callback_method (str | None)
  • machine_detection_timeout (int | None)
  • machine_detection_speech_threshold (int | None)
  • machine_detection_speech_end_threshold (int | None)
  • machine_detection_silence_timeout (int | None)
  • record (bool | None)
  • recording_status_callback (str | None)
  • recording_status_callback_event (list[str] | None)
  • recording_channels (str | None)
  • recording_track (str | None)
  • status_callback (str | None)
  • status_callback_event (list[str] | None)
  • status_callback_method (str | None)
  • timeout (int | None)

Validators:

  • _validate_params

machine_detection pydantic-field 

machine_detection: (
    Literal["Enable", "DetectMessageEnd"] | None
) = None

Enables AMD. 'Enable' reports as soon as it can tell human from machine (to hang up on voicemail); 'DetectMessageEnd' waits out the greeting (to leave a message).

async_amd pydantic-field 

async_amd: bool | None = None

Detect in the background. Required for on_amd: with it off, AnsweredBy comes back on the TwiML request, which inline TwiML can't receive.

record pydantic-field 

record: bool | None = None

Required for on_recording.

status_callback_event pydantic-field 

status_callback_event: list[str] | None = None

Lifecycle events to report. Omitted, Twilio sends only 'completed' — which covers busy/canceled/failed/no-answer. Set it for ringing/answered.

timeout pydantic-field 

timeout: int | None = None

Seconds to ring before giving up. Twilio defaults to 60.

InitiateChatConversationOptions pydantic-model

Bases: InitiateMessagingConversationOptions

Options for initiating an outbound Chat conversation.

Extends InitiateMessagingConversationOptions with a required channel_id (Conversations v1 Channel SID) for Chat delivery.

Fields:

  • to (str)
  • message (str)
  • metadata (dict[str, Any] | None)
  • channel_id (str)

InitiateConversationResult pydantic-model

Bases: BaseModel

Result of initiating an outbound messaging conversation.

Config:

  • default: {'arbitrary_types_allowed': True}

Fields:

InitiateMessagingConversationOptions pydantic-model

Bases: BaseModel

Shared options for initiating an outbound messaging conversation.

This base model is used for messaging-style outbound conversations, including SMS, RCS, WhatsApp, and Chat. Each channel may extend this with channel-specific requirements (e.g., Chat requires channel_id).

The sender is always TAC's configured address (config.phone_number for SMS, config.rcs_sender_id for RCS, config.whatsapp_number for WhatsApp, ChatChannelConfig.agent_address for Chat). Multi-sender deployments should use one TAC instance per sender so inbound webhook routing, memory scoping, and configuration stay in sync.

Config:

  • default: {'populate_by_name': True}

Fields:

  • to (str)
  • message (str)
  • metadata (dict[str, Any] | None)

InitiateVoiceConversationOptions pydantic-model

Bases: BaseModel

Options for initiating an outbound voice conversation.

The caller identity is always TAC's configured config.phone_number. Multi-number deployments should use one TAC instance per line.

TwiML for the outbound call is built by merging per-field, highest precedence first: 1. This call's twiml_options (per-call overrides) 2. ConversationRelayProviderConfig.default_twiml_options (channel-wide defaults) 3. TAC defaults (welcome greeting, conversation_configuration, action_url resolved via Studio handoff if configured)

Fields you don't set at a layer fall through to lower layers — so twiml_options=VoiceTwiMLOptionsConversationRelay(voice="es-MX-Neural2-A") on this call overrides only voice; language, interruptible, etc. from the channel config still apply.

Set voice, language, interruptible, etc. on the channel's ConversationRelayProviderConfig.default_twiml_options to apply them to every call (both inbound and outbound). Use this model's twiml_options for per-call overrides (e.g. campaign-specific custom_parameters).

Config:

  • default: {'populate_by_name': True, 'extra': 'forbid'}

Fields:

websocket_url pydantic-field 

websocket_url: str | None = None

Public WebSocket URL for ConversationRelay (e.g. 'wss://your-domain.ngrok.app/ws'). Optional — defaults to the URL derived from TACConfig.voice_public_domain + voice_websocket_path. Pass it here only to override the URL for a specific call.

twiml_options pydantic-field 

twiml_options: VoiceTwiMLOptions | None = None

Per-call overrides for the outbound TwiML — a VoiceTwiMLOptionsConversationRelay for the default ConversationRelay provider. Merged over ConversationRelayProviderConfig.default_twiml_options and TAC defaults.

call_options pydantic-field 

call_options: CallOptions | None = None

Parameters for Twilio's calls.create() — AMD, recording, status callbacks, timeout (see CallOptions). Accepts a plain dict. Callback URLs auto-wire when the matching handler is registered; an explicit URL wins.

InitiateVoiceConversationResult pydantic-model

Bases: BaseModel

Result of initiating an outbound voice conversation.

Fields:

  • call_sid (str)

PaginationMeta pydantic-model

Bases: BaseModel

Pagination metadata for API list responses.

Config:

  • default: {'populate_by_name': True}

Fields:

key pydantic-field 

key: str

Key for the response

page_size pydantic-field 

page_size: int

Page size

previous_token pydantic-field 

previous_token: str | None = None

Token for previous page

next_token pydantic-field 

next_token: str | None = None

Token for next page

AuthorInfo pydantic-model

Bases: BaseModel

Information about the author of a communication.

Fields:

address pydantic-field 

address: str

Author address (phone number or identifier)

participant_id pydantic-field 

participant_id: str | None = None

Participant ID of the author in the conversation

ConversationSession pydantic-model

Bases: BaseModel

Context information for a conversation session that's passed to callbacks.

This provides the necessary context for developers to handle memory-ready events and send responses back through the appropriate channel.

Config:

  • arbitrary_types_allowed: True

Fields:

conversation_id pydantic-field 

conversation_id: str

Unique conversation identifier

call_sid pydantic-field 

call_sid: str | None = None

Twilio Call SID on the Voice channel, None on messaging. The correlation key for call events (VoiceChannel.on_call_status / on_amd / on_recording) and end_call. Equals conversation_id in relay-only mode; look the session up the other way with VoiceChannel.get_conversation_session_by_call_sid.

profile_id pydantic-field 

profile_id: str | None = None

Profile ID associated with conversation (optional)

channel pydantic-field 

channel: str

Channel type (e.g., 'SMS', 'VOICE')

started_at pydantic-field 

started_at: datetime

When the conversation session was started

profile pydantic-field 

profile: ProfileResponse | None = None

Profile information with traits (optional)

author_info pydantic-field 

author_info: AuthorInfo | None = None

Author information from communication event (optional)

ai_agent_info pydantic-field 

ai_agent_info: AuthorInfo | None = None

AI agent information from communication event (optional). Populated on messaging channels and on Conversation Orchestrator-backed voice calls. Remains None in ConversationRelay-only voice mode, where there is no Conversation Orchestrator participant to resolve.

metadata pydantic-field 

metadata: dict

Generic metadata storage for session-specific data

pending_handoff_data pydantic-field 

pending_handoff_data: PendingHandoffData | None = None

Pending handoff payload set by the handoff tool. Voice channel sends this as a WS 'end' message after the LLM's final response.

cached_memory pydantic-field 

cached_memory: TACMemoryResponse | None = None

Cached memory for 'once' mode. Set on first retrieval, cleared on INACTIVE.

cache_lock pydantic-field 

cache_lock: Lock

Lock for task-safe cache operations within the event loop in 'once' mode

build_profile_prompt 

build_profile_prompt(
    trait_groups: list[str] | None = None,
) -> str | None

Build customer profile prompt section for LLM context.

Parameters:

Name Type Description Default
trait_groups list[str] | None

Optional list of trait group names to include. If None, no filtering is applied.

 None

Returns:

Type Description
str | None

LLM prompt section with profile data, or None if no profile data
str | None

is available or no traits match the filter.
Example

section = context.build_profile_prompt(["Contact", "Preferences"]) print(section)

Customer Profile

Information about this customer: - Contact: {"name": "John Doe", "email": "john@example.com"} - Preferences: {"language": "en", "timezone": "PST"}

TACCommunication pydantic-model

Bases: BaseModel

Unified communication model with all fields from both Memory and Conversation Orchestrator APIs.

Provides complete access to all communication fields regardless of the source. Fields not available from a particular API will be None.

Config:

  • default: {'populate_by_name': True}

Fields:

id pydantic-field 

id: str

Communication identifier

author pydantic-field 

author: TACCommunicationAuthor

Communication author

content pydantic-field 

content: TACCommunicationContent

Communication content

recipients pydantic-field 

recipients: list[TACCommunicationAuthor]

Communication recipients

channel_id pydantic-field 

channel_id: str | None = None

Channel-specific reference ID, when provided by the source API

created_at pydantic-field 

created_at: str | None = None

When communication was created

updated_at pydantic-field 

updated_at: str | None = None

When communication was last updated

conversation_id pydantic-field 

conversation_id: str | None = None

Conversation ID (Conversation Orchestrator only)

account_id pydantic-field 

account_id: str | None = None

Account ID (Conversation Orchestrator only)

TACCommunicationAuthor pydantic-model

Bases: BaseModel

Unified author model with all fields from both Memory and Conversation Orchestrator APIs.

Config:

  • default: {'populate_by_name': True}

Fields:

  • address (str)
  • channel (Literal['VOICE', 'SMS', 'RCS', 'EMAIL', 'WHATSAPP', 'CHAT', 'API', 'SYSTEM'])
  • participant_id (str | None)
  • delivery_status (Literal['INITIATED', 'IN_PROGRESS', 'DELIVERED', 'COMPLETED', 'FAILED'] | None)
  • id (str | None)
  • name (str | None)
  • type (Literal['HUMAN_AGENT', 'CUSTOMER', 'AI_AGENT', 'AGENT', 'UNKNOWN'] | None)
  • profile_id (str | None)

address pydantic-field 

address: str

Address of the communication author

channel pydantic-field 

channel: Literal[
    "VOICE",
    "SMS",
    "RCS",
    "EMAIL",
    "WHATSAPP",
    "CHAT",
    "API",
    "SYSTEM",
]

Channel type

participant_id pydantic-field 

participant_id: str | None = None

Participant ID (Conversation Orchestrator only)

delivery_status pydantic-field 

delivery_status: (
    Literal[
        "INITIATED",
        "IN_PROGRESS",
        "DELIVERED",
        "COMPLETED",
        "FAILED",
    ]
    | None
) = None

Delivery status (Conversation Orchestrator recipients only)

id pydantic-field 

id: str | None = None

Author ID (Memory only)

name pydantic-field 

name: str | None = None

Display name (Memory only)

type pydantic-field 

type: (
    Literal[
        "HUMAN_AGENT",
        "CUSTOMER",
        "AI_AGENT",
        "AGENT",
        "UNKNOWN",
    ]
    | None
) = None

Author type (Memory only)

profile_id pydantic-field 

profile_id: str | None = None

Profile ID (Memory only)

TACCommunicationContent pydantic-model

Bases: BaseModel

Unified content model with all fields from both Memory and Conversation Orchestrator APIs.

Config:

  • default: {'populate_by_name': True}

Fields:

type pydantic-field 

type: Literal['TEXT', 'TRANSCRIPTION'] | None = None

Content type discriminator (Conversation Orchestrator only)

text pydantic-field 

text: str | None = None

Message text content

transcription pydantic-field 

transcription: Transcription | None = None

Transcription metadata (Conversation Orchestrator only, when type=TRANSCRIPTION)

TACMemoryResponse 

TACMemoryResponse(
    data: MemoryRetrievalResponse | list[Communication],
)

Unified response wrapper for TAC.retrieve_memory().

Provides a consistent interface for accessing memory data regardless of whether Memory API is configured or falling back to Conversation Orchestrator Communications API.

Memory configured: - observations, summaries, communications all populated - communications include Memory-specific fields (author id, name, type, profile_id)

Conversation Orchestrator fallback: - observations and summaries are empty lists - communications include Conversation Orchestrator-specific fields (conversation_id, account_id, etc.)

Initialize wrapper with either Memory or Conversation Orchestrator data.

Parameters:

Name Type Description Default
data MemoryRetrievalResponse | list[Communication]

Either MemoryRetrievalResponse (Memory) or list[Communication] (Conversation Orchestrator)

 required

observations property 

observations: list[ObservationInfo]

Get observation memories.

Returns:

Type Description
list[ObservationInfo]

List of observations if Memory is configured,
list[ObservationInfo]

empty list for Conversation Orchestrator fallback

summaries property 

summaries: list[SummaryInfo]

Get summary memories.

Returns:

Type Description
list[SummaryInfo]

List of summaries if Memory is configured,
list[SummaryInfo]

empty list for Conversation Orchestrator fallback

communications property 

communications: list[TACCommunication]

Get communications in unified format with all available fields.

Communications are converted to a common format during initialization that includes all fields from both Memory and Conversation Orchestrator APIs. Fields not available from a particular API will be None.

Returns:

Type Description
list[TACCommunication]

List of unified communications with all available fields

has_memory_features property 

has_memory_features: bool

Check if Memory API is configured and providing full features.

Returns:

Type Description
bool

True if Memory is configured (observations/summaries available),
bool

False if using Conversation Orchestrator fallback (only communications available)

raw_data property 

raw_data: MemoryRetrievalResponse | list[Communication]

Access raw underlying data for advanced use cases.

Use this when you need access to all fields from the original API responses, not just the simplified common fields.

Returns:

Type Description
MemoryRetrievalResponse | list[Communication]

Either MemoryRetrievalResponse or list[Communication] depending on configuration

build_memory_prompts 

build_memory_prompts() -> list[str]

Build all memory prompt sections (observations, summaries, communications) for LLM context.

Returns:

Type Description
list[str]

List of LLM prompt sections. Each element is a complete section
list[str]

(e.g., observations section, summaries section). Returns empty list
list[str]

if no memory data is available.
Example

sections = memory_response.build_memory_prompts() for section in sections: ... print(section) ... print()

Key Observations

Important notes about the customer from previous interactions: - Customer prefers email communication - Previously reported billing issue (resolved)

Past Conversation Summaries

Summaries of previous conversations with this customer: - Discussed product features and pricing on 2024-01-15

AmdEvent pydantic-model

Bases: _CallEventBase

A Twilio async_amd_status_callback — answering machine detection.

Fires at most once per call, and only when the call set both CallOptions.machine_detection and async_amd.

answered_by is mode-dependent — machine_start under "Enable", machine_end_beep / machine_end_silence / machine_end_other under "DetectMessageEnd", plus human / fax / unknown in both. Use :attr:is_machine rather than matching those yourself. Register via VoiceChannel.on_amd.

Fields:

  • call_sid (str)
  • account_sid (str | None)
  • extra (dict[str, str])
  • answered_by (str | None)
  • machine_detection_duration (str | None)

is_machine property 

is_machine: bool

A machine answered — any machine_* value, either mode.

unknown (detection timed out) is False, so a call is never hung up on a guess.

CallStatusEvent pydantic-model

Bases: _CallEventBase

A Twilio status_callback — call progress and disposition.

By default Twilio sends only the terminal event, which covers every disposition (completed / busy / no-answer / failed / canceled); set CallOptions.status_callback_event for the intermediate ones. Register via VoiceChannel.on_call_status.

Fields:

  • call_sid (str)
  • account_sid (str | None)
  • extra (dict[str, str])
  • call_status (str | None)
  • call_duration (str | None)
  • sip_response_code (str | None)

is_unreached property 

is_unreached: bool

Call ended without reaching the callee — i.e. worth a retry.

RecordingEvent pydantic-model

Bases: _CallEventBase

A Twilio recording_status_callback — a recording became available.

Fires when the recording is ready (recording_url accessible), only when recording is enabled. Register via VoiceChannel.on_recording.

Fields:

  • call_sid (str)
  • account_sid (str | None)
  • extra (dict[str, str])
  • recording_sid (str | None)
  • recording_url (str | None)
  • recording_status (str | None)
  • recording_duration (str | None)

VoiceTwiMLOptions pydantic-model

Bases: BaseModel

Base for a VoiceProvider's inbound-call TwiML customization options.

Each provider answers the inbound-call webhook with its own TwiML shape (VoiceTwiMLOptionsConversationRelay for <ConversationRelay>, a future subclass for <Stream>), so VoiceProvider.handle_incoming_call's host_twiml_options is typed against this base rather than a specific provider's options.

Rejects unknown fields (inherited by subclasses) — this base has none of its own, so a dict passed where a VoiceTwiMLOptions is expected would otherwise silently validate into an empty instance.

Config:

  • default: {'extra': 'forbid'}

VoiceTwiMLOptionsConversationRelay pydantic-model

Bases: VoiceTwiMLOptions

Options for the TwiML inside <ConversationRelay> (plus the <Connect action> URL).

Fields map to the attributes documented at https://www.twilio.com/docs/voice/twiml/connect/conversationrelay . All fields are optional. VoiceChannel.handle_incoming_call merges these values over TAC defaults using Pydantic's model_fields_set — only fields explicitly set by the caller override TAC's defaults.

Config:

  • default: {'populate_by_name': True}

Fields:

Validators:

  • _reject_empty_websocket_url → websocket_url
  • _reject_extra_shadowing_typed_fields

custom_parameters pydantic-field 

custom_parameters: (
    CustomParameters | dict[str, Any] | None
) = None

Custom parameters to pass to ConversationRelay

welcome_greeting pydantic-field 

welcome_greeting: str | None = None

Initial greeting message for caller

welcome_greeting_interruptible pydantic-field 

welcome_greeting_interruptible: InterruptMode | None = None

What caller input can interrupt the welcome greeting. Defaults to 'any' on Twilio.

action_url pydantic-field 

action_url: str | None = None

URL for Twilio to request when call ends

conversation_configuration pydantic-field 

conversation_configuration: str | None = None

Conversation Service SID for ConversationRelay to automatically manage conversation creation and participants.

websocket_url pydantic-field 

websocket_url: str | None = None

ConversationRelay WebSocket URL (the attribute). Leave None (the default) to use the URL the channel derives from TACConfig.voice_public_domain + voice_websocket_path. Set it only for a per-call URL — e.g. an affinity-routed host that appends a token to the upgrade URL, typically via handle_incoming_call's host_twiml_options. Like every other field, it layers: on_inbound_call_twiml customizer > default_twiml_options > host_twiml_options > TAC default.

language pydantic-field 

language: str | None = None

Language for both STT and TTS, e.g. 'en-US'. Equivalent to setting both tts_language and transcription_language.

tts_language pydantic-field 

tts_language: str | None = None

TTS language code; overrides language for TTS.

transcription_language pydantic-field 

transcription_language: str | None = None

STT language code; overrides language for transcription. Can be 'multi' for automatic language detection (Deepgram only).

voice pydantic-field 

voice: str | None = None

TTS voice name (choices vary by tts_provider)

tts_provider pydantic-field 

tts_provider: str | None = None

TTS provider: 'Google', 'Amazon', or 'ElevenLabs'. Defaults to 'ElevenLabs'.

transcription_provider pydantic-field 

transcription_provider: str | None = None

STT provider: 'Google' or 'Deepgram'. Defaults to 'Deepgram' (or 'Google' for accounts that used ConversationRelay before 2025-09-12).

speech_model pydantic-field 

speech_model: str | None = None

Speech model for STT. Choices vary by transcription_provider.

elevenlabs_text_normalization pydantic-field 

elevenlabs_text_normalization: (
    Literal["on", "auto", "off"] | None
) = None

Text normalization for ElevenLabs TTS. Defaults to 'off'. 'auto' behaves like 'off' for ConversationRelay calls.

eot_threshold pydantic-field 

eot_threshold: float | None = None

Confidence required to finish a turn. Only applies with Deepgram + flux speech model. Twilio enforces the accepted range — see ConversationRelay docs.

partial_prompts pydantic-field 

partial_prompts: bool | None = None

Send unfinalized prompts and eager end-of-turn events (last=False). Only applies with Deepgram + flux speech model.

deepgram_smart_format pydantic-field 

deepgram_smart_format: bool | None = None

Use Deepgram Smart Format for transcription output. Defaults to true when transcription_provider='Deepgram'.

speech_timeout pydantic-field 

speech_timeout: int | Literal['auto'] | None = None

Silence (ms) after speech before finalizing the prompt. Integer milliseconds or the literal 'auto' (the platform default). Twilio enforces the accepted range — see ConversationRelay docs.

interruptible pydantic-field 

interruptible: InterruptMode | bool | None = None

What caller input interrupts TTS playback. Boolean accepted for backward compat: True='any', False='none'. Defaults to 'any'.

interrupt_sensitivity pydantic-field 

interrupt_sensitivity: (
    Literal["high", "medium", "low"] | None
) = None

How easily caller speech triggers an interrupt. Defaults to 'high'.

report_input_during_agent_speech pydantic-field 

report_input_during_agent_speech: InterruptMode | None = (
    None
)

What caller input gets reported while the agent is speaking (independent of whether playback is interrupted). Defaults to 'none' since May 2025.

ignore_backchannel pydantic-field 

ignore_backchannel: bool | None = None

Filter short conversational feedback ('yeah', 'uh-huh', …) so it doesn't interrupt the agent. Defaults to false.

preemptible pydantic-field 

preemptible: bool | None = None

Allow text tokens from the next talk cycle to interrupt the current one. Defaults to false.

dtmf_detection pydantic-field 

dtmf_detection: bool | None = None

Emit DTMF keypress events over the WebSocket.

hints pydantic-field 

hints: str | None = None

Comma-separated words/phrases likely to appear in speech. Capitalize proper nouns.

events pydantic-field 

events: str | None = None

Space-separated event subscriptions, e.g. 'speaker-events tokens-played'.

debug pydantic-field 

debug: str | None = None

Debug subscription, e.g. 'debugging'. Note: 'speaker-events' and 'tokens-played' have moved to the events attribute — only use them here for backward compatibility.

intelligence_service pydantic-field 

intelligence_service: str | None = None

Conversation Intelligence (classic) Service SID or unique name for persisting transcripts and running Language Operators.

languages pydantic-field 

languages: list[LanguageConfig] | None = None

Additional children for multi-language support

extra pydantic-field 

extra: dict[str, str | bool | int] | None = None

Escape hatch for ConversationRelay attributes not yet typed on this model. Keys are emitted as-is on ; Twilio's SDK converts snake_case to camelCase, lowercases bools to 'true'/'false', and stringifies ints. Prefer a typed field when one exists — use extra only for newly-added Twilio attributes not yet in this SDK.