Guide
MCP server
Revox runs an MCP server (Model Context Protocol) that exposes this API as tools. Connect Claude, ChatGPT, Cursor, Codex or any MCP client to it and ask in plain words: create an assistant, pick its voice, connect a calendar, place a test call.
Connect your client
https://www.getrevox.com/api/mcp-servers/generic/mcphttps://www.getrevox.com/api/mcp-servers/generic/mcpclaude mcp add --transport http revox https://www.getrevox.com/api/mcp-servers/generic/mcp{
"mcpServers": {
"revox": {
"url": "https://www.getrevox.com/api/mcp-servers/generic/mcp"
}
}
}{
"servers": {
"revox": {
"type": "http",
"url": "https://www.getrevox.com/api/mcp-servers/generic/mcp"
}
}
}codex mcp add revox --url https://www.getrevox.com/api/mcp-servers/generic/mcp
codex mcp login revoxhttps://www.getrevox.com/api/mcp-servers/generic/mcpIn Claude, open Settings › Connectors › Add custom connector (https://claude.ai/customize/connectors), paste this URL and sign in to Revox.
Authentication
- OAuth: clients that support it (Claude, ChatGPT, Cursor) open a Revox sign-in window the first time. Nothing to configure.
- API key: send
Authorization: Bearer YOUR_API_KEY, the same key as the REST API. - If you belong to several organizations, use the organization's own URL, shown in the dashboard on the MCP page.
How the tools work together
The server sends these instructions to the client when it connects:
Revox places AI phone calls and manages the voice assistants that make them.
Before writing or changing an assistant's prompt (revox_create_assistant, or revox_update_assistant with prompt or first_sentence), call revox_get_prompt_guide and follow it: it is Revox's prompt-creation guide for phone conversations (identity and opener, turns, qualification, objections, actions, end of call). Pass its guide_version as prompt_guide_version: those tools refuse a prompt without it.
After your last change to an assistant, call revox_check_assistant_setup and fix what it reports before handing the assistant over.
To place a call, use revox_make_call, then revox_wait_for_call to get the outcome, transcript and extracted data.
You cannot play audio: to choose a voice, call revox_pick_voice and give the user its url, then revox_wait_for_voice_pick. After creating or updating an assistant, give the user its test_url to try it live in the browser.
You cannot sign in to a calendar account: to add a calendar, call revox_connect_calendar and give the user its url, then revox_wait_for_calendar. revox_list_assistant_tools lists what an assistant's prompts can mention as @name, including its calendars.
Tools (33)
- revox_auth_status
- revox_create_api_key
- revox_get_call
- revox_wait_for_call
- revox_make_call
- revox_get_calls
- revox_get_live_call_link
- revox_list_assistants
- revox_get_assistant
- revox_get_prompt_guide
- revox_create_assistant
- revox_update_assistant
- revox_check_assistant_setup
- revox_set_demo_page
- revox_list_voices
- revox_get_voice
- revox_pick_voice
- revox_wait_for_voice_pick
- revox_list_assistant_tools
- revox_list_calendars
- revox_connect_calendar
- revox_wait_for_calendar
- revox_get_calendar_options
- revox_select_calendar_option
- revox_update_calendar_settings
- revox_disconnect_calendar
- revox_remove_calendar
- revox_list_pronunciations
- revox_remove_pronunciation
- revox_get_current_user
- revox_list_campaigns
- revox_get_balance
- revox_get_usage
Calls
revox_get_callread onlyGet a call by ID.
MoreLess
Use this to poll for completion after revox_make_call (MCP has no webhooks).
Arguments (1)
idstringrequiredCall ID
revox_wait_for_callread onlyPoll a call until it completes, is cancelled, or the server time window expires (~240 s).
MoreLess
If the result contains
_retry: true, call this tool again with the same id to keep waiting.Arguments (2)
idstringrequiredCall ID (from revox_make_call response)
poll_interval_secsnumberSeconds between each status fetch (default 5)
Default
51 to 60
revox_make_callwritesPlace a call.
MoreLess
Returns immediately with call id. Provide either assistant_id or prompt (not both). With assistant_id, personalize the call with prompt_variables (the assistant's {{variables}}); the assistant's own config is used and the inline fields (prompt, voice, first sentence, structured output, webhook, custom tools...) are ignored. With prompt, the inline fields configure this one call. Voice is optional: if voice_provider/voice_id are omitted, a voice is auto-selected based on the target phone number's country (e.g. a French number gets a French voice). Use metadata to attach your own ids, from_phone_number to choose the caller ID, scheduled_at to call later. Use call_retry_config to change this call's number of attempts or to skip dates such as public holidays (excluded_dates, with skip_calling_window false). To know when the call is done, use revox_wait_for_call or poll revox_get_call manually: the result carries the outcome, summary, transcript, extracted structured_output and the tools the agent ran.
Arguments (28)
phone_numberstringrequiredE.164 phone number (e.g. +1234567890)
prompt_variablesobject<string, string>Values of the assistant's {{variables}} for this call, keyed by variable name, whether the call uses assistant_id or an inline assistant. Send every variable the prompt and first sentence use. A missing or empty one is not rejected: the prompt reads '(name: not provided)' in its place, and a static first sentence leaves it out.
Keys: Variable name, as written between the braces: name for {{name}}.
metadataobject<string, string>Your own key/value pairs to store with the call, e.g. your CRM ID. They come back as sent on the call.
Keys: A key of your choice.
from_phone_numberstringCaller ID of the call, in E.164 format: one of your organization's numbers (GET /phone-numbers). Omitted: the assistant's from_phone_number, or else a Revox number chosen for the destination.
scheduled_atstring (date-time)Start the call at this date and time (ISO 8601, e.g. 2026-11-03T10:00:00+01:00) instead of now.
concurrencyobjectLimit 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).
skip_calling_windowbooleanDial even outside the assistant's calling window (default true): the first dial ignores calling windows, allowed days and excluded dates. Set false to respect them (required for call_retry_config.excluded_dates to hold the first dial): the call then waits for the next open window.
Default
truetimezonestringnullableIANA timezone of this call, in place of its campaign's or assistant's timezone. Examples: 'America/Los_Angeles', 'Europe/Paris'. The call runs in exactly this one timezone: its calling windows and allowed days are read in it, the agent tells the date and offers calendar slots in it, and callbacks and extracted datetimes are interpreted in it. Omitted or null: the campaign's timezone, else the assistant's. It is never derived from the phone number.
call_retry_configany JSON valueassistant_idstringID of an existing assistant to use. When provided, prompt/voice_provider/voice_id are ignored.
promptstringCustom prompt for the call. Required when assistant_id is not provided.
voice_providerstringOptional voice provider override (e.g. cartesia). Ignored when assistant_id is provided. If omitted, auto-selected from phone number country.
voice_idstringOptional voice ID override. Ignored when assistant_id is provided. If omitted, auto-selected from phone number country.
voice_volumenumberVoice volume for Cartesia only (0.5–2.0, default 1.0). Ignored when assistant_id or non-Cartesia provider.
0.5 to 2
first_sentencestringThe agent's opening line, spoken word for word. Only used, and only kept, with first_sentence_mode 'static': with 'generated' or 'none' it is dropped and reads back empty. May contain {{variable}} placeholders; one without a value is left out.
first_sentence_mode"generated" | "static" | "none"How the agent opens the call. Default at creation: 'generated'.
"generated"The agent opens with a greeting it writes from the prompt. first_sentence is not used, and not kept.
"static"The agent opens with first_sentence, word for word.
"none"The agent says nothing first and waits for the other person to speak.
end_of_call_sentencestringSentence the agent says, without being interruptible, when it decides to end the call. Null or empty: the agent says a short default goodbye, only if it has not said goodbye already.
voicemail_messagestringnullableIf 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.").
max_call_duration_secsnumberLongest a call may last, in seconds: the agent then says max_duration_end_message, if set, and hangs up. Default at creation: 300. Outbound calls are capped at 600.
structured_output_configarray of any JSON valueThe values to extract from each call (e.g. an email, a budget, a date). They land in structured_output of each call attempt, keyed by name.
structured_output_promptstringnullableCustom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
webhook_urlstringURL that receives a POST with the call and this assistant once the call is over, when it reaches completed or errored (not when it is cancelled). See Webhooks for the payload.
custom_toolsarray of objectnullableCustom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution. Null or empty when the assistant has none.
post_call_promptstringnullablePost-call instructions: what a separate AI agent does once the call has ended (answered or not: voicemails and unanswered calls get it too). It reads the call (transcript, outcome, summary, structured_output, prompt variables, what was done during the call) and acts with the tools below. Empty or null: nothing runs after the call. How to write them: - Plain language, in the language you want, one step per line, each as a condition then an action: "If the prospect asked to be called back, ...". A call that meets no condition gets nothing, which is the expected result. - Name each action by its tool, as @tool_name: the agent can only act through these tools, never by itself. - To send an exact text, put it in quotes: it is sent word for word. Otherwise the agent writes the message itself, in the language of the call, from facts of the call only. - {{variables}} are filled in before the agent reads them: the call's prompt variables, each structured_output field by its name, and {{outcome}}, {{outcome_summary}}. - Pick the email tool by who reads it: @send_email writes to the person who was on the call (their address on file or one they gave), with only the text you ask for; @notify_team_by_email writes to your own team, at the address you name, with the call report and a link to the call. Say which address each team email goes to, and which channel each Slack or Teams message goes to. Texts always go to the person on the call. - Actions already taken during the call (an SMS sent by @send_sms from the call prompt, a booking, a transfer) are never repeated. Tools: - @send_email (always available; at most 3 per call): Emails the person who was on the call (the prospect, the customer), like @send_sms texts them. The address is the contact's email on file, or one the person gave during the call; it never goes anywhere else. The email carries only the subject and the text the instructions ask for: no call report, no link to the dashboard. The instructions can name the sender and a reply-to address. Can carry a calendar invite for the callback time the call produced. To tell your own team about the call, use @notify_team_by_email. Example: If the prospect asked for the brochure, send them an email with @send_email, subject "Votre brochure", with the link https://example.com/brochure. - @notify_team_by_email (always available; at most 5 per call): Emails your own team about the call, at any address the instructions name, which can depend on the call (billing@ for a billing question, shipping@ for a delivery). By default the subject is "{outcome}: {contact}" and the email includes the contact, the call outcome, the extracted data, the summary and a "View the call" link to the dashboard. The instructions can give another subject and leave sections or the link out. Can carry a calendar invite for the callback time the call produced. Never for the person who was on the call: that is @send_email. Example: If a meeting was booked, notify sales@company.com with @notify_team_by_email with the prospect's name, number and the agreed date. - @send_sms (always available; at most 3 per call): Texts the person on the call (the callee outbound, the caller inbound), under 300 characters, in the language of the call. Not available on web test calls (no phone number). Also usable during the call, from the call prompt. Example: If nobody answered, send an SMS with @send_sms: "Bonjour, ici Julie de Revox, je vous rappelle demain matin." - @post_slack_message (requires a Slack workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Slack channels connected to the assistant (named in the instructions, e.g. #sales). Revox adds the assistant's name and a link to the call. Example: Post the call outcome and summary in #sales with @post_slack_message. - @post_teams_message (requires a Microsoft Teams workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Microsoft Teams channels connected to the assistant, named "Team / Channel". Revox adds the assistant's name and a link to the call. Example: When the prospect is interested, post a short summary in Sales / Leads with @post_teams_message. - @crm_push_call (requires Zoho CRM connected, or HubSpot connected with post-call sync on, in the assistant's Integrations tab of the dashboard; without it the tool is not offered; at most 1 per call): Records the call in the connected CRM (Zoho, or HubSpot with post-call sync on): the contact is created or updated from their number and the call attached with its outcome, summary, extracted data and recording. The instructions can add a note. With HubSpot sync on, it also runs by itself after every call someone answered, unless the instructions mention the CRM (then they decide). Example: After every answered call, @crm_push_call with a two-sentence note: the prospect's need, then the next step.
transfer_destinationsarray of objectnullableWhere 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.
at most 10 items
human_transfer_mode"warm" | "cold"nullableHow calls are transferred to transfer_destinations. Default: 'warm'. Ignored without transfer destinations.
"warm"The agent calls the destination first, briefs the person who answers on the call so far (see warm_transfer_summary_instructions), then puts the caller through.
"cold"The call is passed on at once, without a briefing (a SIP REFER: the phone carrier must allow it).
warm_transfer_summary_instructionsstringnullableWhen 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_speednumbernullableWhen 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.
0.6 to 1.5
revox_get_callsread onlySearch/list calls
Arguments (16)
querystringFree-text search. A call matches when it contains every word of the query (3 characters or more, in any order) in its phone numbers, contact identity, metadata or prompt variable values, or in the extracted data of its last attempt. A phone number typed with spaces or a leading 0 is matched on its digits.
statusesarray of enum (10 values)Keep calls in any of these statuses. A scheduled call of a paused campaign counts as 'paused'.
"initializing"Being created, not scheduled yet. Newer calls start as scheduled instead.
"queued_for_calling"Its turn came: the attempt is about to dial, within your concurrent call limit.
"calling"An attempt is in progress: the phone is ringing or a conversation is going on.
"post_processing"The phone conversation is over; the transcript, outcome and extracted data are being computed. It can no longer be paused or cancelled.
"not_launched"Created but never sent: a campaign call waiting for POST /campaigns/{id}/launch-calls. It is not dialed until then.
"scheduled"Waiting to be dialed at scheduled_at (the first attempt, a retry or a requested callback). A call due outside its calling windows waits for the next one.
"paused"No new attempt is made until it is resumed (POST /call/{id}/resume, or resuming its campaign).
"completed"Final. Revox will not dial it again: a person or a phone menu answered, or the last attempt allowed by call_retry_config was made. outcome and last_call_attempt tell how it went.
"cancelled"Final. Cancelled before it completed: by a user (POST /call/{id}/cancel, the dashboard, a campaign cancel), or because the prospect called back (see cancel_reason).
"errored"Final. The call could not be placed and will not be retried: the number does not exist, the destination cannot be called, the organization ran out of credits, or an internal error stopped it.
Default
[]directionsarray of ("inbound" | "outbound")Keep calls in any of these directions.
"inbound"Someone called one of your numbers and an assistant answered.
"outbound"Revox called the number: from POST /call, a campaign or the dashboard.
Default
[]resultsarray of enum (6 values)Keep calls whose last attempt has one of these results (who answered: human, voicemail, IVR...). 'none' matches calls whose last attempt has no result yet, or no attempt at all.
"IVR"An automated phone menu answered (e.g. 'press 1 for sales').
"voicemail"A voicemail or an answering machine answered.
"human"A person answered.
"unknown"Silence, or audio that could not be classified.
"screening-filter"A call screening assistant (Apple or Google) answered for the person and asked who is calling and why.
"none"The last attempt has no result yet, or there is no attempt.
Default
[]outcomesarray of enum (6 values)Keep calls with one of these business outcomes. 'none' matches calls without an outcome, 'do_not_call' calls whose number is on the do-not-call list (those match no other outcome value).
"not_interested"The person declined, refused or showed no interest.
"interested"The person engaged and is a lead to follow up: the strongest outcome the AI assigns.
"completed"A person from your team talked to the prospect: they joined the call, the call was transferred to them, or they set this outcome by hand. Never assigned by the AI.
"requested_callback_later"The person asked to be called back later. When they gave a time and attempts are left, the call is scheduled again for that time.
"none"The call has no outcome.
"do_not_call"The number is on the do-not-call list. Such a call matches no other outcome value.
Default
[]assistant_idsarray of stringKeep calls placed with one of these assistants. A step of a multi-step flow matches the calls that went through it. 'none' matches calls whose assistant was deleted.
Default
[]campaign_idsarray of stringKeep calls of one of these campaigns. With this filter, a call superseded by the prospect calling back is left out, so each contact is listed once.
Default
[]from_phone_numbersarray of stringKeep calls whose from_phone_number is one of these numbers (your number for an outbound call, the caller's for an inbound one), in E.164 format, exact match.
Default
[]assignee_idsarray of (string | "none")Keep calls assigned to one of these team members (user IDs, see the call's assignee.id). 'none' matches unassigned calls.
string"none"Unassigned calls.
Default
[]variablesarray of objectKeep calls whose metadata (or, when the metadata has no such key, prompt variables) hold all these values.
to_phone_numberstringKeep calls whose to_phone_number is this number (the person called for an outbound call, your number for an inbound one), in E.164 format, exact match. Ignored by POST /call/export.
call_idsarray of stringKeep only the calls with these IDs. Ignored by POST /call/export.
pageintegerPage number, starting at 1. Default: 1.
Default
1≥ 1page_sizeintegerNumber of calls per page, 1 to 100. Default: 50.
Default
501 to 100sort_bystringSort order. 'updated_at' (the default): most recent activity. 'duration': talk time of the last attempt, calls without one last. 'priority': a fixed order for working a campaign (live calls, then calls a person from your team joined, hot leads, calls a person answered, queued, scheduled, the rest), which ignores sort_direction. 'structured_output.<field>': a value extracted from the last attempt.
sort_direction"asc" | "desc"'asc' or 'desc' (the default).
Assistants
revox_list_assistantsread onlyGet all assistants for the organization.
MoreLess
Each comes with its dashboard_url and test_url (opens the page with the web test call ready).
revox_get_assistantread onlyGet an assistant by ID, with its dashboard_url and test_url (opens the page with the web test call ready).
Arguments (1)
idstringrequired
revox_get_prompt_guideread onlyRevox's prompt-creation guide (in French): the rules for an assistant's prompt on a phone call (identity and opener, personalization with variables, turns, qualification, objections, transfers and bookings, end of call) and the checks before delivering it.
MoreLess
You MUST call this before revox_create_assistant, and before revox_update_assistant changes prompt or first_sentence, then write the prompt following it. It returns a guide_version to pass as prompt_guide_version. Pass the paths matching the case to also get their examples.
Arguments (1)
pathsarray of enum (10 values)The guide's « parcours et exemples » that match the case (cold call, lead follow-up, inbound reception, switchboard, objections...). Omit when none applies.
Possible values
"Réception entrante""Appel à froid sans relation préalable""Branche standard et réception en outbound B2B""Relance d'un lead ou d'une étude existante""Appel à une personne qui connaît la marque""Rappel après inscription ou onboarding""Rappel après demande de séjour, devis ou réservation""Qualification : rendre l'enchaînement naturel""Proposer une suite cohérente""Objection, préférence et arrêt"
revox_create_assistantwritesCreate a new assistant.
MoreLess
You MUST call revox_get_prompt_guide first and write the prompt following it; pass its guide_version as prompt_guide_version. Set voice_provider and voice_id for a specific accent (e.g. French): let the user choose by ear with revox_pick_voice, or use revox_list_voices and pick a voice whose language matches your prompt. custom_tools are HTTP endpoints the agent can call during the conversation; webhook_url receives each call's report when it ends; precall_lookup_url (inbound calls) is queried before answering to fill the prompt variables. To transfer calls to a human, set transfer_destinations (label + E.164 number each) and human_transfer_mode (warm: the AI briefs the colleague before connecting, the default; cold: direct SIP transfer); the prompt must say when to transfer and, with several destinations, which label to pick. post_call_prompt sets what happens once the call has ended (emails, SMS, Slack or Teams messages, CRM): read its description for how to write it and which tools exist. To text the person during the call instead, write in the prompt when to use @send_sms (only works when the number can receive SMS). For the assistant to book meetings, add its calendars with revox_connect_calendar. revox_list_assistant_tools lists everything its prompts can mention as @name, including those calendars. The result carries the assistant's dashboard_url and test_url: give the user test_url so they can talk to the assistant right away in their browser (web test call).
Arguments (25)
namestringrequiredpromptstringrequiredSystem prompt given to the LLM for the whole call: who the agent is, its goal and how to run the conversation. May contain {{variable}} placeholders, filled from the call's prompt_variables.
prompt_guide_versionstringRequired. The guide_version returned by revox_get_prompt_guide. Call that tool and write the prompt following its guide before calling this one.
timezonestringIANA timezone of this assistant's calls, e.g. 'Europe/Paris' or 'America/Phoenix'. Every call runs in exactly one timezone: its calling windows and allowed days are read in it, the agent tells the date and offers calendar slots in it, and callbacks and extracted datetimes are interpreted in it. A campaign's
timezone, then POST /calltimezone, override it for their calls. Default when creating: 'Europe/Paris'. Replaces the deprecatedcall_retry_config.timezone.first_sentencestringThe agent's opening line, spoken word for word. Only used, and only kept, with first_sentence_mode 'static': with 'generated' or 'none' it is dropped and reads back empty. May contain {{variable}} placeholders; one without a value is left out.
first_sentence_mode"generated" | "static" | "none"How the agent opens the call. Default at creation: 'generated'.
"generated"The agent opens with a greeting it writes from the prompt. first_sentence is not used, and not kept.
"static"The agent opens with first_sentence, word for word.
"none"The agent says nothing first and waits for the other person to speak.
end_of_call_sentencestringSentence the agent says, without being interruptible, when it decides to end the call. Null or empty: the agent says a short default goodbye, only if it has not said goodbye already.
voicemail_messagestringnullableIf 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.").
max_call_duration_secsnumberLongest a call may last, in seconds: the agent then says max_duration_end_message, if set, and hangs up. Default at creation: 300. Outbound calls are capped at 600.
structured_output_configarray of any JSON valueThe values to extract from each call (e.g. an email, a budget, a date). They land in structured_output of each call attempt, keyed by name.
structured_output_promptstringnullableCustom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
webhook_urlstringURL that receives a POST with the call and this assistant once the call is over, when it reaches completed or errored (not when it is cancelled). See Webhooks for the payload.
custom_toolsarray of objectnullableCustom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution. Null or empty when the assistant has none.
post_call_promptstringnullablePost-call instructions: what a separate AI agent does once the call has ended (answered or not: voicemails and unanswered calls get it too). It reads the call (transcript, outcome, summary, structured_output, prompt variables, what was done during the call) and acts with the tools below. Empty or null: nothing runs after the call. How to write them: - Plain language, in the language you want, one step per line, each as a condition then an action: "If the prospect asked to be called back, ...". A call that meets no condition gets nothing, which is the expected result. - Name each action by its tool, as @tool_name: the agent can only act through these tools, never by itself. - To send an exact text, put it in quotes: it is sent word for word. Otherwise the agent writes the message itself, in the language of the call, from facts of the call only. - {{variables}} are filled in before the agent reads them: the call's prompt variables, each structured_output field by its name, and {{outcome}}, {{outcome_summary}}. - Pick the email tool by who reads it: @send_email writes to the person who was on the call (their address on file or one they gave), with only the text you ask for; @notify_team_by_email writes to your own team, at the address you name, with the call report and a link to the call. Say which address each team email goes to, and which channel each Slack or Teams message goes to. Texts always go to the person on the call. - Actions already taken during the call (an SMS sent by @send_sms from the call prompt, a booking, a transfer) are never repeated. Tools: - @send_email (always available; at most 3 per call): Emails the person who was on the call (the prospect, the customer), like @send_sms texts them. The address is the contact's email on file, or one the person gave during the call; it never goes anywhere else. The email carries only the subject and the text the instructions ask for: no call report, no link to the dashboard. The instructions can name the sender and a reply-to address. Can carry a calendar invite for the callback time the call produced. To tell your own team about the call, use @notify_team_by_email. Example: If the prospect asked for the brochure, send them an email with @send_email, subject "Votre brochure", with the link https://example.com/brochure. - @notify_team_by_email (always available; at most 5 per call): Emails your own team about the call, at any address the instructions name, which can depend on the call (billing@ for a billing question, shipping@ for a delivery). By default the subject is "{outcome}: {contact}" and the email includes the contact, the call outcome, the extracted data, the summary and a "View the call" link to the dashboard. The instructions can give another subject and leave sections or the link out. Can carry a calendar invite for the callback time the call produced. Never for the person who was on the call: that is @send_email. Example: If a meeting was booked, notify sales@company.com with @notify_team_by_email with the prospect's name, number and the agreed date. - @send_sms (always available; at most 3 per call): Texts the person on the call (the callee outbound, the caller inbound), under 300 characters, in the language of the call. Not available on web test calls (no phone number). Also usable during the call, from the call prompt. Example: If nobody answered, send an SMS with @send_sms: "Bonjour, ici Julie de Revox, je vous rappelle demain matin." - @post_slack_message (requires a Slack workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Slack channels connected to the assistant (named in the instructions, e.g. #sales). Revox adds the assistant's name and a link to the call. Example: Post the call outcome and summary in #sales with @post_slack_message. - @post_teams_message (requires a Microsoft Teams workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Microsoft Teams channels connected to the assistant, named "Team / Channel". Revox adds the assistant's name and a link to the call. Example: When the prospect is interested, post a short summary in Sales / Leads with @post_teams_message. - @crm_push_call (requires Zoho CRM connected, or HubSpot connected with post-call sync on, in the assistant's Integrations tab of the dashboard; without it the tool is not offered; at most 1 per call): Records the call in the connected CRM (Zoho, or HubSpot with post-call sync on): the contact is created or updated from their number and the call attached with its outcome, summary, extracted data and recording. The instructions can add a note. With HubSpot sync on, it also runs by itself after every call someone answered, unless the instructions mention the CRM (then they decide). Example: After every answered call, @crm_push_call with a two-sentence note: the prospect's need, then the next step.
transfer_destinationsarray of objectnullableWhere 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.
at most 10 items
human_transfer_mode"warm" | "cold"nullableHow calls are transferred to transfer_destinations. Default: 'warm'. Ignored without transfer destinations.
"warm"The agent calls the destination first, briefs the person who answers on the call so far (see warm_transfer_summary_instructions), then puts the caller through.
"cold"The call is passed on at once, without a briefing (a SIP REFER: the phone carrier must allow it).
warm_transfer_summary_instructionsstringnullableWhen 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_speednumbernullableWhen 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.
0.6 to 1.5
precall_lookup_urlstringnullableInbound 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.at most 2000 characters
precall_lookup_headersarray of objectnullableHTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
at most 10 items
voice_provider"cartesia" | "elevenlabs" | "gradium"Voice provider. Use with voice_id. To let the user choose by ear, use revox_pick_voice; otherwise revox_list_voices (pick a voice whose language matches the prompt).
voice_idstringVoice ID. Use with voice_provider. For French, use revox_list_voices and pick a voice with language 'fr', or Cartesia id a249eaff-1e96-4d2c-b23b-12efa4f66f41.
voice_speednumberVoice speed (default 1.0).
0.6 to 1.5
voice_volumenumberVoice volume for Cartesia only (0.5–2.0, default 1.0). Ignored for other providers.
0.5 to 2
voice_model"sonic-3" | "sonic-3.5" | "sonic-3.6"Cartesia TTS model (Cartesia only, default sonic-3.6). Ignored for other providers.
revox_update_assistantwritesUpdate an assistant by ID.
MoreLess
Only the fields you pass change. To change prompt or first_sentence, you MUST call revox_get_prompt_guide first, rework the text following it, and pass its guide_version as prompt_guide_version. Include voice_provider and voice_id to change the voice (e.g. to a French accent). custom_tools replaces the whole list (null removes them all); precall_lookup_url and precall_lookup_headers take null to remove the inbound lookup. To transfer calls to a human, set transfer_destinations (label + E.164 number each) and human_transfer_mode (warm: the AI briefs the colleague before connecting, the default; cold: direct SIP transfer); the prompt must say when to transfer and, with several destinations, which label to pick. transfer_destinations: null removes the transfer. post_call_prompt sets what happens once the call has ended (emails, SMS, Slack or Teams messages, CRM): read its description for how to write it and which tools exist. To text the person during the call instead, write in the prompt when to use @send_sms (only works when the number can receive SMS). For the assistant to book meetings, add its calendars with revox_connect_calendar. revox_list_assistant_tools lists everything its prompts can mention as @name, including those calendars. The result carries the assistant's dashboard_url and test_url: give the user test_url so they can talk to the assistant right away in their browser (web test call).
Arguments (26)
idstringrequiredprompt_guide_versionstringThe guide_version returned by revox_get_prompt_guide. Required when prompt or first_sentence is passed.
namestringpromptstringSystem prompt given to the LLM for the whole call: who the agent is, its goal and how to run the conversation. May contain {{variable}} placeholders, filled from the call's prompt_variables.
timezonestringIANA timezone of this assistant's calls, e.g. 'Europe/Paris' or 'America/Phoenix'. Every call runs in exactly one timezone: its calling windows and allowed days are read in it, the agent tells the date and offers calendar slots in it, and callbacks and extracted datetimes are interpreted in it. A campaign's
timezone, then POST /calltimezone, override it for their calls. Default when creating: 'Europe/Paris'. Replaces the deprecatedcall_retry_config.timezone.first_sentencestringThe agent's opening line, spoken word for word. Only used, and only kept, with first_sentence_mode 'static': with 'generated' or 'none' it is dropped and reads back empty. May contain {{variable}} placeholders; one without a value is left out.
first_sentence_mode"generated" | "static" | "none"How the agent opens the call. Default at creation: 'generated'.
"generated"The agent opens with a greeting it writes from the prompt. first_sentence is not used, and not kept.
"static"The agent opens with first_sentence, word for word.
"none"The agent says nothing first and waits for the other person to speak.
end_of_call_sentencestringSentence the agent says, without being interruptible, when it decides to end the call. Null or empty: the agent says a short default goodbye, only if it has not said goodbye already.
voicemail_messagestringnullableIf 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.").
max_call_duration_secsnumberLongest a call may last, in seconds: the agent then says max_duration_end_message, if set, and hangs up. Default at creation: 300. Outbound calls are capped at 600.
structured_output_configarray of any JSON valueThe values to extract from each call (e.g. an email, a budget, a date). They land in structured_output of each call attempt, keyed by name.
structured_output_promptstringnullableCustom prompt for structured data extraction. If not provided, a default prompt is used. Available variables: {{transcript}}, {{call_direction}}, {{user_phone_number}}, {{agent_phone_number}}.
webhook_urlstringURL that receives a POST with the call and this assistant once the call is over, when it reaches completed or errored (not when it is cancelled). See Webhooks for the payload.
custom_toolsarray of objectnullableCustom API tools the assistant can call during conversations. Each tool defines an HTTP endpoint with variable substitution. Null or empty when the assistant has none.
post_call_promptstringnullablePost-call instructions: what a separate AI agent does once the call has ended (answered or not: voicemails and unanswered calls get it too). It reads the call (transcript, outcome, summary, structured_output, prompt variables, what was done during the call) and acts with the tools below. Empty or null: nothing runs after the call. How to write them: - Plain language, in the language you want, one step per line, each as a condition then an action: "If the prospect asked to be called back, ...". A call that meets no condition gets nothing, which is the expected result. - Name each action by its tool, as @tool_name: the agent can only act through these tools, never by itself. - To send an exact text, put it in quotes: it is sent word for word. Otherwise the agent writes the message itself, in the language of the call, from facts of the call only. - {{variables}} are filled in before the agent reads them: the call's prompt variables, each structured_output field by its name, and {{outcome}}, {{outcome_summary}}. - Pick the email tool by who reads it: @send_email writes to the person who was on the call (their address on file or one they gave), with only the text you ask for; @notify_team_by_email writes to your own team, at the address you name, with the call report and a link to the call. Say which address each team email goes to, and which channel each Slack or Teams message goes to. Texts always go to the person on the call. - Actions already taken during the call (an SMS sent by @send_sms from the call prompt, a booking, a transfer) are never repeated. Tools: - @send_email (always available; at most 3 per call): Emails the person who was on the call (the prospect, the customer), like @send_sms texts them. The address is the contact's email on file, or one the person gave during the call; it never goes anywhere else. The email carries only the subject and the text the instructions ask for: no call report, no link to the dashboard. The instructions can name the sender and a reply-to address. Can carry a calendar invite for the callback time the call produced. To tell your own team about the call, use @notify_team_by_email. Example: If the prospect asked for the brochure, send them an email with @send_email, subject "Votre brochure", with the link https://example.com/brochure. - @notify_team_by_email (always available; at most 5 per call): Emails your own team about the call, at any address the instructions name, which can depend on the call (billing@ for a billing question, shipping@ for a delivery). By default the subject is "{outcome}: {contact}" and the email includes the contact, the call outcome, the extracted data, the summary and a "View the call" link to the dashboard. The instructions can give another subject and leave sections or the link out. Can carry a calendar invite for the callback time the call produced. Never for the person who was on the call: that is @send_email. Example: If a meeting was booked, notify sales@company.com with @notify_team_by_email with the prospect's name, number and the agreed date. - @send_sms (always available; at most 3 per call): Texts the person on the call (the callee outbound, the caller inbound), under 300 characters, in the language of the call. Not available on web test calls (no phone number). Also usable during the call, from the call prompt. Example: If nobody answered, send an SMS with @send_sms: "Bonjour, ici Julie de Revox, je vous rappelle demain matin." - @post_slack_message (requires a Slack workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Slack channels connected to the assistant (named in the instructions, e.g. #sales). Revox adds the assistant's name and a link to the call. Example: Post the call outcome and summary in #sales with @post_slack_message. - @post_teams_message (requires a Microsoft Teams workspace connected, with channels chosen, in the assistant's Team alerts tab of the dashboard; without it the tool is not offered; at most 5 per call): Posts in one of the Microsoft Teams channels connected to the assistant, named "Team / Channel". Revox adds the assistant's name and a link to the call. Example: When the prospect is interested, post a short summary in Sales / Leads with @post_teams_message. - @crm_push_call (requires Zoho CRM connected, or HubSpot connected with post-call sync on, in the assistant's Integrations tab of the dashboard; without it the tool is not offered; at most 1 per call): Records the call in the connected CRM (Zoho, or HubSpot with post-call sync on): the contact is created or updated from their number and the call attached with its outcome, summary, extracted data and recording. The instructions can add a note. With HubSpot sync on, it also runs by itself after every call someone answered, unless the instructions mention the CRM (then they decide). Example: After every answered call, @crm_push_call with a two-sentence note: the prospect's need, then the next step.
transfer_destinationsarray of objectnullableWhere 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.
at most 10 items
human_transfer_mode"warm" | "cold"nullableHow calls are transferred to transfer_destinations. Default: 'warm'. Ignored without transfer destinations.
"warm"The agent calls the destination first, briefs the person who answers on the call so far (see warm_transfer_summary_instructions), then puts the caller through.
"cold"The call is passed on at once, without a briefing (a SIP REFER: the phone carrier must allow it).
warm_transfer_summary_instructionsstringnullableWhen 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_speednumbernullableWhen 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.
0.6 to 1.5
precall_lookup_urlstringnullableInbound 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.at most 2000 characters
precall_lookup_headersarray of objectnullableHTTP headers sent with the pre-call lookup request, e.g. an API key. Null or empty when the endpoint needs none.
at most 10 items
voice_provider"cartesia" | "elevenlabs" | "gradium"Voice provider. Use with voice_id. To let the user choose by ear, use revox_pick_voice; otherwise revox_list_voices (pick a voice whose language matches the prompt).
voice_idstringVoice ID. Use with voice_provider. For French, use revox_list_voices and pick a voice with language 'fr', or Cartesia id a249eaff-1e96-4d2c-b23b-12efa4f66f41.
voice_speednumberVoice speed (default 1.0).
0.6 to 1.5
voice_volumenumberVoice volume for Cartesia only (0.5–2.0, default 1.0). Ignored for other providers.
0.5 to 2
voice_model"sonic-3" | "sonic-3.5" | "sonic-3.6"Cartesia TTS model (Cartesia only, default sonic-3.6). Ignored for other providers.
revox_check_assistant_setupread onlyCheck a saved assistant for the setup mistakes that break real calls (persona gender vs voice, transfer or booking with nothing connected, leftover template text, wrong language, wording that reads wrong once variables are filled).
MoreLess
Call it once after your last revox_create_assistant or revox_update_assistant, not after each edit: a fresh check takes a few seconds. Apply each issue's fix with revox_update_assistant (a text fix replaces
findwithreplaceinfield; a voice fix switches tovoice), then check again. An empty list means nothing major was found.Arguments (2)
idstringrequiredlocale"fr" | "en"Language of the issue messages. Defaults to en.
revox_list_assistant_toolsread onlyEverything an assistant's prompts can name as @name: call_tools for its prompt (the built-in actions, its calendars under their generated handles, its custom tools), post_call_tools for its post_call_prompt.
MoreLess
Each has its mention, a description, an example, and whether it is available on this assistant, with the setup it lacks otherwise. A calendar appears once an account is connected to it. Call this before writing a prompt that uses them.
Arguments (1)
assistant_idstringrequired
Voices
revox_list_voicesread onlyGet available voices (Cartesia, ElevenLabs and Gradium).
revox_get_voiceread onlyGet a voice by ID and provider.
Arguments (2)
idstringrequiredprovider"cartesia" | "elevenlabs" | "gradium"requiredThe provider of the voice.
revox_pick_voicewritesYou cannot play audio, so let the user listen and choose: this returns a url to a Revox page where they audition voices and validate one.
MoreLess
Give the user the url (ask them to open it and validate a voice), then call revox_wait_for_voice_pick with the pick_id: it returns the voice once validated, as voice_provider, voice_id, voice_speed, voice_volume and voice_model, to pass to revox_create_assistant or revox_update_assistant. Prefer this over choosing from revox_list_voices whenever the user cares about the voice.
Arguments (2)
languageenum (8 values)Only offer voices in this language: the language the assistant speaks (e.g. 'fr'). Omit to offer every language.
Possible values
"en""fr""es""de""it""pt""ru""zh"purposestringWhat the voice is for, shown on the page (e.g. "l'accueil téléphonique du cabinet Martin").
at most 120 characters
revox_wait_for_voice_pickread onlyWait until the user validates a voice on the revox_pick_voice page, or the server time window expires (~240 s).
MoreLess
If the result contains
_retry: true, the user has not chosen yet: call this tool again with the same pick_id (or ask them where they are). Once chosen, it returns immediately with the voice; the user can validate another one on the same page, and calling this again returns the latest.Arguments (1)
pick_idstringrequiredpick_id from revox_pick_voice
Calendars
revox_list_calendarsread onlyThe calendars an assistant books meetings on: their status (not_connected, needs_setup, ready), the mention the prompt uses, the connected account, the settings, and the link to connect them (invite.url) with what to do next.
Arguments (1)
assistant_idstringrequired
revox_connect_calendarwritesYou cannot sign in to a calendar account, so the user does: this returns a url to a Revox page where they (or a colleague, no Revox account needed) connect their Google Calendar, Calendly or Cal.com account and pick what to book on.
MoreLess
Pass provider to add a new calendar to the assistant, or calendar_id for a new link to one with no account (the previous link stops working). Anyone holding the link can connect an account, so give it only to the person concerned. Give the user the url, then call revox_wait_for_calendar. An assistant can have several calendars: call this once per calendar.
Arguments (3)
assistant_idstringrequiredprovider"google-calendar" | "calendly" | "cal-com-oauth"Adds a calendar on this provider. Omit with calendar_id.
"google-calendar"Google Calendar: books on a calendar of the account, with the opening hours and meeting length of its settings.
"calendly"Calendly: books an event type of the account.
"cal-com-oauth"Cal.com: books an event type of the account.
calendar_idstringAn existing calendar with no account, from revox_list_calendars. Omit with provider.
revox_wait_for_calendarread onlyWait until the calendar from revox_connect_calendar is ready to take bookings, or the server time window expires (~240 s).
MoreLess
If the result contains
_retry: true, it is not ready yet: follow its next_step, then call this tool again with the same ids (or ask the user where they are). Once ready, it returns the calendar with its mention, the @handle generated from the connected account.Arguments (2)
assistant_idstringrequiredcalendar_idstringrequired
revox_get_calendar_optionsread onlyThe calendars (Google) or event types (Calendly, Cal.com) of the connected account, to pass one to revox_select_calendar_option.
MoreLess
A notice says when the account's plan will stop bookings: tell the user. An option with bookable false is a Google calendar shared read-only: it cannot be picked, so if it is the one the user wants, tell them to ask its owner for "Make changes to events".
Arguments (2)
assistant_idstringrequiredcalendar_idstringrequired
revox_select_calendar_optionwritesPick the calendar or event type of the connected account, with an id from revox_get_calendar_options.
Arguments (3)
assistant_idstringrequiredcalendar_idstringrequiredoption_idstringrequired
revox_update_calendar_settingswritesGoogle Calendar: opening hours, meeting length, Meet link and the meeting location (it can use the call's variables, e.g. '{{site_address}}').
MoreLess
Calendly and Cal.com: the event type. Settings replace the current ones as a whole and must match the calendar's provider: start from connection.settings in revox_list_calendars. The calendar must have an account connected.
Arguments (3)
assistant_idstringrequiredcalendar_idstringrequiredsettingsobjectrequired
revox_disconnect_calendarwritesThe calendar keeps its handle, which the agent treats as not available, and its link is revoked.
MoreLess
Use revox_connect_calendar with its calendar_id to connect another account, which gives it that account's handle: update the prompt if it mentions the old one. Ask the user first.
Arguments (2)
assistant_idstringrequiredcalendar_idstringrequired
revox_remove_calendarwritesThe agent stops booking on it.
MoreLess
The account connection is deleted too, unless another calendar still uses it. Update the prompt if it mentions this calendar. Ask the user first.
Arguments (2)
assistant_idstringrequiredcalendar_idstringrequired
Campaigns
revox_list_campaignsread onlyGet all campaigns for the organization.
Account
revox_auth_statusread onlyCheck if the API key is valid.
revox_create_api_keywritesCreate a Revox API key for the organization, to configure another tool or service (env var, CI secret, integration).
MoreLess
The full key is returned only in this response and no tool can show it again: store it right away where it is needed, do not repeat it to the user unless they ask. The user can revoke it from dashboard_url.
Arguments (1)
namestringLabel shown in the dashboard, naming where the key will be used (e.g. 'Codex - CRM sync').
at most 255 characters
revox_get_live_call_linkread onlyGet a short-lived web page URL to listen to a call that is ringing or on the line, and take over from the AI to talk to the person (microphone required), or hang up.
MoreLess
Give the url to the user to open in their browser: you cannot listen yourself. Fails when the call is not live (queued, between attempts, ended): check its status with revox_get_call. The url is a credential scoped to this one call, so do not store or share it beyond the user.
Arguments (2)
idstringrequiredID of the live call.
expires_in_secondsintegerHow long the link can be opened, in seconds, from 30 to 3600. Default 300 (5 minutes). Keep it short: anyone holding the link can listen to the call and talk to the person on the line. Expiry only stops new openings: a page already connected to the call stays connected until the call ends.
30 to 3600
revox_set_demo_pagewritesThe demo page lets anyone with its link call the assistant and see the calls it placed, with their transcripts and recordings.
MoreLess
Off by default.
enabled: trueturns it on with a new link; calling it again regenerates the link and the previous one stops working at once.enabled: falseturns it off.Arguments (2)
idstringrequiredenabledbooleanrequiredtrue: turn the page on with a new link (regenerates it if already on). false: turn it off.
revox_list_pronunciationsread onlyThe words the assistant's voice must say a specific way (company, person or place names), chosen by ear in the dashboard: the text sent to the voice in their place, and voice_changed when the assistant's voice changed since.
MoreLess
To add or change one, send the user to the prompt editor: select the word, say it, pick the version that sounds right.
Arguments (1)
assistant_idstringrequired
revox_remove_pronunciationwritesThe voice says the word as written again.
Arguments (2)
assistant_idstringrequiredpronunciation_idstringrequired
revox_get_current_userread onlyGet the authenticated user.
revox_get_balanceread onlyGet organization balance (in euro cents).
revox_get_usageread onlyCredits used (1 credit = 1 worked contact = €0.50 excl.
MoreLess
VAT), calls, answered calls and time on the line over a period, point by point and per assistant and campaign, compared with the period just before; plus the credits left and the date they run out at the recent pace. Without arguments: the current month so far. Use it to answer 'how much did we spend', 'which campaign used the most credits' or 'how long will our credits last'.
Arguments (4)
fromstring (date-time)Start of the period, ISO 8601 (e.g. 2026-11-01T00:00:00+01:00). Default: the start of the current month in
timezone.tostring (date-time)End of the period, excluded, ISO 8601. Default: now.
granularity"hour" | "day" | "week" | "month"Size of each point of
series. Default: hour up to 2 days, day up to 92 days, week up to a year, month beyond. At most 400 points.timezonestringIANA timezone the points and the default period are cut in. Default: Europe/Paris.