place_phone_call
Place a phone call in France
Place a real outbound phone call to a number in France (+33) and get back a written result: a voice agent carries out the task you describe (book a table, move an appointment, ask a business a question, follow up on an order or a claim). Compliance: the service's rules require the voice agent to disclose it is an AI assistant at the start of every call (EU AI Act art. 50), and calls are placed only on the user's explicit request. The only exception is a callee the user confirms already knows an AI will call (ai_disclosure; not recommended).
The voice agent opens by saying it is an AI assistant calling on behalf of the user; if the callee objects to the call, it ends the call politely and the number is never called again by this service. It navigates phone menus (voice or keypad), waits on hold and talks with the person who answers. No audio is returned or recorded: you get a written outcome, a summary and, on request, the transcript (text kept 90 days at most).
When to use: the user explicitly asked you to phone a specific French business or person, and the number and the task are confirmed.
Number found by you: if the number did not come from the user (you found it by web search, in memory or in a document), STOP before calling: show the number to the user, ask "Shall I call this number?" and call only after they confirm in a later message.
Missing details: do not quiz the user for every detail before calling. Give the facts you already have in task; if the callee asks for something the user did not give, get_call shows it as pending_question and you ask the user then.
When not to use: marketing, sales prospecting, surveys, debt collection, mass or repeated calling (unlawful in France and refused); impersonating another person, an authority or a bank; threats or harassment; asking the callee for their codes, passwords, card details or a money transfer, gift cards or crypto (claiming money owed to the user is fine); dictating a payment code (3-
Parameterstaskrequiredvoicelanguagephone_numberrequiredscheduled_atai_disclosureoutside_hoursvoice_settingsidempotency_keycallee_informed_confirmation
get_call
Get call status and result
Get the status and written result of a call placed with place_phone_call (outcome, summary, pending question, transcript on request), optionally waiting for news. Compliance: read-only; transcripts are text only (no audio is recorded) and are kept 90 days at most.
Use it to follow a call in progress (repeat until done=true), to see whether the voice agent is waiting for the user's answer (pending_question), and to read the final outcome and summary to report to the user. Read-only: it never places, changes or ends a call.
Returns: status (scheduled, in_progress, retry_scheduled, completed, cancelled, failed), done, outcome (success, failed, voicemail, no_answer, busy, callback_requested, callee_objected), summary, pending_question {question_id, text}, new events since after_event_id, last_event_id and next_step. A call that is busy or not answered is retried automatically (status retry_scheduled), except on lines where every call needs a new request from the user (event callback_suggested: ask the user). callee_objected means the person asked not to be called again: the transcript was deleted and the number can no longer be called; tell the user.
Parameterscall_idrequiredwait_secondsafter_event_idresponse_format
answer_call_question
Answer the voice agent's question during a call
Send the user's answer to a question the voice agent asked during a live call (shown by get_call as pending_question) and get confirmation that it was relayed. Compliance: the same rules as the task apply; an answer that threatens, impersonates someone, asks the callee for codes, card details or a transfer, or dictates a payment code or a full card with its security code is refused before anything is sent.
Use it only when get_call shows a pending_question. The answer is spoken to the person on the line, so it must be the user's real information or decision: if you do not know it, ask the user and relay their words; never invent personal details. If the callee asks for a code (SMS, verification, delivery), a password or a card detail, ask the user: they decide whether to give it (write it as [secret: value] so it is masked in stored transcripts) or to decline, or to take the call themselves with transfer_call_to_user. During a live call, answer quickly: after about 45 seconds without an answer (pending_question.seconds_left) the voice agent offers the callee a callback; if you need to ask your human, call hold_call_question first (one extra minute, only if the callee agrees). If the call then ended with the question still open and a callback is scheduled (get_call shows status retry_scheduled with a pending_question), the answer is still accepted: it is kept and given at the start of the callback (sending the same answer again is harmless). Any other ended call fails with wrong_call_state. Then continue with get_call.
Parametersanswerrequiredcall_idrequiredquestion_id
transfer_call_to_user
Transfer a live call to the user
Transfer a live call to the user's own phone so they can talk to the callee themselves, and get the transfer request confirmed. Compliance: the voice agent tells the callee it is handing over to the person it calls for; recommended whenever a payment or sensitive data is needed.
The voice agent tells the callee it is passing the call over, rings user_phone_number, connects both sides without hanging up, then leaves the call. Use it only when the user asked to take over the conversation (or accepted when you offered) and can pick up their phone now. Fails if the call is not in progress. Follow progress with get_call: transfer events go requested → ringing → connected (or failed, in which case the voice agent stays on the line).
Parameterscall_idrequireduser_phone_numberrequired
schedule_callback
Schedule a callback of a finished call
Schedule a new attempt of a finished call (same number, same task) at the time the user chose and get the scheduled time back, for instance when the callee said 'call back tomorrow after 3 pm'. Compliance: only on the user's request; limited to 3 callbacks within 14 days, at the exact time the user chose (no calling-hours window); turned off on lines where every call needs a new request from the user (error callbacks_disabled).
Use it only after get_call shows done=true. To call another number or do a different task, use place_phone_call instead. The time is kept as given (at least 2 minutes from now); at most 14 days ahead and 3 callbacks per call. A real call will be placed at that time and paid like any call; cancel it with cancel_call.
Parameterscall_idrequiredcallback_atrequired
cancel_call
Cancel a scheduled or live call
Cancel a call that is scheduled or in progress (including a scheduled callback or automatic retry) and get the cancelled status back. Compliance: stops any further attempt to that number for this call; nothing is charged beyond the time already spoken.
A live call is hung up immediately; only the time already spoken is paid and the reserved credit is released. A scheduled call will not be placed. Use it when the user changes their mind or the task is no longer needed. Cannot be undone. Cancelling an already cancelled call has no further effect; a call that already ended cannot be cancelled.
Parameterscall_idrequired
List this account's calls, newest first, and get for each one its call_id, phone number, status, outcome, task and one-line summary. Compliance: read-only, limited to this account's own calls; transcripts older than 90 days are deleted.
Use it to find a call_id, to check whether a number was already called recently before placing a new call, or to answer questions such as 'what happened with my call to the garage?'. Read-only. For the full result and transcript of one call, use get_call with response_format='detailed'.
Parameterslimitqueryoutcome
get_account_balance
Get remaining call time
Read the remaining call time on this account and get the minutes of conversation left on the prepaid credit (subscription minutes included, with their expiry date) and the account limits (simultaneous calls, calls per day). Compliance: read-only; no payment can be made from here (only the account owner adds credit, in the web app).
Use it before a long call (e.g. one with a long hold) or after place_phone_call failed for insufficient credit. Read-only. Credit cannot be added from here: if it is low, tell the user to add credit from their account in the web app.
Takes no parameters.
hold_call_question
Ask the callee for one more minute to answer the agent's question
Get one more minute to answer the voice agent's pending question: the request is passed to the voice agent, which asks the callee. Compliance: the extension happens ONLY if the callee agrees; the voice agent asks them politely and never makes anyone wait more than 2 minutes in total for one question.
Use it as soon as get_call shows a pending_question you cannot answer yourself (you need to ask your human): call hold_call_question first, then ask your human. Once per question (+60 seconds). The voice agent asks the callee "can you hold for another minute, or shall I call you back?": if they agree, pending_question.seconds_left grows by 60; if they would rather be called back, the agent arranges a callback and your answer, sent later with answer_call_question, is given at the callback. Follow it with get_call (event question_hold: accepted, callee_prefers_callback or not_possible). Not for a finished call, nor when you already know the answer (just answer).
Parameterscall_idrequiredquestion_id
place_batch_calls
Place the same call to a list of numbers in France
Place the same call to a list of numbers in France (Pro and Enterprise plans) and get back a batch_id with one call_id per number. Compliance: the AI disclosure is always made; marketing, prospecting, surveys and mass calling of people who did not expect it are unlawful and refused; anti-harassment limits per number apply.
Use it when the user explicitly asks to make the same kind of call to several numbers they provide (e.g. confirm tomorrow's appointments with their own customers, ask several garages for a quote). The account's limits apply: calls run a few at a time (simultaneous-call limit; the rest wait their turn), the batch is refused if it exceeds the calls left for the last 24 hours, automatic retries and calls still waiting 15 minutes after the requested time stay within 08:00-21:00 callee's time. Each call is paid like a single call. Returns immediately; follow it with get_batch_calls, or each call with get_call. Starter accounts get plan_feature_required: tell the user.
Parametersnametaskrequiredvoicelanguagescheduled_atphone_numbersrequired
get_batch_calls
Get the progress of a batch of calls
Get the progress and results of a batch of calls: counts by status, successes, refused numbers and, for each call, its call_id, status, outcome and summary. Compliance: read-only, limited to this account's own batches.
Use it after place_batch_calls to report results to the user. Read-only. For one call's transcript, use get_call with response_format='detailed'. To stop a single call, use cancel_call.
Parametersbatch_idrequired
configure_agent_identity
Read or change how the voice agent introduces itself
Read or change how the voice agent introduces itself on the user's calls: name, tone, opening line, answer to "who is calling?", introduction and the AI mention in the opening. Compliance: the recommended settings (default) say "Hello, this is Léa, <user>'s virtual assistant. I'm calling about…" and answer yes when asked if it is an AI (EU AI Act art. 50); the agent never denies being an AI, whatever the settings.
Call it with no argument to read the current identity, a preview of what the agent will say, and the warning. Name and tone can be changed freely. Any other change is a deviation from the recommended settings: the first attempt returns the warning (error responsibility_acceptance_required) and changes nothing. Show the warning text to the user word for word; only if the user explicitly accepts, call again with the same changes plus accept_responsibility=true and warning_version. The acceptance is logged with a timestamp and the user becomes responsible for those settings. Refused whatever the acceptance: texts claiming the agent is human, or presenting it as police, government or a bank.
When to use: the user asks to rename the agent, change how it introduces itself or its tone. When not to use: a one-off greeting for a single call (put it in place_phone_call's task instead). Side effects: changes the settings for every new call of the account (calls already scheduled keep their identity). Idempotent.
Parameterstonefirst_nameintroductionopening_linewarning_versionreset_to_recommendedaccept_responsibilityai_mention_in_openingwho_is_calling_answer