Calls

Place a call

posthttps://www.getrevox.com/api/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.

Request body

phone_numberstringrequired
The phone number to call in the E.164 format. Example: +1234567890
skip_calling_windowboolean
Bypass the calling-window check for this call so it dials even outside the assistant's configured window. Use for immediate 'call now' dials.
timezonestringnullable
IANA timezone in which this call's calling windows and allowed days are evaluated, in place of the assistant's call_retry_config.timezone, for this call only. Examples: 'America/Los_Angeles', 'Europe/Paris'. Null: the callee's own timezone, derived from the country of phone_number. Omitted: the assistant's setting. Use it when you know where the callee is better than their country code does, e.g. a US number on Pacific time.
from_phone_numberstring
The phone number to use for making the call (e.g., +1234567890). If not provided, uses the default trunk.
call_twice_in_a_rowboolean
Double call for this call only, in place of the assistant's call_retry_config.call_twice_in_a_row. True: if the first attempt reaches nobody (no answer, declined, voicemail, call screening nobody took), the second attempt is dialed within seconds, from the same caller number. Each call is an attempt: the double call counts as 2 when both calls happen, so true raises a max_retry_attempts of 1 to 2. Omitted: the assistant's setting.
prompt_variablesmap of 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.
metadatamap of string
Metadata to store with the call.
assistant_idstring (uuid)
The ID of the assistant to use for this call.
assistantobject
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.
Show 48 fieldsHide 48 fields
- typeenum (string)
  Assistant kind. 'standalone' (default) is a normal assistant, 'multi-step' orchestrates a flow of sub-assistants, 'sub-assistant' is a step inside a multi-step flow (hidden from the assistants list). Flow transitions are managed via the /assistants/:id/edges endpoints, not on the assistant itself.
  One ofstandalonemulti-stepsub-assistant
- positionobjectnullable
  Canvas position of this assistant's node in its multi-step flow editor.
  Show 2 fieldsHide 2 fields
  xnumberrequired
  ynumberrequired
- start_step_namestringnullable
  Name of a multi-step flow's start step. Defaults to the assistant's name.
  max length 255
- promptstringrequired
  The prompt to use for the call. This will be given to the LLM (gpt-4.1)
- post_call_promptstringnullable
  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.
- first_sentencestring
  The first sentence to use for the call. This will be given to the LLM
- first_sentence_modeenum (string)
  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 ofgeneratedstaticnone
- end_of_call_sentencestring
  Optional message to say when the agent decides to end the call.
- voiceobject
  The voice to use for the call. You can get the list of voices using the /voices endpoint
  Show 5 fieldsHide 5 fields
  providerenum (string)required
  The provider of the voice.
  One ofcartesiaelevenlabsgradium
  idstringrequired
  The ID of the voice.
  min length 1
  speednumber
  The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.
  min 0.6 · max 1.5
  volumenumber
  Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.
  min 0.5 · max 2
  modelenum (string)
  Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.
  One ofsonic-3sonic-3.5sonic-3.6
- voice_languagesarray of objectnullable
  Extra languages for a multilingual assistant, each with its own voice (any provider). A call picks one with a language entry in its prompt_variables (a language code such as "es", or a name such as "Spanish"); otherwise the phone number's country picks one, and failing that the call runs in the language of voice, which cannot be listed here. A changed voice is applied to the calls in that language that have not completed yet; a language still used by such a call cannot be removed.
  Show 2 fieldsHide 2 fields
  languageenum (string)required
  The language contacts are called in with this voice.
  One ofenfresdeitptruzh
  voiceobjectrequired
  The voice used for contacts whose language is this language.
  Show 5 fieldsHide 5 fields
  providerenum (string)required
  The provider of the voice.
  One ofcartesiaelevenlabsgradium
  idstringrequired
  The ID of the voice.
  min length 1
  speednumber
  The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Gradium 0.6–1.5. Default is 1.0.
  min 0.6 · max 1.5
  volumenumber
  Volume of the voice (Cartesia only). 0.5–2.0, default 1.0. Ignored for other providers.
  min 0.5 · max 2
  modelenum (string)
  Cartesia TTS model (Cartesia only). Defaults to sonic-3.6 when omitted. Ignored for other providers.
  One ofsonic-3sonic-3.5sonic-3.6
- cartesia_dictionary_pronunciation_idstringnullable
  Optional Cartesia pronunciation dictionary ID to use for this assistant's calls. Set null to unlink it.
  min length 1
- llm_modelone of
  Show 3 variantsHide 3 variants
  One ofRecommendedobject
  typestring (constant)required
  The LLM Revox currently recommends for voice agents, chosen server-side and upgraded without any change on your side. No per-assistant configuration.
  Always "recommended"
  One ofGpt41Priorityobject
  typestring (constant)required
  OpenAI gpt-4.1 on the priority tier, with gpt-4.1-mini answering a turn when gpt-4.1 is slow to respond. No per-assistant configuration.
  Always "gpt-4.1-priority"
  One ofRealtimeobject
  typestring (constant)required
  Use a model from Realtime.
  Always "realtime"
  providerenum (string)required
  The provider to use from Realtime. eg: openai, google.
  One ofopenaigoogle
  realtime_model_idstringrequired
  The model ID to use from Realtime. eg: gpt-4.1
  realtime_voice_idstring
  Output voice for the realtime provider (e.g. OpenAI: marin; Gemini: Puck).
  min length 1
- webhook_urlstring
  The webhook URL to call when the call is completed.
- max_call_duration_secsnumber
  The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.
- max_duration_end_messagestringnullable
  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.
  max length 150
- structured_output_configarray of StructuredOutputField
  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.).
- structured_output_promptstringnullable
  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}}.
- call_retry_configCallRetryConfig
- background_soundenum (string)nullable
  Ambient background sound to play during the call. null/omitted disables it.
  One ofaudio/office.oggaudio/waves.m4a
- background_sound_volumenumber
  Volume of the ambient background sound (0 = silent, 1 = max).
  min 0 · max 1
- thinking_soundenum (string)nullable
  Audio clip to play while the agent is processing a response. One of the built-in LiveKit audio clips; null/omitted disables it.
  One ofcity-ambience.oggforest-ambience.oggoffice-ambience.oggcrowded-room.oggkeyboard-typing.oggkeyboard-typing2.ogghold_music.ogg
- thinking_sound_volumenumber
  Volume of the thinking sound (0 = silent, 1 = max).
  min 0 · max 1
- thinking_sound_probabilitynumber
  Probability [0..1] that the thinking sound plays on any given turn; otherwise the agent is silent while thinking.
  min 0 · max 1
- transfer_destinationsarray of objectnullable
  Where calls can be transferred to when users ask to speak to a human. With a single entry the assistant always transfers there; with several, it picks one at transfer time by applying the routing rules written in the assistant's own prompt (which refer to the destination labels). Empty or null disables transfer.
  Show 2 fieldsHide 2 fields
  labelstringrequired
  Human-meaningful name for this destination (e.g. "Sales"). The assistant's prompt refers to these labels when describing who to transfer to.
  min length 1 · max length 60
  phone_numberstringrequired
  Destination phone number in E.164 format (e.g. +1234567890).
- human_transfer_modeenum (string)nullable
  When transfer_destinations is non-empty: "warm" (AI bridges) or "cold" (SIP REFER; trunk must allow REFER/PSTN). Omit or null when transfer is disabled.
  One ofwarmcold
- warm_transfer_summary_instructionsstringnullable
  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.
- warm_transfer_voice_speednumbernullable
  When using warm transfer: voice speed used only while the AI briefs the human colleague. Same range as voice.speed. Omit or null to brief at the assistant's voice speed.
  min 0.6 · max 1.5
- ivr_navigation_enabledboolean
  Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.
- voicemail_messagestringnullable
  If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately. Left on the first attempt only (second dial of a double call). Takes the same {{variables}} as the prompt (e.g. "Hi {{first_name}}, this is Julie from Acme, please call us back.").
- stt_contextobjectnullable
  Assistant-level speech-to-text context: structured general key/value pairs plus a list of domain terms. Prompt-derived context is merged in without replacing existing entries.
  Show 2 fieldsHide 2 fields
  generalarray of objectrequired
  Default []
  Show 2 fieldsHide 2 fields
  keystringrequired
  min length 1
  valuestringrequired
  min length 1
  termsarray of stringrequired
  Default []
- stt_modelenum (string)
  Transcriber (speech-to-text) model. Defaults to the newest Soniox realtime model when omitted.
  One ofstt-rt-v4stt-rt-v5
- stt_endpoint_sensitivitynumbernullable
  Soniox endpoint sensitivity override (-1 to 1). Higher values finalize transcripts sooner. Null or omitted: the agent's default tuning.
  min -1 · max 1
- stt_endpoint_latency_levelintegernullable
  Soniox endpoint latency adjustment level override (0 to 3). Higher values reduce endpoint latency at a slight accuracy cost. Null or omitted: the agent's default tuning.
  min 0 · max 3
- stt_bvc_filter_enabledboolean
  When false, the agent transcribes the raw caller track instead of the BVC noise-cancellation output. Default true.
- krisp_viva_filter_enabledboolean
  When true, the agent's noise-cancellation filter is Krisp VIVA Tel instead of the legacy BVCTelephony. Default false.
- first_sentence_delay_msinteger
  Delay in milliseconds before speaking the first sentence. Default: 400.
  min 0 · max 9007199254740991
- calendlyobjectnullable
  Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in calendars. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  Show 2 fieldsHide 2 fields
  connection_idstringrequired
  The connection ID representing the link between your Calendly account and Revox.
  event_type_idstringrequired
  The Calendly event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)
  min length 1
- calobjectnullable
  Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in calendars. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  Show 2 fieldsHide 2 fields
  connection_idstringrequired
  The connection ID representing the link between your Cal.com account and Revox.
  event_type_idstringrequired
  The Cal.com event type to schedule. (eg: 7081322)
  min length 1
- google_calendarobjectnullable
  Deprecated: an assistant now books on any number of calendars, managed with the assistant calendars endpoints and listed in calendars. This field stands for the assistant's first ready calendar of this provider: setting it creates or updates that calendar, null removes it. The dashboard ignores it.
  Show 8 fieldsHide 8 fields
  calendar_idstringrequired
  The Google calendar to book on. (eg: primary)
  time_zonestringrequired
  The timezone of the opening hours. (eg: Europe/Paris)
  duration_minutesintegerrequired
  min 5 · max 480Default 30
  daysarray of integerrequired
  The open days, 0 is Sunday.
  Default [1,2,3,4,5]
  start_timestringrequired
  pattern ^\d{2}:\d{2}$Default "09:00"
  end_timestringrequired
  pattern ^\d{2}:\d{2}$Default "18:00"
  google_meetbooleanrequired
  Adds a Google Meet link to the meeting.
  Default true
  connection_idstringrequired
  The connection ID representing the link between your Google account and Revox.
- hubspotobjectnullable
  HubSpot Meetings config. When set with at least one meeting link, the agent can read a rep's real availability and book the meeting natively in HubSpot during the call.
  Show 4 fieldsHide 4 fields
  connection_idstringrequired
  The Nango connection ID linking the org's HubSpot account to Revox.
  precall_lookup_enabledbooleanrequired
  Resolve the caller against HubSpot contacts before answering an inbound call, filling the contact_* prompt variables (contact_name, contact_owner, contact_lead_status, contact_has_open_deal). Off by default: it costs API calls before the phone is picked up.
  Default false
  meeting_linksarray of objectrequired
  Scheduling pages the agent can book on during a call — typically one per sales rep plus a round-robin team page marked as the fallback.
  Default []
  Show 5 fieldsHide 5 fields
  slugstringrequired
  HubSpot scheduling page slug, as returned by the meeting-links API (e.g. 'julien-marchand').
  min length 1
  labelstringrequired
  Name the agent recognises for this calendar (e.g. 'Julien Marchand'). Listed in the prompt and matched against what the caller asks for.
  min length 1
  duration_msintegerrequired
  Meeting duration in milliseconds, chosen among the durations the scheduling page offers (e.g. 1800000 for 30 minutes).
  max 9007199254740991 · > 0
  is_fallbackbooleanrequired
  Marks the round-robin calendar the agent falls back to when the requested rep has no slot. At most one meeting link may set this.
  booking_urlstringrequirednullable
  Public URL of the scheduling page (e.g. https://meetings-eu1.hubspot.com/julien). The agent books through the API and only texts this link to the caller when the booking fails and the call can receive an SMS. Null on calendars saved before this field existed.
  Default null
  post_call_syncobject
  Sends call data back to HubSpot after the call. Off until set: connecting HubSpot to book meetings must not start writing to the CRM. Always present in responses; omit it on update to leave the current setting untouched.
  Show 2 fieldsHide 2 fields
  enabledbooleanrequired
  Records calls in HubSpot after they end: the contact is created or updated from the phone number and the call is logged on its timeline. By default every call a person answered is recorded. When the post-call prompt talks about the CRM (in plain words or by mentioning the crm_push_call tool), the post-call agent decides instead which calls are recorded and what the logged call says.
  Default false
  field_mappingarray of objectrequired
  Maps extracted call fields (structured_output / prompt variables) onto HubSpot contact properties.
  Default []
  Show 2 fieldsHide 2 fields
  sourcestringrequired
  Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.
  min length 1
  hubspot_propertystringrequired
  Destination HubSpot contact property, by internal name (e.g. 'email', 'company', or a custom 'budget').
  min length 1
- slackobjectnullable
  Slack notification config. When set, posts a message to the chosen channel after a call ends with one of the configured outcomes.
  Show 2 fieldsHide 2 fields
  connection_idstringrequired
  The Nango connection ID linking the org's Slack workspace to Revox.
  channelsarray of objectrequired
  The Slack channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
  Show 2 fieldsHide 2 fields
  idstringrequired
  The Slack channel ID (e.g. 'C01234567').
  namestringnullable
  Human-readable Slack channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
- teamsobjectnullable
  Microsoft Teams config. When set with at least one channel, the post-call agent can post to those channels when the post-call instructions ask for it.
  Show 2 fieldsHide 2 fields
  connection_idstringrequired
  The Nango connection ID linking a Microsoft Teams account to Revox. Messages are posted as that account.
  channelsarray of objectrequired
  The Teams channels the post-call agent may post to. It resolves the channel it was told to use against this list and cannot reach any other.
  Show 4 fieldsHide 4 fields
  idstringrequired
  The Microsoft Teams channel ID (e.g. '19:561fbdbb...@thread.tacv2').
  namestringnullable
  Human-readable channel name, cached for display in the UI and given to the LLM when the agent prompt routes by channel name.
  team_idstringrequired
  The ID of the team the channel belongs to. Needed to post.
  team_namestringnullable
  Human-readable team name. Channel names repeat across teams (every team has a 'General'), so the team name is what tells two of them apart.
- zohoobjectnullable
  Zoho CRM integration config. When set, upserts the prospect (keyed on phone) into the chosen module and attaches a Note with the call summary after a call ends with one of the configured outcomes.
  Show 5 fieldsHide 5 fields
  connection_idstringrequired
  The Nango connection ID linking the org's Zoho CRM account to Revox.
  modulestringrequired
  Zoho module the prospect record is upserted into (e.g. 'Leads' or 'Contacts').
  min length 1
  log_call_activitybooleanrequired
  When true, also log the call as a record in Zoho's Calls module (related to the upserted prospect via Who_Id).
  field_mappingarray of objectrequired
  Maps extracted call fields (structured_output / prompt variables) onto Zoho field API names on the upserted record.
  Show 2 fieldsHide 2 fields
  sourcestringrequired
  Source key to read from the call: a structured_output field name, falling back to a prompt variable of the same name.
  min length 1
  zoho_fieldstringrequired
  Destination Zoho field API name on the upserted record (e.g. 'Email', 'Company', or a custom 'Budget__c').
  min length 1
  templatestringnullable
  Optional Note body template. Supports {{summary}}, {{outcome}}, {{phone}}, {{call_url}}, {{assistant_name}}, {{campaign_name}}, {{transcript}}, plus prompt_variables and structured_output keys. When null/empty a default note (outcome + summary + auto-listed extracted fields) is used.
- custom_toolsarray of objectnullable
  Custom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution.
  Show 8 fieldsHide 8 fields
  namestringrequired
  Unique tool name in lowercase_snake_case (e.g. check_inventory)
  min length 1 · pattern ^[a-z][a-z0-9_]*$
  descriptionstringrequired
  Human-readable description of what the tool does, used by the LLM to decide when to call it
  min length 1
  methodenum (string)required
  HTTP method to use when calling the API endpoint
  One ofGETPOSTPUTPATCHDELETE
  urlstringrequired
  Full URL of the API endpoint. Supports {{variable}} placeholders for dynamic values
  min length 1
  headersarray of objectrequired
  HTTP headers to include in the request. Values support {{variable}} placeholders
  Default []
  Show 2 fieldsHide 2 fields
  keystringrequired
  min length 1
  valuestringrequired
  query_paramsarray of objectrequired
  Query string parameters appended to the URL. Values support {{variable}} placeholders
  Default []
  Show 2 fieldsHide 2 fields
  keystringrequired
  min length 1
  valuestringrequired
  body_templatestringrequirednullable
  JSON body template for the request. Use quoted {{variable}} placeholders (e.g. "{{name}}") for dynamic values
  Default null
  input_schemaarray of StructuredOutputFieldrequired
  Schema defining the parameters the LLM should extract from the conversation to pass to this tool
- from_phone_numberstringnullable
  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.
- logo_urlstring (uri)nullable
  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.
- precall_lookup_urlstringnullable
  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.
  max length 2000
- precall_lookup_headersarray of objectnullable
  HTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
  Show 2 fieldsHide 2 fields
  keystringrequired
  max length 200 · pattern ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$
  valuestringrequired
  min length 1 · max length 4000
concurrencyobject
Limit the number of concurrent calls for a given concurrency key. The limit itself is set server-side; omit this to leave the call ungrouped (bounded only by your organization's limit).
Show 1 fieldHide 1 field
- keystringrequired
  Groups this call with every other call sharing the same key, for concurrency purposes.
campaignobject
Group this call under a campaign, to follow its statistics in the dashboard. Nothing to create beforehand: the campaign exists as soon as a call names it, and it uses the assistant of that first call. Requires assistant_id, and cannot be combined with concurrency: the call follows the campaign's own concurrency limit, retry settings and pause. Returns 409 when the campaign was cancelled or uses another assistant. Calling the same number twice in a campaign counts as one contact.
Show 1 fieldHide 1 field
- namestringrequired
  The campaign's name, case-insensitive. Created on first use, reused by every later call that sends it.
  min length 1 · max length 255
scheduled_atone of
Schedule the call to start at a specific date and time (ISO 8601 format). If not provided, the call will start immediately.
Show 2 variantsHide 2 variants
1. One ofstringstring (date-time)
2. One ofOption 2any

Responses

200Success

callCallrequired

402Not enough credits on the organization

errorstringrequired
codestring (constant)required
Always "INSUFFICIENT_BALANCE"

409Conflict with the resource's current state

messagestring
errorstring
bodyErrorsobject
The validation errors returned from the API.
Show 1 fieldHide 1 field
- issuesarray of objectrequired
  Show 3 fieldsHide 3 fields
  patharray of one ofrequired
  Show 2 variantsHide 2 variants
  One ofstringstring
  One ofnumbernumber
  messagestringrequired
  codestring

Example request

cURL

curl -X POST https://www.getrevox.com/api/call \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33612345678"
  }'