Skip to content
revox
Get started
API Reference
Assistants

Get assistant by ID

assistants.retrieve(id) -> AssistantRetrieveResponse { id, background_sound, calendly, 20 more }
GET/assistants/{id}

Retrieve a single assistant by its unique ID. Returns the full assistant configuration including prompt, voice settings, and first sentence mode. Useful for inspecting an assistant's current setup before updating it or placing a call.

ParametersExpand Collapse
id: String
ReturnsExpand Collapse
class AssistantRetrieveResponse { id, background_sound, calendly, 20 more }
id: String
background_sound: :"audio/office.ogg"

The background sound to play during the call. Useful to give the impression that your AI agent is in an office.

calendly: { connection_id, event_type_id}
connection_id: String

The connection ID representing the link between your Calendly account and Revox.

event_type_id: String

The event type ID representing the event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)

call_retry_config: { calling_windows, max_retry_attempts, timezone}

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

calling_windows: Array[{ calling_window_end_time, calling_window_start_time, retry_delay_seconds}]
calling_window_end_time: String

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: String

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: Integer

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0
maximum9007199254740991
max_retry_attempts: Integer

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0
maximum9007199254740991
timezone: String

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

created_at: untyped
end_of_call_sentence: String
first_sentence: String
first_sentence_delay_ms: Integer

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum-9007199254740991
maximum9007199254740991
first_sentence_mode: :generated | :static | :none
One of the following:
:generated
:static
:none
ivr_navigation_enabled: bool

Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.

llm_model: { name, type} | { openrouter_model_id, openrouter_provider, type}
One of the following:
class UnionMember0 { name, type }
name: :"gpt-4.1" | :"ministral-3-8b-instruct"
One of the following:
:"gpt-4.1"
:"ministral-3-8b-instruct"
type: :"dedicated-instance"
class UnionMember1 { openrouter_model_id, openrouter_provider, type }
openrouter_model_id: String

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: String

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: :openrouter

Use a model from OpenRouter.

max_call_duration_secs: Float

The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.

name: String
organization_id: String
prompt: String
structured_output_config: Array[{ name, required, type, 2 more}]

The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).

name: String
minLength1
required: bool
type: :string | :number | :boolean | 3 more
One of the following:
:string
:number
:boolean
:enum
:date
:datetime
description: String
enum_options: Array[String]
transfer_phone_number: String

Phone number to transfer calls to when users request to speak to a human agent.

updated_at: untyped
voice: { id, provider, speed}
id: String

The ID of the voice.

minLength1
provider: :cartesia | :elevenlabs

The provider of the voice.

One of the following:
:cartesia
:elevenlabs
speed: Float

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2. Default is 1.0.

minimum0.6
maximum1.5
voicemail_message: String

If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.

webhook_url: String

The webhook URL to call when the call is completed.

faq_items: Array[{ answer, question, id, 2 more}]
answer: String
question: String
id: String
needs_human_answer: bool
source: :human | :ai
One of the following:
:human
:ai
pending_faq_count: Float

Get assistant by ID

require "revox"

revox = Revox::Client.new(api_key: "My API Key")

assistant = revox.assistants.retrieve("id")

puts(assistant)
{
  "id": "id",
  "background_sound": "audio/office.ogg",
  "calendly": {
    "connection_id": "connection_id",
    "event_type_id": "event_type_id"
  },
  "call_retry_config": {
    "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": {},
  "end_of_call_sentence": "end_of_call_sentence",
  "first_sentence": "first_sentence",
  "first_sentence_delay_ms": -9007199254740991,
  "first_sentence_mode": "generated",
  "ivr_navigation_enabled": true,
  "llm_model": {
    "name": "gpt-4.1",
    "type": "dedicated-instance"
  },
  "max_call_duration_secs": 0,
  "name": "name",
  "organization_id": "organization_id",
  "prompt": "prompt",
  "structured_output_config": [
    {
      "name": "x",
      "required": true,
      "type": "string",
      "description": "description",
      "enum_options": [
        "string"
      ]
    }
  ],
  "transfer_phone_number": "transfer_phone_number",
  "updated_at": {},
  "voice": {
    "id": "x",
    "provider": "cartesia",
    "speed": 0.6
  },
  "voicemail_message": "voicemail_message",
  "webhook_url": "webhook_url",
  "faq_items": [
    {
      "answer": "answer",
      "question": "question",
      "id": "id",
      "needs_human_answer": true,
      "source": "human"
    }
  ],
  "pending_faq_count": 0
}
Returns Examples
{
  "id": "id",
  "background_sound": "audio/office.ogg",
  "calendly": {
    "connection_id": "connection_id",
    "event_type_id": "event_type_id"
  },
  "call_retry_config": {
    "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": {},
  "end_of_call_sentence": "end_of_call_sentence",
  "first_sentence": "first_sentence",
  "first_sentence_delay_ms": -9007199254740991,
  "first_sentence_mode": "generated",
  "ivr_navigation_enabled": true,
  "llm_model": {
    "name": "gpt-4.1",
    "type": "dedicated-instance"
  },
  "max_call_duration_secs": 0,
  "name": "name",
  "organization_id": "organization_id",
  "prompt": "prompt",
  "structured_output_config": [
    {
      "name": "x",
      "required": true,
      "type": "string",
      "description": "description",
      "enum_options": [
        "string"
      ]
    }
  ],
  "transfer_phone_number": "transfer_phone_number",
  "updated_at": {},
  "voice": {
    "id": "x",
    "provider": "cartesia",
    "speed": 0.6
  },
  "voicemail_message": "voicemail_message",
  "webhook_url": "webhook_url",
  "faq_items": [
    {
      "answer": "answer",
      "question": "question",
      "id": "id",
      "needs_human_answer": true,
      "source": "human"
    }
  ],
  "pending_faq_count": 0
}