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
Ambient background sound to play during the call. null/omitted disables it.
Volume of the ambient background sound (0 = silent, 1 = max).
Optional Cartesia pronunciation dictionary ID to use for this assistant’s calls. Set null to unlink it.
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.
When true, the agent’s noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.
Public URL of the brand logo shown on the assistant’s demo page. Upload a new logo via POST /assistants/:id/logo. Set explicitly to null to clear it.
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.
Instructions the agent follows once the call has ended: who to email, when to text, what to post on Slack or Teams. Plain language, no template syntax. Empty or null means no post-call agent runs.
Inbound calls only. URL fetched over HTTP GET right before the call is answered, with {{phone}} replaced by the caller’s number in E.164 format (URL-encoded), to fill the {{variable}} placeholders the assistant declares. It answers either {"prompt_variables": {...}} or a flat JSON object whose top-level fields are the variables. The call is always answered: if the endpoint fails, takes more than 3 seconds, answers 404 or leaves a variable out, the missing variables are marked as not provided. Must be an http(s) URL containing {{phone}}. When null, no lookup is performed.
Name of a multi-step flow’s start step. Defaults to the assistant’s name.
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}}.
When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.
Soniox endpoint latency adjustment level (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: Soniox default.
Soniox endpoint sensitivity (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: Soniox default.
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).
If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.
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.
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",
"background_sound": "audio/office.ogg",
"background_sound_volume": 0,
"cal": {
"connection_id": "connection_id",
"event_type_id": "event_type_id"
},
"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": {}
}
],
"max_retry_attempts": 1,
"timezone": "timezone"
},
"cartesia_dictionary_pronunciation_id": "cartesia_dictionary_pronunciation_id",
"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"
}
],
"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",
"hubspot": {
"connection_id": "connection_id",
"meeting_links": [
{
"booking_url": "booking_url",
"duration_ms": 1,
"is_fallback": true,
"label": "x",
"slug": "x"
}
],
"precall_lookup_enabled": true,
"post_call_sync": {
"enabled": true,
"field_mapping": [
{
"hubspot_property": "x",
"source": "x"
}
]
}
},
"human_transfer_mode": "warm",
"ivr_navigation_enabled": true,
"krisp_viva_filter_enabled": true,
"llm_model": {
"type": "recommended"
},
"logo_url": "logo_url",
"max_call_duration_secs": 0,
"max_duration_end_message": "max_duration_end_message",
"name": "name",
"organization_id": "organization_id",
"position": {
"x": 0,
"y": 0
},
"post_call_prompt": "post_call_prompt",
"precall_lookup_headers": [
{
"key": "key",
"value": "x"
}
],
"precall_lookup_url": "precall_lookup_url",
"prompt": "prompt",
"slack": {
"channels": [
{
"id": "id",
"name": "name"
}
],
"connection_id": "connection_id"
},
"start_step_name": "start_step_name",
"structured_output_config": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"structured_output_prompt": "structured_output_prompt",
"stt_bvc_filter_enabled": true,
"stt_context": {
"general": [
{
"key": "x",
"value": "x"
}
],
"terms": [
"x"
]
},
"stt_endpoint_latency_level": -9007199254740991,
"stt_endpoint_sensitivity": 0,
"stt_model": "stt-rt-v4",
"teams": {
"channels": [
{
"id": "id",
"team_id": "team_id",
"name": "name",
"team_name": "team_name"
}
],
"connection_id": "connection_id"
},
"thinking_sound": "city-ambience.ogg",
"thinking_sound_probability": 0,
"thinking_sound_volume": 0,
"transfer_destinations": [
{
"label": "x",
"phone_number": "phone_number"
}
],
"type": "standalone",
"updated_at": {},
"voice": {
"id": "x",
"provider": "cartesia",
"model": "sonic-3",
"speed": 0.6,
"volume": 0.5
},
"voice_languages": [
{
"language": "en",
"voice": {
"id": "x",
"provider": "cartesia",
"model": "sonic-3",
"speed": 0.6,
"volume": 0.5
}
}
],
"voicemail_message": "voicemail_message",
"warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
"warm_transfer_voice_speed": 0.6,
"webhook_url": "webhook_url",
"zoho": {
"connection_id": "connection_id",
"field_mapping": [
{
"source": "x",
"zoho_field": "x"
}
],
"log_call_activity": true,
"module": "x",
"template": "template"
},
"created_by": {
"id": "id",
"email": "email",
"first_name": "first_name",
"last_name": "last_name"
},
"is_inbound_receptionist": true,
"is_realestate_assistant": true
}
}Returns Examples
{
"assistant": {
"id": "id",
"background_sound": "audio/office.ogg",
"background_sound_volume": 0,
"cal": {
"connection_id": "connection_id",
"event_type_id": "event_type_id"
},
"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": {}
}
],
"max_retry_attempts": 1,
"timezone": "timezone"
},
"cartesia_dictionary_pronunciation_id": "cartesia_dictionary_pronunciation_id",
"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"
}
],
"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",
"hubspot": {
"connection_id": "connection_id",
"meeting_links": [
{
"booking_url": "booking_url",
"duration_ms": 1,
"is_fallback": true,
"label": "x",
"slug": "x"
}
],
"precall_lookup_enabled": true,
"post_call_sync": {
"enabled": true,
"field_mapping": [
{
"hubspot_property": "x",
"source": "x"
}
]
}
},
"human_transfer_mode": "warm",
"ivr_navigation_enabled": true,
"krisp_viva_filter_enabled": true,
"llm_model": {
"type": "recommended"
},
"logo_url": "logo_url",
"max_call_duration_secs": 0,
"max_duration_end_message": "max_duration_end_message",
"name": "name",
"organization_id": "organization_id",
"position": {
"x": 0,
"y": 0
},
"post_call_prompt": "post_call_prompt",
"precall_lookup_headers": [
{
"key": "key",
"value": "x"
}
],
"precall_lookup_url": "precall_lookup_url",
"prompt": "prompt",
"slack": {
"channels": [
{
"id": "id",
"name": "name"
}
],
"connection_id": "connection_id"
},
"start_step_name": "start_step_name",
"structured_output_config": [
{
"name": "x",
"required": true,
"type": "string",
"description": "description",
"enum_options": [
"string"
]
}
],
"structured_output_prompt": "structured_output_prompt",
"stt_bvc_filter_enabled": true,
"stt_context": {
"general": [
{
"key": "x",
"value": "x"
}
],
"terms": [
"x"
]
},
"stt_endpoint_latency_level": -9007199254740991,
"stt_endpoint_sensitivity": 0,
"stt_model": "stt-rt-v4",
"teams": {
"channels": [
{
"id": "id",
"team_id": "team_id",
"name": "name",
"team_name": "team_name"
}
],
"connection_id": "connection_id"
},
"thinking_sound": "city-ambience.ogg",
"thinking_sound_probability": 0,
"thinking_sound_volume": 0,
"transfer_destinations": [
{
"label": "x",
"phone_number": "phone_number"
}
],
"type": "standalone",
"updated_at": {},
"voice": {
"id": "x",
"provider": "cartesia",
"model": "sonic-3",
"speed": 0.6,
"volume": 0.5
},
"voice_languages": [
{
"language": "en",
"voice": {
"id": "x",
"provider": "cartesia",
"model": "sonic-3",
"speed": 0.6,
"volume": 0.5
}
}
],
"voicemail_message": "voicemail_message",
"warm_transfer_summary_instructions": "warm_transfer_summary_instructions",
"warm_transfer_voice_speed": 0.6,
"webhook_url": "webhook_url",
"zoho": {
"connection_id": "connection_id",
"field_mapping": [
{
"source": "x",
"zoho_field": "x"
}
],
"log_call_activity": true,
"module": "x",
"template": "template"
},
"created_by": {
"id": "id",
"email": "email",
"first_name": "first_name",
"last_name": "last_name"
},
"is_inbound_receptionist": true,
"is_realestate_assistant": true
}
}