Conversation
The Conversation object, its attributes, and methods.
The Conversation object (conv) provides access to conversation data and tools for managing the agent’s behaviour. It handles state management, flow transitions, SMS interactions, environment details, and voice selection.
Attributes
id
id
Description: Unique identifier of the conversation.
Example:
account_id
account_id
Description: PolyAI account ID that owns this project.
Example:
project_id
project_id
Description: Project ID of the current agent.
Example:
env
env
sip_headers
sip_headers
Description: Dictionary of SIP headers (dict[str, str]) provided by the carrier.
Example:
integration_attributes
integration_attributes
Description: Metadata passed from an external integration (dict[str, Any]).
Only available inside the start function.
Example:
caller_number
caller_number
Description: Caller’s phone number in E.164 format, or None on chat channels.
Example:
callee_number
callee_number
Description: Number dialled by the caller.
Example:
state
state
Description: Dictionary-like store that persists values across turns.
Example:
current_flow
current_flow
Description: Name of the flow currently executing, or None.
sms_queue
sms_queue
Description: List of OutgoingSMS / OutgoingSMSTemplate objects queued for dispatch at turn end.
metrics_queue
metrics_queue
Description: List of custom metrics queued for analytics.
variant_name
variant_name
Description: Name of the active variant, or None.
variants
variants
Description: Dictionary of all variant definitions (dict[str, Variant]).
variant
variant
Description: Variant object for the active variant, or None.
Example:
sms_templates
sms_templates
Description: Dictionary of SMS templates (dict[str, SMSTemplate]).
Example:
voice_change
voice_change
Description: Pending TTSVoice change requested this turn, or None.
language
language
Description: ISO-639 language code configured for the project (e.g. "en").
history
history
Description: Chronological list of UserInput and AgentResponse events so far.
Example:
handoffs
handoffs
Description: Dictionary of configured hand-off destinations (dict[str, HandoffConfig]).
Example:
transcript_alternatives
transcript_alternatives
Description: List of ASR alternatives for the last user utterance.
Example:
real_time_config
real_time_config
Description: Returns a dictionary of real-time configuration values defined in Configuration Builder.
Use this to read values like opening_hours, fallback_number, or flags for toggling logic between environments.
Example:
memory
memory
Description: Dictionary of memory fields previously stored for the caller, retrieved from Agent Memory.
Use conv.memory.get("key") to access previously saved values across conversations. You can store new fields by assigning them to conv.state if the field is listed in the Agent Memory config.
Example:
Methods
say
say
Description: Override the next utterance.
Example:
randomize_voice
randomize_voice
Description: Randomly choose a voice based on weighted probabilities.
Example:
goto_flow
goto_flow
Description: Transition to another flow at turn end.
Example:
exit_flow
exit_flow
Description: Exit the current flow.
Example:
set_variant
set_variant
Description: Manually set the active variant.
Example:
log_api_response
log_api_response
Description: Log an external API response for analytics.
Example:
send_sms
send_sms
Description: Queue a plain-text SMS.
Example:
send_sms_template
send_sms_template
Description: Queue a pre-configured SMS template.
Example:
write_metric
write_metric
Description: Write a custom metric to the analytics pipeline.
call_handoff
call_handoff
Description: Transfer the call to a configured handoff destination.
This method supports optional reason and utterance fields:
| Parameter | Type | Description |
|---|---|---|
destination | str | Handoff target key (e.g. "BillingQueue"). Must be defined in your agent config. |
reason | str or None | Short code for escalation reason. Appears in Conversation Review and API. |
utterance | str or None | Spoken message just before transfer begins. Also appears in logs and Review. |
Example:
Where it shows up:
- In flows or actions using
builtin-handoff, the fields appear as config options. - In functions, you call
conv.call_handoff(...)directly. - In Conversation Review and the Conversations API, both fields appear for debugging and analytics.
Conversation
The Conversation object, its attributes, and methods.
The Conversation object (conv) provides access to conversation data and tools for managing the agent’s behaviour. It handles state management, flow transitions, SMS interactions, environment details, and voice selection.
Attributes
id
id
Description: Unique identifier of the conversation.
Example:
account_id
account_id
Description: PolyAI account ID that owns this project.
Example:
project_id
project_id
Description: Project ID of the current agent.
Example:
env
env
sip_headers
sip_headers
Description: Dictionary of SIP headers (dict[str, str]) provided by the carrier.
Example:
integration_attributes
integration_attributes
Description: Metadata passed from an external integration (dict[str, Any]).
Only available inside the start function.
Example:
caller_number
caller_number
Description: Caller’s phone number in E.164 format, or None on chat channels.
Example:
callee_number
callee_number
Description: Number dialled by the caller.
Example:
state
state
Description: Dictionary-like store that persists values across turns.
Example:
current_flow
current_flow
Description: Name of the flow currently executing, or None.
sms_queue
sms_queue
Description: List of OutgoingSMS / OutgoingSMSTemplate objects queued for dispatch at turn end.
metrics_queue
metrics_queue
Description: List of custom metrics queued for analytics.
variant_name
variant_name
Description: Name of the active variant, or None.
variants
variants
Description: Dictionary of all variant definitions (dict[str, Variant]).
variant
variant
Description: Variant object for the active variant, or None.
Example:
sms_templates
sms_templates
Description: Dictionary of SMS templates (dict[str, SMSTemplate]).
Example:
voice_change
voice_change
Description: Pending TTSVoice change requested this turn, or None.
language
language
Description: ISO-639 language code configured for the project (e.g. "en").
history
history
Description: Chronological list of UserInput and AgentResponse events so far.
Example:
handoffs
handoffs
Description: Dictionary of configured hand-off destinations (dict[str, HandoffConfig]).
Example:
transcript_alternatives
transcript_alternatives
Description: List of ASR alternatives for the last user utterance.
Example:
real_time_config
real_time_config
Description: Returns a dictionary of real-time configuration values defined in Configuration Builder.
Use this to read values like opening_hours, fallback_number, or flags for toggling logic between environments.
Example:
memory
memory
Description: Dictionary of memory fields previously stored for the caller, retrieved from Agent Memory.
Use conv.memory.get("key") to access previously saved values across conversations. You can store new fields by assigning them to conv.state if the field is listed in the Agent Memory config.
Example:
Methods
say
say
Description: Override the next utterance.
Example:
randomize_voice
randomize_voice
Description: Randomly choose a voice based on weighted probabilities.
Example:
goto_flow
goto_flow
Description: Transition to another flow at turn end.
Example:
exit_flow
exit_flow
Description: Exit the current flow.
Example:
set_variant
set_variant
Description: Manually set the active variant.
Example:
log_api_response
log_api_response
Description: Log an external API response for analytics.
Example:
send_sms
send_sms
Description: Queue a plain-text SMS.
Example:
send_sms_template
send_sms_template
Description: Queue a pre-configured SMS template.
Example:
write_metric
write_metric
Description: Write a custom metric to the analytics pipeline.
call_handoff
call_handoff
Description: Transfer the call to a configured handoff destination.
This method supports optional reason and utterance fields:
| Parameter | Type | Description |
|---|---|---|
destination | str | Handoff target key (e.g. "BillingQueue"). Must be defined in your agent config. |
reason | str or None | Short code for escalation reason. Appears in Conversation Review and API. |
utterance | str or None | Spoken message just before transfer begins. Also appears in logs and Review. |
Example:
Where it shows up:
- In flows or actions using
builtin-handoff, the fields appear as config options. - In functions, you call
conv.call_handoff(...)directly. - In Conversation Review and the Conversations API, both fields appear for debugging and analytics.