Place a call

client.call.create(, ?): CallCreateResponse { call }

POST/call

Place a new outbound call order. Provide either an existing assistant ID or a custom assistant configuration. The call can be scheduled for a specific time or started immediately. A single call order may be resolved over multiple call attempts spanning up to a few days, with automatic retries when voicemail is detected. You can also set concurrency limits and pass prompt variables for dynamic personalization.

ParametersExpand Collapse

body: CallCreateParams { phone_number, assistant, assistant_id, 6 more }

phone_number: string

The phone number to call in the E.164 format. Example: +1234567890

assistant?: Assistant

You can provide a custom assistant configuration here. If you don't provide an assistant_id, this assistant object will be used for this call.

prompt: string

The prompt to use for the call. This will be given to the LLM (gpt-4.1)

background_sound?: "audio/office.ogg" | null

The background sound to play during the call. Useful to give the impression that your AI agent is in an office, in the street, or anywhere else you want.

calendly?: 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?: CallRetryConfig { 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<CallingWindow>

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: number

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

exclusiveMinimum0

maximum9007199254740991

max_retry_attempts: number

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0

maximum9007199254740991

timezone?: string | null

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

end_of_call_sentence?: string

Optional message to say when the agent decides to end the call.

faq_items?: Array<FaqItem>

FAQ items to associate with this assistant. When provided, replaces all existing FAQ items.

answer: string

question: string

first_sentence?: string

The first sentence to use for the call. This will be given to the LLM

first_sentence_delay_ms?: number

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

minimum0

maximum9007199254740991

first_sentence_mode?: "generated" | "static" | "none"

How the first sentence should be handled. "generated" means the LLM will generate a response based on the first_sentence instruction. "static" means the first_sentence will be spoken exactly as provided. "none" means the agent will not speak first and will wait for the user.

One of the following:

"generated"

"static"

"none"

ivr_navigation_enabled?: boolean

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

llm_model?: UnionMember0 { name, type } | UnionMember1 { openrouter_model_id, openrouter_provider, type }

One of the following:

UnionMember0 { name, type }

One of the following:

"gpt-4.1"

"ministral-3-8b-instruct"

type: "dedicated-instance"

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?: number

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

structured_output_config?: Array<StructuredOutputConfig>

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

minLength1

required: boolean

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 | null

Phone number to transfer calls to when users request to speak to a human agent in E.164 format (e.g. +1234567890).

voice?: Voice { id, provider, speed }

The voice to use for the call. You can get the list of voices using the /voices endpoint

id: string

The ID of the voice.

minLength1

provider: "cartesia" | "elevenlabs"

The provider of the voice.

One of the following:

"cartesia"

"elevenlabs"

speed?: number

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 | null

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.

assistant_id?: string

The ID of the assistant to use for this call.

concurrency?: Concurrency

Limit the number of concurrent calls for a given concurrency key.

key: string

The key for which you want to limit the number of concurrent calls.

max: number

The maximum number of concurrent calls to allow for the given concurrency key.

minimum1

force_now?: boolean

The prompt to use for the call. This will be given to the LLM (gpt-4.1)

from_phone_number?: string

The phone number to use for making the call (e.g., +1234567890). If not provided, uses the default trunk.

metadata?: Record<string, string>

Metadata to store with the call.

prompt_variables?: Record<string, string>

Variables to interpolate into the prompt. Wether you use an assistant_id or an assistant object, this will be used to interpolate the variables into the prompt.

scheduled_at?: string | unknown

Schedule the call to start at a specific date and time (ISO 8601 format). If not provided, the call will start immediately.

One of the following:

string

unknown

ReturnsExpand Collapse

CallCreateResponse { call }

call: Call { id, assistant, call_attempts, 16 more }

This represent a call "order" that was requested by the user. A call order can be resolved over multiple call attempts spanning up to a few days.

id: string

The ID of the call.

assistant: Assistant | null

id: string

background_sound: "audio/office.ogg" | null

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

calendly: Calendly | null

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: CallRetryConfig | null

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

calling_windows: Array<CallingWindow>

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: number

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

exclusiveMinimum0

maximum9007199254740991

max_retry_attempts: number

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0

maximum9007199254740991

timezone?: string | null

created_at: unknown

end_of_call_sentence: string | null

first_sentence: string | null

first_sentence_delay_ms: number

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: boolean

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

llm_model: UnionMember0 { name, type } | UnionMember1 { openrouter_model_id, openrouter_provider, type }

One of the following:

UnionMember0 { name, type }

One of the following:

"gpt-4.1"

"ministral-3-8b-instruct"

type: "dedicated-instance"

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: number

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

organization_id: string

prompt: string

structured_output_config: Array<StructuredOutputConfig> | null

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

minLength1

required: boolean

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 | null

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

updated_at: unknown

voice: Voice | null

id: string

The ID of the voice.

minLength1

provider: "cartesia" | "elevenlabs"

The provider of the voice.

One of the following:

"cartesia"

"elevenlabs"

speed?: number

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 | null

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

webhook_url: string | null

The webhook URL to call when the call is completed.

faq_items?: Array<FaqItem>

answer: string

question: string

id?: string

needs_human_answer?: boolean

source?: "human" | "ai"

One of the following:

"human"

"ai"

pending_faq_count?: number

call_attempts: Array<CallAttempt>

All call attempts for this call order, ordered by most recent first.

id: string

The ID of the call attempt.

answered_at: unknown

The time the call was answered.

dial_error: "number_non_attributed" | "too_many_calls" | "busy" | 5 more | null

The SIP error that occurred.

One of the following:

"number_non_attributed"

"too_many_calls"

"busy"

"temporarily_unavailable"

"no_answer"

"no_international_permission"

"precondition_failed"

"non_classified_error"

ended_at: unknown

The time the call ended.

phone_number: string

The phone number that was called. Formatted in E.164 format. Example: +1234567890

recording_url: string | null

The URL of the audio recording of the call.

result: "IVR" | "voicemail" | "human" | 2 more | null

One of the following:

"IVR"

"voicemail"

"human"

"unknown"

"ios-screening-filter"

started_at: unknown

The time the call started.

status: "queued" | "ringing" | "ongoing" | 2 more

The status of the call attempt.

One of the following:

"queued"

"ringing"

"ongoing"

"completed"

"error"

end_reason?: string | null

Reason for ending the call when ended_by is 'agent'. E.g. 'tool_end_call', 'voicemail', 'transfer', 'ivr_no_navigate'.

ended_by?: "agent" | "user" | "system" | null

Who ended the call: 'agent' (AI agent), 'user' (caller/callee hung up), or 'system' (e.g. max duration limit).

One of the following:

"agent"

"user"

"system"

structured_output?: Record<string, unknown> | null

The data extracted from the call, using the structured output config from the parent call object.

transcript?: Array<Transcript> | null

The transcript of the call.

content: string

role: "user" | "assistant" | "tool"

One of the following:

"user"

"assistant"

"tool"

tool_arguments?: Record<string, unknown> | string

One of the following:

Record<string, unknown>

string

tool_is_error?: boolean

tool_name?: string

call_retry_config: CallRetryConfig | null

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

calling_windows: Array<CallingWindow>

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: number

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

exclusiveMinimum0

maximum9007199254740991

max_retry_attempts: number

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0

maximum9007199254740991

timezone?: string | null

calls_count: number

The number of call attempts made.

campaign: Campaign | null

id: string

created_at: unknown

The time the call order was created.

direction: "inbound" | "outbound"

Whether the call is inbound or outbound.

One of the following:

"inbound"

"outbound"

first_sentence_delay_ms: number

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

minimum-9007199254740991

maximum9007199254740991

from_phone_number: string

The phone number that made the call. Formatted in E.164 format. Example: +1234567890

is_cancelled: boolean

DEPRECATED: Whether the call has been cancelled. This is derived from status. Use status instead.

is_completed: boolean

DEPRECATED: Whether the call has completed. This is derived from status. Use status instead.

last_call_attempt: LastCallAttempt | null

This represent a single call attempt. A call attempt is a single call made to the phone number.

id: string

The ID of the call attempt.

answered_at: unknown

The time the call was answered.

dial_error: "number_non_attributed" | "too_many_calls" | "busy" | 5 more | null

The SIP error that occurred.

One of the following:

"number_non_attributed"

"too_many_calls"

"busy"

"temporarily_unavailable"

"no_answer"

"no_international_permission"

"precondition_failed"

"non_classified_error"

ended_at: unknown

The time the call ended.

phone_number: string

The phone number that was called. Formatted in E.164 format. Example: +1234567890

recording_url: string | null

The URL of the audio recording of the call.

result: "IVR" | "voicemail" | "human" | 2 more | null

One of the following:

"IVR"

"voicemail"

"human"

"unknown"

"ios-screening-filter"

started_at: unknown

The time the call started.

status: "queued" | "ringing" | "ongoing" | 2 more

The status of the call attempt.

One of the following:

"queued"

"ringing"

"ongoing"

"completed"

"error"

end_reason?: string | null

Reason for ending the call when ended_by is 'agent'. E.g. 'tool_end_call', 'voicemail', 'transfer', 'ivr_no_navigate'.

ended_by?: "agent" | "user" | "system" | null

Who ended the call: 'agent' (AI agent), 'user' (caller/callee hung up), or 'system' (e.g. max duration limit).

One of the following:

"agent"

"user"

"system"

structured_output?: Record<string, unknown> | null

The data extracted from the call, using the structured output config from the parent call object.

transcript?: Array<Transcript> | null

The transcript of the call.

content: string

role: "user" | "assistant" | "tool"

One of the following:

"user"

"assistant"

"tool"

tool_arguments?: Record<string, unknown> | string

One of the following:

Record<string, unknown>

string

tool_is_error?: boolean

tool_name?: string

llm_model: UnionMember0 { name, type } | UnionMember1 { openrouter_model_id, openrouter_provider, type }

One of the following:

UnionMember0 { name, type }

One of the following:

"gpt-4.1"

"ministral-3-8b-instruct"

type: "dedicated-instance"

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.

metadata: Record<string, string> | null

Metadata stored with the call.

organization_id: string

The ID of the organization that owns the call.

scheduled_at: unknown

The time the call order is scheduled to start.

status: "initializing" | "queued_for_calling" | "calling" | 4 more

The status of the call.

One of the following:

"initializing"

"queued_for_calling"

"calling"

"scheduled"

"completed"

"cancelled"

"errored"

to_phone_number: string

The phone number that received the call. Formatted in E.164 format. Example: +1234567890

Place a call

import Revox from '@revoxai/sdk';

const client = new Revox({
  apiKey: process.env['REVOX_API_KEY'], // This is the default and can be omitted
});

const call = await client.call.create({ phone_number: 'phone_number' });

console.log(call.call);

{
  "call": {
    "id": "id",
    "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
    },
    "call_attempts": [
      {
        "id": "id",
        "answered_at": {},
        "dial_error": "number_non_attributed",
        "ended_at": {},
        "phone_number": "phone_number",
        "recording_url": "recording_url",
        "result": "IVR",
        "started_at": {},
        "status": "queued",
        "end_reason": "end_reason",
        "ended_by": "agent",
        "structured_output": {
          "foo": "bar"
        },
        "transcript": [
          {
            "content": "content",
            "role": "user",
            "tool_arguments": {
              "foo": "bar"
            },
            "tool_is_error": true,
            "tool_name": "tool_name"
          }
        ]
      }
    ],
    "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"
    },
    "calls_count": 0,
    "campaign": {
      "id": "id",
      "name": "name"
    },
    "created_at": {},
    "direction": "inbound",
    "first_sentence_delay_ms": -9007199254740991,
    "from_phone_number": "from_phone_number",
    "is_cancelled": true,
    "is_completed": true,
    "last_call_attempt": {
      "id": "id",
      "answered_at": {},
      "dial_error": "number_non_attributed",
      "ended_at": {},
      "phone_number": "phone_number",
      "recording_url": "recording_url",
      "result": "IVR",
      "started_at": {},
      "status": "queued",
      "end_reason": "end_reason",
      "ended_by": "agent",
      "structured_output": {
        "foo": "bar"
      },
      "transcript": [
        {
          "content": "content",
          "role": "user",
          "tool_arguments": {
            "foo": "bar"
          },
          "tool_is_error": true,
          "tool_name": "tool_name"
        }
      ]
    },
    "llm_model": {
      "name": "gpt-4.1",
      "type": "dedicated-instance"
    },
    "metadata": {
      "foo": "string"
    },
    "organization_id": "organization_id",
    "scheduled_at": {},
    "status": "initializing",
    "to_phone_number": "to_phone_number"
  }
}

Returns Examples

{
  "call": {
    "id": "id",
    "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
    },
    "call_attempts": [
      {
        "id": "id",
        "answered_at": {},
        "dial_error": "number_non_attributed",
        "ended_at": {},
        "phone_number": "phone_number",
        "recording_url": "recording_url",
        "result": "IVR",
        "started_at": {},
        "status": "queued",
        "end_reason": "end_reason",
        "ended_by": "agent",
        "structured_output": {
          "foo": "bar"
        },
        "transcript": [
          {
            "content": "content",
            "role": "user",
            "tool_arguments": {
              "foo": "bar"
            },
            "tool_is_error": true,
            "tool_name": "tool_name"
          }
        ]
      }
    ],
    "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"
    },
    "calls_count": 0,
    "campaign": {
      "id": "id",
      "name": "name"
    },
    "created_at": {},
    "direction": "inbound",
    "first_sentence_delay_ms": -9007199254740991,
    "from_phone_number": "from_phone_number",
    "is_cancelled": true,
    "is_completed": true,
    "last_call_attempt": {
      "id": "id",
      "answered_at": {},
      "dial_error": "number_non_attributed",
      "ended_at": {},
      "phone_number": "phone_number",
      "recording_url": "recording_url",
      "result": "IVR",
      "started_at": {},
      "status": "queued",
      "end_reason": "end_reason",
      "ended_by": "agent",
      "structured_output": {
        "foo": "bar"
      },
      "transcript": [
        {
          "content": "content",
          "role": "user",
          "tool_arguments": {
            "foo": "bar"
          },
          "tool_is_error": true,
          "tool_name": "tool_name"
        }
      ]
    },
    "llm_model": {
      "name": "gpt-4.1",
      "type": "dedicated-instance"
    },
    "metadata": {
      "foo": "string"
    },
    "organization_id": "organization_id",
    "scheduled_at": {},
    "status": "initializing",
    "to_phone_number": "to_phone_number"
  }
}

Place a call

ParametersExpand Collapse

ReturnsExpand Collapse

Place a call

Returns Examples

What can I help you with?

Suggestions