Create an assistant
Create a new AI assistant with a custom prompt, voice, and behavior configuration. Assistants define how the AI agent behaves during calls, including the system prompt given to the LLM, the first sentence spoken, the voice provider and voice ID (Cartesia or ElevenLabs), and end-of-call behavior. Once created, reference the assistant by its ID when placing calls.
Parameters
The prompt to use for the call. This will be given to the LLM (gpt-4.1)
Prompt / instructions for the after-call SMS. Supports {{variable}} placeholders. When null, no after-call SMS is sent.
Ambient background sound to play during the call. null/omitted disables it.
Volume of the ambient background sound (0 = silent, 1 = max).
Email address to receive notifications when a call ends with a matching outcome.
Optional message to say when the agent decides to end the call.
The first sentence to use for the call. This will be given to the LLM
Delay in milliseconds before speaking the first sentence. Default: 400.
Override the default outbound phone number for calls placed with this assistant. Must be a phone number owned by the organization in E.164 format (e.g. +1234567890). When null, the organization's default phone number is used.
The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
Optional message the agent will say, without being interruptible, when the call reaches its max duration. Kept short so it fits inside the farewell buffer. If not set, the call ends silently.
Enable SMS tool during calls. When enabled, the agent can send SMS messages to the user on the call.
Hardcoded SMS template to send during calls. When set, this exact text is sent instead of letting the agent generate the message. Supports {{variable}} placeholders.
Custom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking.
Volume of the thinking sound (0 = silent, 1 = max).
Phone number to transfer calls to when users request to speak to a human agent in E.164 format (e.g. +1234567890).
If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
SMS message to send when the call reaches voicemail. Supports {{variable}} placeholders. When null, no SMS is sent on voicemail.
When using warm transfer: extra instructions for the supervisor handoff summary. If null or empty, the API uses the product default briefing when the call is loaded for the agent.
The webhook URL to call when the call is completed.
Returns
Create an assistant
import os
from revox import Revox
client = Revox(
api_key=os.environ.get("REVOX_API_KEY"), # This is the default and can be omitted
)
assistant = client.assistants.create(
name="name",
prompt="prompt",
)
print(assistant.assistant){
"assistant": {
"id": "id",
"after_call_sms_prompt": "after_call_sms_prompt",
"background_sound": "audio/office.ogg",
"background_sound_volume": 0,
"calendly": {
"connection_id": "connection_id",
"event_type_id": "event_type_id"
},
"call_retry_config": {
"allowed_days": [
"monday"
],
"call_twice_in_a_row": true,
"calling_windows": [
{
"calling_window_end_time": "calling_window_end_time",
"calling_window_start_time": "calling_window_start_time",
"retry_delay_seconds": 1
}
],
"max_retry_attempts": 1,
"timezone": "timezone"
},
"created_at": {},
"custom_tools": [
{
"body_template": "body_template",
"description": "x",
"headers": [
{
"key": "x",
"value": "value"
}
],
"input_schema": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"method": "GET",
"name": "name",
"query_params": [
{
"key": "x",
"value": "value"
}
],
"url": "x"
}
],
"email_notification_address": "dev@stainless.com",
"email_notification_outcomes": [
"not_interested"
],
"end_of_call_sentence": "end_of_call_sentence",
"first_sentence": "first_sentence",
"first_sentence_delay_ms": -9007199254740991,
"first_sentence_mode": "generated",
"from_phone_number": "from_phone_number",
"human_transfer_mode": "warm",
"ivr_navigation_enabled": true,
"llm_model": {
"name": "gpt-4.1",
"type": "dedicated-instance"
},
"max_call_duration_secs": 0,
"max_duration_end_message": "max_duration_end_message",
"name": "name",
"organization_id": "organization_id",
"prompt": "prompt",
"sms_enabled": true,
"sms_template": "sms_template",
"structured_output_config": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"structured_output_prompt": "structured_output_prompt",
"thinking_sound": "city-ambience.ogg",
"thinking_sound_probability": 0,
"thinking_sound_volume": 0,
"transfer_phone_number": "transfer_phone_number",
"updated_at": {},
"voice": {
"id": "x",
"provider": "cartesia",
"speed": 0.6,
"volume": 0.5
},
"voicemail_message": "voicemail_message",
"voicemail_sms_prompt": "voicemail_sms_prompt",
"warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
"webhook_url": "webhook_url",
"faq_items": [
{
"answer": "answer",
"question": "question",
"id": "id",
"needs_human_answer": true,
"source": "human"
}
],
"pending_faq_count": 0
}
}Returns Examples
{
"assistant": {
"id": "id",
"after_call_sms_prompt": "after_call_sms_prompt",
"background_sound": "audio/office.ogg",
"background_sound_volume": 0,
"calendly": {
"connection_id": "connection_id",
"event_type_id": "event_type_id"
},
"call_retry_config": {
"allowed_days": [
"monday"
],
"call_twice_in_a_row": true,
"calling_windows": [
{
"calling_window_end_time": "calling_window_end_time",
"calling_window_start_time": "calling_window_start_time",
"retry_delay_seconds": 1
}
],
"max_retry_attempts": 1,
"timezone": "timezone"
},
"created_at": {},
"custom_tools": [
{
"body_template": "body_template",
"description": "x",
"headers": [
{
"key": "x",
"value": "value"
}
],
"input_schema": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"method": "GET",
"name": "name",
"query_params": [
{
"key": "x",
"value": "value"
}
],
"url": "x"
}
],
"email_notification_address": "dev@stainless.com",
"email_notification_outcomes": [
"not_interested"
],
"end_of_call_sentence": "end_of_call_sentence",
"first_sentence": "first_sentence",
"first_sentence_delay_ms": -9007199254740991,
"first_sentence_mode": "generated",
"from_phone_number": "from_phone_number",
"human_transfer_mode": "warm",
"ivr_navigation_enabled": true,
"llm_model": {
"name": "gpt-4.1",
"type": "dedicated-instance"
},
"max_call_duration_secs": 0,
"max_duration_end_message": "max_duration_end_message",
"name": "name",
"organization_id": "organization_id",
"prompt": "prompt",
"sms_enabled": true,
"sms_template": "sms_template",
"structured_output_config": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"structured_output_prompt": "structured_output_prompt",
"thinking_sound": "city-ambience.ogg",
"thinking_sound_probability": 0,
"thinking_sound_volume": 0,
"transfer_phone_number": "transfer_phone_number",
"updated_at": {},
"voice": {
"id": "x",
"provider": "cartesia",
"speed": 0.6,
"volume": 0.5
},
"voicemail_message": "voicemail_message",
"voicemail_sms_prompt": "voicemail_sms_prompt",
"warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
"webhook_url": "webhook_url",
"faq_items": [
{
"answer": "answer",
"question": "question",
"id": "id",
"needs_human_answer": true,
"source": "human"
}
],
"pending_faq_count": 0
}
}