Models¶

tac.models ¶

Shared models for the Twilio Agent Connect.

ActionChannelSettings ¶

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.

ActionParticipantRef ¶

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.

ActionResponse ¶

Bases: BaseModel

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

ActionTextContent ¶

Bases: BaseModel

Plain-text content for a SEND_MESSAGE action.

Communication ¶

Bases: BaseModel

A communication representing a message exchanged in a conversation.

CommunicationContent ¶

Bases: BaseModel

Content of a communication (ContentText or ContentTranscription).

CommunicationParticipant ¶

Bases: BaseModel

Author or recipient in a communication.

CommunicationRequest ¶

Bases: BaseModel

Request payload for adding a communication.

ConversationRequest ¶

Bases: BaseModel

Request payload for creating a conversation.

ConversationResponse ¶

Bases: BaseModel

Response from creating a conversation.

ParticipantAddress ¶

Bases: BaseModel

Communication address for a conversation participant.

ParticipantRequest ¶

Bases: BaseModel

Request payload for creating a conversation participant.

ParticipantResponse ¶

Bases: BaseModel

Response from creating a participant.

SendMessageActionPayload ¶

Bases: BaseModel

Inner payload for a SEND_MESSAGE action.

SendMessageActionRequest ¶

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.

HandoffPayload ¶

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).

CommunicationsRange ¶

Bases: BaseModel

Range of communications used in the operator execution.

ExecutionDetails ¶

Bases: BaseModel

Execution context details for the operator result.

IntelligenceConfiguration ¶

Bases: BaseModel

Intelligence configuration details from the CI service.

Operator ¶

Bases: BaseModel

Operator details from the CI service.

OperatorResultEvent ¶

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.

Participant ¶

Bases: BaseModel

Participant in a conversation.

TriggerDetails ¶

Bases: BaseModel

Trigger details for the operator execution.

Knowledge ¶

Bases: BaseModel

Represents a Twilio Knowledge resource.

KnowledgeBase ¶

Bases: BaseModel

Represents a Twilio Knowledge Base resource.

KnowledgeChunkResult ¶

Bases: BaseModel

Represents a search result chunk from knowledge base search.

MemoryCommunication ¶

Bases: BaseModel

A communication from Memory API (historical conversation data).

MemoryCommunicationContent ¶

Bases: BaseModel

Content of a Memory communication.

MemoryParticipant ¶

Bases: BaseModel

Participant in a Memory communication (author or recipient).

MemoryRetrievalRequest ¶

Bases: BaseModel

Request payload for retrieving conversation memories.

MemoryRetrievalResponse ¶

Bases: BaseModel

Response from the Memory API /Recall endpoint.

ObservationInfo ¶

Bases: BaseModel

An observation memory from the API response.

ProfileResponse ¶

Bases: BaseModel

Response from the profile retrieval API.

SummaryInfo ¶

Bases: BaseModel

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

InitiateChatConversationOptions ¶

Bases: InitiateMessagingConversationOptions

Options for initiating an outbound Chat conversation.

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

InitiateConversationResult ¶

Bases: BaseModel

Result of initiating an outbound messaging conversation.

InitiateMessagingConversationOptions ¶

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.

InitiateVoiceConversationOptions ¶

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. VoiceChannelConfig.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=TwiMLOptions(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 VoiceChannelConfig.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).

InitiateVoiceConversationResult ¶

Bases: BaseModel

Result of initiating an outbound voice conversation.

PaginationMeta ¶

Bases: BaseModel

Pagination metadata for API list responses.

AuthorInfo ¶

Bases: BaseModel

Information about the author of a communication.

ConversationSession ¶

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.

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 ¶

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.

TACCommunicationAuthor ¶

Bases: BaseModel

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

TACCommunicationContent ¶

Bases: BaseModel

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

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

TwiMLOptions ¶

Bases: BaseModel

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.

Models¶

tac.models ¶

ActionChannelSettings ¶

ActionParticipantRef ¶

ActionResponse ¶

ActionTextContent ¶

Communication ¶

CommunicationContent ¶

CommunicationParticipant ¶

CommunicationRequest ¶

ConversationRequest ¶

ConversationResponse ¶

ParticipantAddress ¶

ParticipantRequest ¶

ParticipantResponse ¶

SendMessageActionPayload ¶

SendMessageActionRequest ¶

HandoffPayload ¶

CommunicationsRange ¶

ExecutionDetails ¶

IntelligenceConfiguration ¶

Operator ¶

OperatorResultEvent ¶

Participant ¶

TriggerDetails ¶

Knowledge ¶

KnowledgeBase ¶

KnowledgeChunkResult ¶

MemoryCommunication ¶

MemoryCommunicationContent ¶

MemoryParticipant ¶

MemoryRetrievalRequest ¶

MemoryRetrievalResponse ¶

ObservationInfo ¶

ProfileResponse ¶

SummaryInfo ¶

InitiateChatConversationOptions ¶

InitiateConversationResult ¶

InitiateMessagingConversationOptions ¶

InitiateVoiceConversationOptions ¶

InitiateVoiceConversationResult ¶

PaginationMeta ¶

AuthorInfo ¶

ConversationSession ¶

build_profile_prompt ¶

Customer Profile¶

TACCommunication ¶

TACCommunicationAuthor ¶

TACCommunicationContent ¶

TACMemoryResponse ¶

observations property ¶

summaries property ¶

communications property ¶

has_memory_features property ¶

raw_data property ¶

build_memory_prompts ¶

Key Observations¶

Past Conversation Summaries¶

TwiMLOptions ¶

observations `property` ¶

summaries `property` ¶

communications `property` ¶

has_memory_features `property` ¶

raw_data `property` ¶