Vocaleo

Docs

For agents and developers

What Vocaleo is

Vocaleo lets a personal AI assistant place one phone call and read one structured result. You hand over a phone number and a task in plain language; Vocaleo makes the call and returns what happened as machine-readable facts, not a transcript to parse. The customer is the agent. This page is written for you, the agent.

Machine-readable index

Public Vocaleo skill

Install the same public skill in Hermes or OpenClaw. It uses the existing HTTPS API for account setup, calls, and results. Each guide explains installation and secure account access.

MCP server

The API is also available through MCP (Model Context Protocol) tools, so an agent that speaks MCP needs no HTTP code of its own. Point your MCP client at https://api.vocaleo.co/mcp over streamable HTTP. The tools below include the optional dedicated-number add-on for all users.

One difference from the REST API below: you pass the API key as an api_key argument on authenticated tools, not as a bearer header. This lets an agent use the key the moment create_account returns it, in the same session, with no config change. The server stores nothing; it forwards the key to the same endpoints.

Behavior matches the REST API exactly, because each tool forwards one public endpoint — the same balance holds, task screen, and rate caps apply. A refused call comes back as a tool error whose content is the error body described below, verbatim; a rate limit adds retry_after_seconds.

Optional dedicated number

A dedicated number costs USD 3 per month through Stripe. Call credit is separate. The add-on is optional and available to all users. Accounts without it keep the shared outbound number.

Ask your agent for a dedicated number. It will show the country, price, and Stripe checkout link. You can say, “Get me a number with area code 413.” If none is available, your agent will ask for another area code. The selected number stays with your checkout. An existing number or pending checkout cannot change area code. After payment, a Vocaleo confirmation page shows your number once it is live. A pending purchase does not activate the number. Your account must report number_addon.active=true.

An active number supplies your outbound caller ID and receives return calls. The assistant identifies itself as your AI assistant, confirms the expected topic, and continues the newest matching outbound task. It uses a concise plan from the prior call to complete the task within your limits. Unknown callers can leave a general message unless you set custom instructions below. Ask your agent to list recent inbound calls.

Call forwarding is unavailable in this release. The assistant handles the task or takes a message.

Failed payment does not extend paid access. After expiry, the number cannot answer new calls. New outbound calls use the shared number; your agent must explain that change first. Ask your agent for the Stripe portal to fix payment or cancel renewal.

Choose how Vocaleo answers inbound calls

You need an active Vocaleo phone number for inbound instructions to work. Your personal mobile number does not meet this requirement. Agents must first use get_account or GET /v1/account with the same account credential. Check that number_addon.active is true. If it is false, explain that inbound instructions will not work yet. Offer the optional USD 3 monthly number. Start its purchase only when the user requests it. After payment, refresh the number status before you report setup as ready. Sufficient call credit is also required.

Ask your assistant to set separate instructions for unknown callers and calls from your registered phone number. For example, use a personal receptionist for unknown callers and a language tutor for your own calls. Vocaleo uses its prompt generator to turn each request into a saved system prompt and objective before a call arrives.

Use get_inbound_settings to read both rules. Use set_inbound_instructions with kind set to unknown or owner. Supply instructions as text, or null to clear only that rule. Direct MCP tools also need api_key; the OAuth connection uses the connected account.

For HTTP, send your bearer key with GET /v1/account/inbound-settings or PUT /v1/account/inbound-settings/unknown. Replace unknown with owner for your own calls.

{"instructions":"Act as my personal receptionist. Ask for the caller's name, reason, and callback number. Confirm the message."}

A successful read or update returns both unknown and owner. Each value is null or an object with instructions, system_prompt, and objective. Use 1–10,000 characters of nonblank text. An empty string does not clear a rule; send {"instructions":null}.

Both rules share a limit of 10 generation attempts per account per hour. Failed generation attempts count. Reads and clears remain available. HTTP 429 supplies Retry-After; tool errors supply retry_after_seconds. A generation failure leaves the saved rule unchanged. If the request disconnects, read the saved settings before a retry.

Caller ID does not prove identity or grant account access. AI and recording disclosure remain required. Custom instructions cannot enable call forwarding. Inbound calls still require an active dedicated number and sufficient call credit.

Automatic callback updates

Ask your agent to monitor return calls. Its host must support scheduled checks; Vocaleo cannot wake an idle agent. The agent checks for new completed calls every 60 seconds and reports the outcome, confirmed details, and charge. Empty checks stay quiet. The agent saves its result marker to avoid repeated notifications.

Use get_inbound_call_updates or GET /v1/inbound-call-updates. Omit cursor once before the outbound call to start from now. Save next_cursor after each page. Continue immediately while has_more is true. Use inbound history for earlier results.

Calls and account credit

1. Create an account

POST /v1/accounts, no authentication. phone_number(E.164 form) is required: it is the account's recovery handle if the key is lost, and one number may own only one account. email is optional. The response carries the API key — shown once, never again, because Vocaleo stores only its hash — and a payment_url.

2. Fund it

Send your user to the payment_url to add credit; a human with a card does this once. If payment_url is null, Stripe is not connected to that environment yet. Check the balance any time with the API key:

A standard call needs the max_charge_cents_per_call reserve. A Pro call needs the pro_max_charge_cents_per_call reserve. Vocaleo holds the selected reserve for the call. It returns the unused credit after settlement. The call then shows held_cents: 0. A full refund returns all credit held for that call.

3. Place the call

POST /v1/calls. Write the task the way you would brief a person: what to accomplish, and what to accept if the first answer is no. Send an optional Idempotency-Key header to make retries safe.

Set pro_mode=true only when the user selects Pro Mode. False or omission selects standard mode. Do not change the mode when you retry the same idempotency key. Vocaleo does not move a failed Pro call to standard mode.

Vocaleo Bridge: join when needed

Vocaleo Bridge lets your agent bring you into a standard outbound call when it needs your help. Bridge is off by default. Ask for it for each call, for example: “Book a table. Bring me in if you need me.”

After that explicit request, set allow_user_join=true on POST /v1/calls or start_call. False or omission keeps Bridge off. Task text alone does not enable Bridge. This permission applies to one call, not the whole account.

The agent puts the destination on hold and calls your verified account number. It explains the situation privately and asks for your agreement before it connects the calls. You cannot supply a different invite number in the call request.

Bridge is unavailable in Pro Mode. The verified number must be supported and different from the destination. Vocaleo rejects an invalid Bridge request before it reserves credit. Keep allow_user_join unchanged when you retry a request with the same Idempotency-Key. A changed permission with that key returns 409.

4. Read the result

GET /v1/calls/{call_id}. wait_seconds (0 to 60) holds the request open until the call reaches completed or error. A call usually outlives one wait, so repeat until the status is one of those two.

in_progress means the provider accepted the call. It does not prove that a person answered. For Standard calls, started_at can remain null while the call is active. Vocaleo normally receives that timestamp with the completed result. A null start time does not mean the call never dialed or is stuck.

An expired wait does not cancel the call or mean that it failed. Repeat the read with the same call ID. Do not start a duplicate call because the wait expired.GET /v1/account reports account credit, not call progress. Use the call endpoint or get_call for the result.

After settlement, held_cents is zero and charged_cents reports the final charge. Unspent credit returns to the account balance. Read the outcome and summary before you report success.

Close your account and delete its data

Ask your assistant to close your account permanently. It must explain the effects before you explicitly confirm. There is no undo. Wait for active calls, charges, and unresolved number purchases or refunds to finish.

  1. Request a fresh phone code with request_account_closure_code(api_key).
  2. Give your assistant the fresh code from your registered phone.
  3. After confirmation, use close_account(api_key, code, confirmation=true).

For HTTP, use POST /v1/account/close/verification, then POST /v1/account/close. Both requests require your current bearer key. The second body is {"code":"<fresh SMS code>","confirmation":true}.

The account closes immediately after acceptance. Access and subscription renewal stop. The receipt supplies account_id and erasure_status: pending. Eligible live data deletion follows automatically. A pending receipt does not prove completed deletion.

Remove the revoked key from your assistant's secret store. Stop account polling after closure. Do not recreate the account automatically after a 401 response. Contact support at support@vocaleo.co with the account reference for deletion status. Support also handles accounts without a registered phone or current access.

What a call promises

The agent says it is an AI on a recorded line, names the person it calls for when you set on_behalf_of, and never invents a fact you did not give it. Vocaleo calls United States, Canada, and United Kingdom numbers only. A task screen refuses harassment, fraud, impersonation of a real person, emergency-service calls, and unsolicited marketing.

The result

Both modes use the same result and private recording routes. Account closure removes eligible call content and live audio for both modes. Keep the Vocaleo call ID for reads. Do not start another call after an uncertain create response.

Authentication

Every authenticated request carries the API key as a bearer token: Authorization: Bearer vok_.... The key is shown once at account creation. Store it securely; never send it over a chat channel.

Price

Read all prices from the latest account response. Standard mode uses price_cents_per_minute and max_charge_cents_per_call. Pro Mode uses pro_price_cents_per_minute and pro_max_charge_cents_per_call. These fields are the source of truth.

The current standard rate is 10 cents per started minute, with a 450-cent reserve. The current Pro rate is 15 cents per started minute, with a 675-cent reserve. The reserve is required credit, not a minimum bill. A call that errors costs zero and returns the full hold. Return calls use standard mode and standard prices.

Call time is rounded up to the next whole minute before charging: a 45-second call is billed as 1 minute, and a 61-second call is billed as 2 minutes.

Errors

Every error body is {"error": {"code", "message"}} plus any named extra fields. Codes: unauthorized, not_found, invalid_request, task_rejected, insufficient_credit, rate_limited, conflict, temporarily_unavailable, executor_error.

Endpoint summary