Anbindung

REST API

Die vollständige Referenz der v1-API. Alles ist JSON, und Fehler haben eine einheitliche Form. Die Preise in volai werden in ganzzahligen Hundertsteln der tschechischen Krone angegeben (Suffix Hal); verbundene Rechnungen verwenden die kleinsten Einheiten ihrer jeweiligen Währung.

Authentifizierung

Jede Anfrage trägt einen API-Schlüssel im Header Authorization: Bearer vk_... . Ihren Schlüssel erhalten Sie im Portal unter Zugang und API (mehr dazu in der Schnellstart).

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

Diese gesamte API hat außerdem eine maschinenlesbare Beschreibung unter GET /openapi.json (OpenAPI 3.1, kein API-Schlüssel nötig) - generieren Sie daraus einen Client oder eine Postman-Collection, oder binden Sie sie direkt in n8n ein.

Fehlerformat

Ein Fehler hat immer dieselbe Form, egal was schiefgegangen ist:

{
  "error": {
    "code": "insufficient_credit",
    "cause": "account",
    "message": "Insufficient credit. Account balance is 3.00 CZK. Top up at volai.cz/en/credit and try again.",
    "action": "Top up the credit at https://volai.cz/en/credit (or ask the account owner to), then send the request again. Nothing was charged and volai itself is up.",
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Diese fünf können fast überall auftreten - die Endpunktreferenz unten führt zusätzlich nur situationsbezogene Codes auf:

400 (ungültige Eingabe) und 404 (Datensatz nicht gefunden) können ebenfalls fast überall auftreten, aber ihr code ist spezifisch für das Feld oder den Endpunkt - die genaue Liste steht immer beim jeweiligen Aufruf unten. Einige Aktionen können außerdem 502 (ein Fehler eines externen Anbieters - das Telefonnetz, ElevenLabs) oder 503 (vorübergehend nicht verfügbar, bitte gleich noch einmal versuchen) zurückgeben.

Wessen Problem es ist: cause und action

Jeder Fehler trägt außerdem cause (vier Werte) und action (ein englischer Satz dazu, was zu tun ist, den Sie dem Benutzer wörtlich vorlesen können). cause ist eine maschinenlesbare Antwort darauf, ob Ihr Code, Ihr Konto, die Zeit oder wir den Fehler beheben müssen:

Für KI-Agenten (Claude Code, Cursor, Ihre eigenen Skripte): Richten Sie sich nach cause, um dem Benutzer zu sagen, wer den Fehler behebt. Bei request nennen Sie das Feld aus message, bei account sagen Sie, was im Konto zu ändern ist oder welche ID zu prüfen ist, bei busy warten und wiederholen, und nur bei service sprechen Sie von einem Problem auf Seiten von volai. Melden Sie request, account oder busy nie als Ausfall von volai.

Die Ursache bestimmt der Code, nicht der HTTP-Status: Kontokontingente (agent_limit, tool_limit, api_key_limit, relay_lease_limit) liefern 400 und sind trotzdem account; not_found bei einem Datensatz ist account (die Antwort darf nicht verraten, ob die ID eines anderen existiert), ein unbekannter Pfad unter /v1 ist request. Die vollständige Zuordnung von Code zu Ursache für jede Operation steht in GET /openapi.json (in der Beschreibung jeder Fehlerantwort).

Die Meldung zum Code validation nennt das Feld (einen Punktpfad im Body, zum Beispiel dataFields.0.type), den tatsächlichen Wert und das akzeptierte Maximum, zum Beispiel Field "knowledge" is 210000 characters long, the maximum accepted is 200000. oder Field "systemPrompt" is required. Produktlimits (60 / 6000 / 300 / 20000 Zeichen für Name, Anweisungen, Ziel und Wissen eines Agenten) kommen als eigene Codes invalid_name, invalid_system_prompt, invalid_goal, invalid_knowledge mit der genauen Zahl. Ein unbekanntes Feld in einem strikten Body (Agent-Entwurf) liefert Unknown field "revision". Remove it; the documentation lists the accepted fields.

requestId und docsUrl

Jede v1-Antwort (Erfolg oder Fehler) trägt im Header X-Request-Id eine eindeutige Anfrage-ID (req_ gefolgt von 16 Hex-Zeichen) - ein Fehler wiederholt sie im Body als requestId. Eine wiedergegebene idempotente Antwort erhält ihre EIGENE aktuelle requestId - Header und Body widersprechen sich nie, obwohl der Rest der Antwort sonst mit dem ersten Mal identisch ist. Senden Sie diese ID an den Support, dann findet er genau diese eine Anfrage im Log.

Fehler-Bodies tragen außerdem docsUrl - einen Link direkt zurück zu diesem Abschnitt.

Bei Agent-Entwürfen (siehe Abschnitt Agent-Entwürfe unten) trägt der Fehler revision_conflict außerdem currentRevision - die aktuelle Revision. Laden Sie sie über GET .../draft und prüfen Sie den Unterschied, bevor Sie das Speichern wiederholen - senden Sie nicht blind denselben Body mit demselben expectedRevision erneut.

{
  "error": {
    "code": "revision_conflict",
    "cause": "request",
    "message": "The draft has changed since you last read it. Fetch the latest revision and try again.",
    "action": "Reload the record you are changing - GET /v1/agents/{id}/draft (or the get_agent_draft tool) for an agent draft, GET /v1/tasks/{id} (or the get_task tool) for a task - reapply your change on top of its current revision and send the request again with that value in expectedRevision (agent draft) or revision (task). This is not a volai outage.",
    "currentRevision": 4,
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Ein Fehler subscription_confirmation_required (409) trägt außerdem confirmUrl - einen Link zur Portalseite, auf der eine im Konto angemeldete Person eine Änderung bestätigt, die erhöht, was der gespeicherten Karte belastet werden darf (siehe PATCH /v1/subscription). Die Anfrage hat nichts geändert; der Link ist 24 Stunden gültig und kann einmal verwendet werden.

{
  "error": {
    "code": "subscription_confirmation_required",
    "cause": "request",
    "message": "This change was not applied, because it raises what may be charged to the saved card, and only a person signed in to the portal can confirm that. Nothing was changed. Open confirmUrl in a browser signed in to the account, review the change and confirm it; the link is valid for 24 hours and can be used once.",
    "action": "Nothing was changed, on purpose: either the change raises what may be charged to the saved card, or the account is a consumer who must make the request to start the plan in person, so only that person can confirm it. Give the confirmUrl from this error to the account owner to open while signed in to the volai portal; a confirmation link is valid for 24 hours and works once, a link to the plan form stays valid. Do not send the same request again: it only produces a new link. This is not a volai outage.",
    "confirmUrl": "https://volai.cz/kredit/pausal/potvrdit?t=eyJ1aWQiOiJ1X3NhbXBsZSJ9.4f1a9c0e",
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Header

Nach der Prüfung des Schlüssels trägt JEDE Antwort (Erfolg oder Fehler) RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden bis zum Ende des aktuellen Zeitfensters) - eine 429 durch das Limit des API-Schlüssels fügt zusätzlich Retry-After mit derselben Sekundenzahl hinzu. Eine 429 rate_limited durch das Limit für ausgehende Anrufe (POST /v1/calls) trägt ihre eigene Wartezeit in Retry-After - wie lange es dauert, bis dieses Limit wieder frei ist, sofern bekannt.

401 trägt einen Header WWW-Authenticate: Bearer realm="volai", error="invalid_token" (RFC 6750), damit eine HTTP-Client-Bibliothek den Grund des Fehlschlags erkennen kann, ohne den Body zu parsen.

Unbekannter Pfad und falsche Methode

Ein unbekannter Pfad unter /v1 (auch das nackte /v1) liefert für jede Methode (GET, POST, PUT, PATCH, DELETE, OPTIONS und HEAD) eine JSON-404 mit derselben Fehlerform wie überall sonst - {"error":{"code":"not_found", ...}}. Ausnahme: Die falsche METHODE auf einem VORHANDENEN Pfad (zum Beispiel DELETE /v1/balance) bleibt eine einfache Next.js-405 ohne JSON-Body - die einzige Stelle in ganz v1, an der ein Fehler keine dokumentierte Form hat.

Idempotenz

POST /v1/messages, POST /v1/calls, POST /v1/rings, POST /v1/voice-messages, POST /v1/relay, POST /v1/numbers, POST /v1/numbers/orders, POST /v1/sms-numbers, POST /v1/voice-sms-numbers, POST /v1/agents, POST /v1/tools, POST /v1/agents/{id}/draft/publish, POST /v1/agents/{id}/test-call, POST /v1/integrations, POST /v1/tasks, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/process, POST /v1/credit/topup, POST /v1/credit/auto-topup/setup, POST /v1/subscription/checkout, POST /v1/subscription/pay und POST /v1/subscription/card akzeptieren einen Header Idempotency-Key. Der Schlüssel gilt global für den jeweiligen API-Schlüssel, unabhängig von HTTP-Methode, Pfad oder Body. Geben Sie jeder eigenständigen logischen Aktion über alle Endpunkte und Request-Bodies hinweg einen neuen Wert; verwenden Sie einen Wert nur erneut, wenn Sie genau dieselbe logische Anfrage wiederholen, typischerweise nach einem Timeout, wenn Sie nicht wissen, ob der erste Versuch durchgegangen ist. Innerhalb von 24 Stunden erhalten Sie dann genau dieselbe Antwort wie beim ersten Mal, bei einem fehlgeschlagenen ersten Versuch auch dessen Fehlerantwort, und nichts wird doppelt gesendet oder angerufen. Sie können die Bestell-ID Ihrer eigenen Anwendung plus den Namen der konkreten Aktion verwenden. Eine gleichzeitige Anfrage mit demselben Schlüssel, die noch läuft (die Antwort ist noch nicht gespeichert), liefert 409 idempotency_in_progress - bitte versuchen Sie es gleich noch einmal.

Bei POST /v1/numbers/orders wird der Schlüssel dauerhaft an die Bestellung gebunden, bevor der Betreiber aufgerufen wird; seine Wiederverwendung mit einer anderen Adresse liefert 409 idempotency_conflict. Gibt der Betreiber nach einem Kauf eine uneindeutige Antwort, muss die Bestellung unter Umständen geprüft werden.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: objednavka-4471" \
  -d '{"to": "+420777123456", "body": "Vielen Dank für Ihre Bestellung."}'

Rate-Limits

60 Anfragen pro Minute und API-Schlüssel (MCP teilt sich dasselbe Limit - es nutzt denselben Schlüssel). Bei Überschreitung kommen 429 und ein Header Retry-After mit der Zahl der Sekunden bis zum nächsten Versuch.

POST /v1/messages hat zusätzlich ein eigenes Limit: höchstens eine SMS alle 2 Sekunden und 100 SMS pro Konto und Tag. Das Senden von einer Mobilnummer (fromNumber) hat ein weiteres Tageslimit pro Konto: 20 Nachrichten in den ersten 30 Tagen nach dem Kauf der Nummer, danach 50. GET /v1/sms-numbers zeigt, wie viele noch übrig sind und wann das Limit zurückgesetzt wird (dailySendRemaining, dailySendResetsAt).

Ausgehende Anrufe (POST /v1/calls, Relay und Testanrufe) teilen sich ein eigenes Limit: 10 Anrufe pro Minute und 1000 pro Tag und Konto, mit höchstens 2 gleichzeitig laufenden Anrufen des integrierten Agenten.

Wie viel vom Limit von 60/min Ihnen bleibt, sehen Sie schon, bevor Sie 429 erreichen - in den Headern RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, die jede Antwort trägt (siehe Fehlerformat > Header oben).

Paginierung

GET /v1/messages und GET /v1/calls nehmen limit (maximale Zahl der zurückgegebenen Datensätze - standardmäßig 50, auf 200 begrenzt, auch wenn Sie mehr anfordern) und before (ein Zeitstempel in Millisekunden - liefert nur ältere Datensätze).

hasMore und nextBefore

Beide Antworten tragen außerdem hasMore (boolean - es gibt eine ältere Seite) und nextBefore (den Zeitstempel des letzten zurückgegebenen Datensatzes, oder null, wenn hasMore false ist). Für die nächste Seite senden Sie nextBefore aus der vorherigen Antwort als neues before - ohne eigene Offset-Rechnung.

before ist EXKLUSIV (liefert nur strikt ältere Datensätze, nie gleich alte) - der letzte Datensatz der vorherigen Seite wiederholt sich auf der nächsten nie. Im seltenen Fall, dass zwei Datensätze genau an der Seitengrenze denselben Millisekunden-Zeitstempel haben, kann der zweite wegfallen. Entfernen Sie Duplikate anhand von id - verlassen Sie sich nicht darauf, dass Seiten nie etwas überspringen.

GET /v1/calls?direction=in oder ?direction=out durchsucht den Verlauf in Stapeln mit einer harten Obergrenze für die Zahl der Stapel - hasMore: true kann daher entweder "es gibt ganz sicher eine weitere Seite" bedeuten oder "wir haben Stapel bis zur Obergrenze durchsucht und das Ende des Verlaufs noch nicht erreicht". false bedeutet immer, dass der Verlauf in dieser Richtung wirklich zu Ende ist.

Versionierung

Die aktuelle Version der öffentlichen Schnittstelle ist 1.58.0 (GET /openapi.json, Feld info.version - siehe den Absatz zur maschinenlesbaren API-Beschreibung in der Einleitung oben). Drei Regeln bestimmen, wie sich die Version ändert:

1. Innerhalb von v1 werden nur OPTIONALE Felder und neue Endpunkte hinzugefügt - bestehende Felder verschwinden nie, ändern nie ihren Typ und nie ihre Bedeutung. Eine Integration, die nur Felder liest, die sie kennt, wird durch ein Update nie beschädigt. Die einzige Ausnahme war Version 1.5.1, die answeredBy bei EINGEHENDEN Anrufen nicht mehr zurückgab - das Feld hatte dort nie einen sinnvollen Wert (siehe Changelog unten).
2. Ein Pflichtfeld oder eine Änderung der Bedeutung eines bestehenden Feldes erscheint immer nur als neue Hauptversion (v2) - nie als stille Änderung an v1.
3. Senden Sie bei Agent-Entwürfen (siehe Agent-Entwürfe oben) immer genau das Objekt zurück, das Sie aus GET .../draft gelesen haben - der Body von PUT/POST ist .strict(), daher liefert ein unbekannter Schlüssel (etwa aus einer neueren Version, die Ihre Integration noch nicht kennt) 400 validation, statt stillschweigend verworfen zu werden.

Changelog

• 5 Nov 2026 (1.58.0): The new POST /v1/voice-sms-numbers/countries/{country}/waitlist (no body) and the MCP tool join_voice_sms_country_waitlist sign the account up for the waitlist of a country that is not in the offer; the response is {country, joined: true, alreadyJoined} and nothing is charged. A country in the offer or outside the map returns validation. GET /v1/voice-sms-numbers/countries and MCP list_voice_sms_countries have a new waitlisted field (ISO codes of the countries the account signed up for). Ordering a number does not change.
• 5 Nov 2026 (1.57.0): The agent language accepts 20 values: cs, sk, en, de, pl, nl, pt, sl, ro, da, et, lv, bg, fi, el, fr, it, hu, lt, sv. A number in another country can be routed to an ElevenLabs agent; the error el_outbound_trunk_not_configured (HTTP 503, cause service) means our outbound trunk is missing. REST and MCP messages stay in English.
• 4 Nov 2026 (1.56.0): GET /v1/voice-sms-numbers/countries and the MCP tool list_voice_sms_countries return monthlyFeeHal for every country (hellers per 30 days excluding VAT). POST /v1/voice-sms-numbers with country orders the number at that country's fee from the offer; no fee confirmation is added. The MCP tool order_voice_sms_number requires confirmedMonthlyFeeHal equal to the fee of the chosen country; any other value is a validation error and nothing is ordered, while the Prague number still confirms 4900. A number record carries the monthlyFeeHal of its country and the same amount is charged by the first fee and every renewal. A country without a set fee does not appear in the offer.
• 4 Nov 2026 (1.55.0): POST /v1/voice-sms-numbers accepts an optional country (ISO 3166-1 alpha-2, uppercase); without it the Prague number is ordered as before. The countries the account may order are returned by GET /v1/voice-sms-numbers/countries and the MCP tool list_voice_sms_countries; a country outside that list is rejected with country_not_offered and nothing is charged. Number records carry country and sms, and a number outside Czechia rejects sending SMS. Outbound calls go only to Czechia, and to the country of the number only where the country_and_cz zone is enabled; the gate rejects any other destination. At most 2 numbers per country.
• 4 Nov 2026 (1.54.0): regions in GET /v1/numbers/available, the region parameter of POST /v1/numbers and the search_available_numbers and buy_number tools now know jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky. Regional stock is small, so pool_empty is more common there: use join_number_waitlist or order_number_from_region.
• 4 Nov 2026 (1.53.0): The offer catalogue now knows all 14 regions. A regional offer (jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky) appears in regions of GET /v1/numbers/available and in the MCP descriptions only once it is on sale; until then it is rejected as an unknown region. The regionLabel text changes: a number from a region carries the English region name, such as Moravian-Silesian Region.
• 4 Nov 2026 (1.52.1): A header value with three asterisks in a row (a leftover of the mask, such as Bear***abc) is rejected by PUT /v1/webhook and set_webhook with invalid_webhook_headers; previously only the whole mask was. The descriptions of get_webhook, send_test_webhook and the MCP server instructions mention headers, and the docs now say the test event carries custom headers. Value limits (1 to 1000 printable ASCII characters) added to OpenAPI and the webhooks page.
• 3 Nov 2026 (1.52.0): PUT /v1/webhook and MCP set_webhook accept optional headers (at most 5 headers, values up to 1000 characters, printable ASCII only). GET/PUT /v1/webhook and get_webhook/set_webhook return a new headers field with masked values (Bear***, {} when none are set). Omitting headers keeps the stored ones, {} removes them, and a value equal to the mask keeps the stored one. Changing the URL to a different domain drops stored headers, and a mask is rejected there. host, content-type, content-length, volai-signature and hop-by-hop headers cannot be set. Headers go with every event including webhook.test and are not sent when a delivery is redirected to a different domain. New error invalid_webhook_headers (400).
• 3 Nov 2026 (1.51.0): REST POST /v1/voice-messages with the body {to, text, repeat?} (text 1 to 500 characters, repeat 1 to 3, default 1; an unknown field including ringingTimeoutSecs is rejected with validation) returns {id, status, from} and accepts an Idempotency-Key header like POST /v1/calls. The MCP tool send_voice_message calls the same service. The result is in GET /v1/calls/{id} as kind: "voice_message" with a voiceMessage block (text, repeat, repeatPlayed, completed) and in the call.completed or call.no_answer webhook; the call summary e-mail is not sent for a voice message. New errors voice_messages_disabled (503, the feature is switched off), voice_message_unavailable (503, the voice engine cannot accept messages) and email_unverified (403).
• 1 Nov 2026 (1.50.0): REST GET, PUT and DELETE /v1/account/spend-cap (response {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}; PUT takes capHal in whole hellers excluding VAT from 5,000 to 100,000,000, warnShare from 0.5 to 0.99 with a default of 0.8, and inboundAboveCap, which is not overwritten on a change when the field is omitted) and MCP get_spend_cap, set_spend_cap and clear_spend_cap, all over lib/service/spend-cap.ts like the Monthly spending cap section under Credit. Once the cap is reached, POST /v1/calls, /v1/messages, /v1/rings, /v1/relay, the test call and task dialling are refused with the new error spend_cap_reached (HTTP 402, nothing is charged); an inbound agent call without inboundAboveCap: true ends after one sentence and the call carries endReason: spend_cap. The month's spend (Europe/Prague) is counted on every account, also without a cap, and includes the part covered by the monthly plan credit. Number fees, the Done for you round and the monthly plan are not counted; the cap does not stop calls already running or CDRs booked after midnight, forwarding without an agent, or outbound calls from a number in Own SIP PBX mode with inboundAboveCap: true. Warning and reached e-mails go at most once a month and are released again when the cap changes. REST POST /v1/agents/{id}/draft/knowledge-import with a body of {url} or {text, filename} (a .txt or .md file up to 1 MB; the portal takes a file up to 800 kB), optionally mode (append by default, or replace), preview (only returns the result, writes nothing) and expectedRevision. The MCP tool import_agent_knowledge (id, url or text + filename, the same optional fields) calls the same service, lib/service/knowledge-import.ts. The text is written into knowledge of the DRAFT and the source into the new knowledgeSources field (at most 20 sources: url or filename, importedAt, chars), which the agent shape now also returns (GET /v1/agents/{id}, list and detail). What does not fit into 20,000 characters is summarized by a model (method: summarized) or cut (truncated). Errors: invalid_import_url, private_address, invalid_knowledge, import_too_large, revision_conflict, rate_limited (10 imports per hour per account). A fetched page is third-party text: the preview and the misuse check when the draft is saved guard against it, and REST saves it right away without preview. REST POST /v1/account/cancellation-request with a body of {reason, note?} (reason is one of too_expensive, callers_hang_up, missing_feature, not_needed, other; note at most 500 characters) and the MCP tool request_account_cancellation call lib/service/account-cancellation.ts, the same service as the form in Settings. Response {cancellationRequest: {reason, note, requestedAt, alreadyRequested}}; a repeated request returns the original record with alreadyRequested: true (HTTP 200) and sends no further e-mail. There is at most one request per account, it changes the account in no way and deletes nothing; the volai owner gets an alert with the reason and the customer a confirmation in the account language. Errors: validation, user_not_found. When you click thumbs down in the call e-mail, the rating is saved right away and on the page that opens you can pick a reason and add a note in a single form. Before, there were only five separate buttons and no note. When you write to podpora@volai.cz, you get an automatic confirmation that the message arrived, saying that we usually reply within one business day, with a link to the status page. At volai.cz/en/trust (in Czech volai.cz/duvera) you find in one place where the data of calls, SMS and your account lies, who touches it, how long we keep it, how we protect it and what we cannot do yet. The website gains a Call from your browser button that lets you try the volai demo agent with a call right from your browser, without signing up. The call is a demo, it is recorded and the agent speaks Czech. We are switching it on gradually, so it may appear only after a while. public/llms.txt, public/SKILL.md, /docs/api and /docs/mcp (cs and en) match the code: create_calendar_event creates an appointment only with confirm: true and the calendar deletes nothing; the number for calls and SMS is in pilot mode (voiceSmsNumbersMode() is admin), other accounts get voice_sms_numbers_unavailable (until 3 Nov 2026; since then the mode is on and any account orders the number itself). The trial call's remainingLine states that an unanswered call also counts towards the limit of 3 calls per 24 hours.
• 1 Nov 2026 (1.49.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-11-15T23:00:00+01:00 (22:00 UTC; previously 2026-11-14T23:00:00+01:00) and PETCENTER_REMINDER_DISPATCH_END stays 2026-11-21T19:55:00+01:00 (18:55 UTC). petcenterCampaignQuotaActive() and the runPetcenterOutboundTaskTick tick therefore dial the main campaign until 15 November 22:00 UTC and coupon_reminder tasks still until 21 November 18:55 UTC. The stored quota of the campaign agent (call-quota:agent) has its own validUntil, which is moved separately via PUT /api/admin/call-quotas from 2026-11-14T22:00:00Z to 2026-11-15T22:00:00Z. The other conditions of the exception (the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, account, agent, outbound task, eight relay names) are unchanged.
• 30 Oct 2026 (1.49.0): POST /v1/tools, PATCH /v1/tools/{id} and MCP create_tool and update_tool accept an optional requireConfirmation field (boolean, default false; any other type is 400 validation). Responses that carry a tool (GET /v1/tools, GET /v1/tools/{id}, POST, PATCH, MCP list_tools) always return it as a boolean; POST /v1/tools/test does not have it. A PATCH without the field keeps the stored value (neither an older client nor a stale portal page switches the gate off), false switches it off. The engine receives require_confirmation: true only for a tool with the gate on and only for an agent on the engine in cs or sk; false is never sent explicitly. An agent in en, de or pl and an ElevenLabs agent ignore the field, and saving the tool is not refused because of language, since a tool belongs to the account and is shared by several agents. Editing a tool does not rewrite agents on the engine: the flag reaches them at the agent's next save (PATCH /v1/agents/{id}) or publish (POST /v1/agents/{id}/draft/publish). With a running campaign, re-publishing an unchanged tested draft keeps the tested mark and the task carries on, now with a gate the test did not cover; a direct PATCH /v1/agents/{id} clears the mark and the task stops with agent_version_changed. A PATCH that changes only requireConfirmation does not call ElevenLabs and does not re-verify the tool address (no DNS lookup), so the gate can be switched even while the tool's domain is unreachable. The gate reads only the caller's last utterance and does not know the agent's question: it catches an unclear consent, not every “yes” given to a different question. Portal: the tool editor (/en/agent/tools/new and /en/agent/tools/[id]) stores the choice in the same field with the switch Require the caller's clear consent; a hidden form flag distinguishes an unchecked switch from a form that did not know the switch, so a stale page cannot silently switch the gate off, and after saving a changed gate the form says that for a running agent it takes effect only after that agent is published. The method, the parameter type and source are submitted from form state and the description is a controlled field, because React 19 resets the form after every form action and the second save after an error used to send the first option of a select and the old description. GET /v1/subscription and MCP get_subscription: available says whether a NEW plan can be started right now, and it is true only when the offer is on for the account and the account has no running plan (active, past_due); otherwise it is false. It used to be true for a subscriber too, although POST /v1/subscription/checkout returned 409 subscription_exists. It is true again once the plan has ended (canceled). A client that used available to tell whether the account has a plan should read subscription instead. recommendation does not depend on available and a subscriber still receives it. PATCH /v1/subscription and MCP update_subscription: a tier the account is already switching to (nextTier) counts as done (200, not 400 invalid_tier), so the same body can be sent again after an outage in the middle and finishes what is left. Exceptions: the current tier with no scheduled change stays invalid_tier; going back to the current tier (it cancels the scheduled change) does not count as done on a repeat and ends with invalid_tier; on a plan set to end a tier alone still returns invalid_state (with cancelAtPeriodEnd: true in the body it is a repeat and goes through). invalid_state is now also listed among the errors of PATCH /v1/subscription in OpenAPI and in the documentation. GET /v1/balance and MCP get_balance: the notices subscription_exhausted_topup, subscription_cap_reached and subscription_runway carry a new optional field cancelAtPeriodEnd: true (present only when true: the plan does not renew, renewsAt is the end of the plan and no new monthly credit arrives). The format of renewsAt (epoch ms) does not change and is documented as the same moment as subscription.periodEnd (ISO 8601). The e-mails about a failed renewal and about the end of a plan have their own wording when the account has no saved card (the card is missing, nothing was charged). An outbound agent call on the engine that stayed ringing or initiated without a conversationId and was closed as failed with price 0 by the watchdog (or by the task reconcile) after two hours now behaves in a task like relay_not_routed: the attempt has items[].attempts[].countsAsAttempt: false and errorCode: "no_provider_report", uses up neither maxAttempts nor the lorela_enterprise schedule, the budget reservation is released, nothing is charged, and the contact gets nextAttemptAt no sooner than 60 seconds later. relay_not_routed and no_provider_report attempts are added together in one series: after the third uncounted attempt in a row the contact goes to review with the reviewReason of the last one, that is call:no_provider_report; earlier only when the next attempt does not fit before expiresAt or the lorela_enterprise policy allows no further attempt. A call that a late post-call completed with a conversationId was seen by the engine, so it counts as before. Items that an earlier call of this kind had already sent to review (call:failed, or call:unknown with the policy) are not reopened automatically. errorCode and reviewReason are free strings, only a new value was added; an integration that reads reports from tasks should expect one more uncounted attempt and one more review reason. A pause (POST .../pause, the batch pause for a campaign) between the dial intent being written and the provider request used to leave reviewReason: "dispatch_in_flight", the active claim, the reservation and an in_progress item with no call and no attempt; start then returned task_needs_attention, resolve returned item_not_resolvable, DELETE returned task_not_deletable and reconcile changed nothing. After such a pause the task processing now releases the intent, the claim and the reservation itself and returns task_paused (no call was placed): the contact is pending again (or failed with a free attempt) and the task is paused without a reviewReason, so the first start succeeds. The cleanup is retried up to three times on a concurrent write (revision_conflict), as is the cleanup at the last gate before the provider, whose result used to be discarded. reconcile (the cron, POST /v1/tasks/{id}/reconcile, MCP reconcile_task) additionally releases an intent that has no call record and no attempt result and whose claim and five-minute margin after it have both expired, that is at the earliest 15 minutes after the dial began (the claim lives for 10 minutes): it returns the reservation and puts the contact back to waiting, or completes it after a verified callback. A task that the expired claim had meanwhile stopped (dispatch_claim_expired) ends paused without a reason and has to be started again (start); a task the claim did not stop keeps running. An uncertain dial and a call that may have been created are left as they are. Tasks that got stuck earlier are repaired by a single reconcile and end as paused without a reason (the pause was intentional), they do not restart on their own. Response shapes do not change. POST /v1/dnc and MCP add_to_dnc accept either e164 (one number, the response { "added": true, "e164": ... } is unchanged) or the new field e164s (1 to 500 numbers, written with a single SADD command). Both fields together, neither, an empty array and more than 500 entries are 400 validation; in OpenAPI both fields are optional and the rule "exactly one of them" is enforced by validation only. An entry of e164s must be a string of at most 256 characters, any other entry fails the whole request with 400. The response to e164s carries addedCount, alreadyOnListCount, rejectedCount and rejected (entries { index, input, reason: "invalid_number" }, where input is the entry as sent, cut to 32 characters). addedCount + alreadyOnListCount + rejectedCount always equals the number of entries sent; a number repeated in the request or written in another format counts as already on the list. An entry that is not a valid number (including longer text, for example two numbers in one cell) does not fail the request, the valid entries are always added, and an input of only invalid entries is still 200, so check rejectedCount after every response. The request is idempotent (repeating it returns addedCount: 0). In OpenAPI the response of POST /v1/dnc is an anyOf of both shapes and the boolean added stays only in the single-number response. Numbers are still removed one at a time (DELETE /v1/dnc/{e164}). The destination check at dial time reads one SISMEMBER instead of the whole set, so a list with thousands of numbers no longer transfers tens of kB on every dial; the listings GET /v1/dnc and list_dnc are unchanged. REST POST /v1/tasks/{id}/items/{itemId}/resolve and MCP resolve_task_item accept reason with the value customer_purchased or, new, unsubscribed on the audited skip (action: "skip" with operationId and evidenceRef). evidenceRef is an opaque reference to the purchase or unsubscribe record, never a phone number or e-mail. Conditions are unchanged: a draft task (contact pending) or a paused task (contact pending or failed), no active claim, dial intent or reservation, and the skip does not resolve contacts in review. Attempts, costs and the do-not-call list stay as they are. The reason is part of the fingerprint (resolution.fingerprint), so repeating the same operation writes nothing and the same operationId with a different reason or evidenceRef returns 409 revision_conflict. items[].resolution.reason in every response that carries a task (GET /v1/tasks, GET /v1/tasks/{id}, POST .../resolve, MCP list_tasks, get_task, resolve_task_item) is now the enum customer_purchased | unsubscribed (a constant in OpenAPI before): a client that validates responses against the old specification must allow unsubscribed. An unknown reason in the request returns 400 validation. Descriptions in OpenAPI, MCP and the API, MCP and Tasks documentation are updated.
• 26 Oct 2026 (1.48.0): REST: GET /v1/voice-sms-numbers, POST /v1/voice-sms-numbers (no body, Idempotency-Key supported, returns 202 with the number in the awaiting_registration state), GET /v1/voice-sms-numbers/{e164}, PATCH /v1/voice-sms-numbers/{e164} (routing: agent on the in-house engine, or none), POST /v1/voice-sms-numbers/{e164}/cancel (cancelling before the registration is approved is free) and DELETE /v1/voice-sms-numbers/{e164} (releasing an active number is irreversible and the period already paid is not refunded; when the cancellation with the carrier fails, the number stays in the releasing state and the response is 502 release_failed). MCP: list_voice_sms_numbers, order_voice_sms_number (confirmedMonthlyFeeHal must be 39000, otherwise nothing is ordered), set_voice_sms_number_routing and cancel_voice_sms_number; releasing is deliberately not available over MCP. Number states: awaiting_registration, active, rejected, releasing. SMS from the number are sent with fromNumber in POST /v1/messages and send_sms (+420 recipients only, no deliveryStatus), received SMS are still read with GET /v1/messages?direction=in and the message.received webhook; calls from the number are placed by an agent (POST /v1/calls with agentId, to +420 only, one outbound call at a time); a bridge between two numbers with from and a ring from it are not available (unsupported_for_number_type). New error codes: voice_sms_numbers_unavailable, voice_sms_number_limit (at most 2 numbers per account, ordering needs a first top-up), voice_sms_order_limit, voice_sms_number_out_of_stock, unsupported_for_number_type (forward and sip are not supported for this number) and destination_not_allowed (the number can call +420 numbers only). The fee of 390 CZK per 30 days is charged as number_fee; the number_fee notice in GET /v1/balance and MCP get_balance counts these numbers too, and a debt older than 7 days releases the number just like other numbers.
• 26 Oct 2026 (1.47.0): GET /v1/account and MCP get_account return a new testCalls field next to account, with max (3), remaining (test calls left in the current window) and resetAt (when the window ends, epoch ms; the window runs 24 hours from the first attempt; null when there was no attempt in the last 24 hours). POST /v1/agents/{id}/test-call and MCP test_call carry the same field right after dialing. Every dialed attempt counts, including an unanswered one, which is not charged; an attempt that never dialed (agent, credit or capacity error) does not count. The field is additive, existing response shapes do not change. PATCH /v1/account does not return it.
• 23 Oct 2026 (1.46.1): POST /v1/tasks/{id}/reconcile, MCP reconcile_task and the task cron settle a task after recovery by the work that is left: paused while any contact is waiting for another attempt (pending, failed, in_progress), even if other contacts are in review; needs_attention only when nothing is left to dial but a contact in review (the task's reviewReason is the reason of the first such item); completed when nothing is left. reviewReason is set only for needs_attention and empty otherwise; after a pause in the middle of a dial and after an expired claim activeItemId, activeClaimToken and activeClaimUntil are released as well. It applies to four recoveries: after a pause in the middle of a dial (dispatch_in_flight), after an expired claim (dispatch_claim_expired), after a call with a previously unknown price is settled (billing_unknown) and after an uncertain dial is resolved (dial:*). Before, recovery put review before work, so pausing a running task sent a task with hundreds of waiting contacts to needs_attention, which start and PATCH (task_not_editable) refused. An uncertain dial for which no call can be found keeps the task in needs_attention (the contact holds an unresolved dial intent and start would refuse it) until POST .../items/{itemId}/resolve decides that contact; the same applies after a call with an unknown price is settled (billing_unknown) while another contact holds an unresolved dial intent. A running task and task-level reasons (for example variables_limit) are not changed by reconcile. With the retryPolicy: "lorela_enterprise" policy the state of a contact after the last allowed attempt (maxAttempts) changes too: a no_answer, missed, busy, completed voicemail without a human or an answered call in which the person said nothing closes it as skipped with reviewReason: "retry_policy_exhausted", like retry_age_expired when the horizon runs out (before: review); the link to the last call (providerCallId) stays. An uncertain result of the last attempt stays in review with the same reason, and the policy still rejects a manual resolve with retry. A verified human callback after this closing turns the contact into completed (after retry_age_expired and task_expired it stays skipped with callbackContactCallId). Tasks without the policy do not change. POST .../items/{itemId}/resolve does not change: the last resolved item in review turns a task with work left into paused. Tasks that got stuck in needs_attention before the rollout do not repair themselves (their reason is derived from an item): resolve with skip over the items in review frees them once.
• 23 Oct 2026 (1.46.0): POST /v1/tasks, PATCH /v1/tasks/{id}, MCP create_task and update_task accept optional retryMaxAgeDays: a whole number 1 to 30, the retry horizon of the retryPolicy: "lorela_enterprise" policy in days from the recipient's first counted attempt. The public task (GET /v1/tasks, GET /v1/tasks/{id}, the create and PATCH responses, MCP get_task and list_tasks) returns it only when it was set; an absent field means the default 5 days as before, so tasks without the field behave unchanged. The field needs the policy (in the same body at creation, in the body or already stored on the task on PATCH), otherwise validation is returned with the field retryMaxAgeDays; so is a value outside 1 to 30 or a non-integer. Omitting it on PATCH preserves the value. Unlike retryPolicy, it can be changed after attempts have started, in the states PATCH has always accepted (running and completed still not: task_not_editable). Raising the value on a paused task returns items that are skipped with reviewReason: "retry_age_expired" to pending with a new nextAttemptAt when they have a counted attempt, a free attempt below maxAttempts, no verified callback and their first counted attempt + the new horizon (and expiresAt, when set) is in the future; lowering it reopens nothing and contacts outside the new horizon stay skipped. The attempt ladder (8 minutes after the first, the 08:00-09:00 and 17:00-19:00 windows, four attempts) does not change, only the horizon does. Portal: the task detail of a task with the policy shows a line about the retry schedule and horizon, the calling rules have a Retry horizon (days) field and offer four attempts for a task with the policy. OpenAPI, the MCP tool descriptions, SKILL.md and the Tasks guide are updated.
• 23 Oct 2026 (1.45.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-11-14T23:00:00+01:00 (22:00 UTC; previously 2026-10-31T23:00:00Z) and PETCENTER_REMINDER_DISPATCH_END is 2026-11-21T19:55:00+01:00 (18:55 UTC; previously 5 November). petcenterCampaignQuotaActive() and the runPetcenterOutboundTaskTick tick therefore dial the main campaign until 14 November 22:00 UTC and coupon_reminder tasks until 21 November 18:55 UTC. The stored quota of the campaign agent (call-quota:agent) has its own validUntil and is moved separately via PUT /api/admin/call-quotas. The other conditions of the exception (the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, account, agent, outbound task, eight relay names) are unchanged.
• 23 Oct 2026 (1.45.0): The number's relay names are set up in the background right after purchase (POST /v1/numbers, buy_number, portal) and after an order is fulfilled (POST /v1/numbers/orders, order_number_from_region), whatever the number's routing. A lease (POST /v1/relay, create_relay_lease), an agent call or a transfer from a number that does not have them yet triggers the setup again. The create_relay_lease description spells out a rule that already applied: a lease connects exactly one call, dialing the same sipName again is rejected with SIP 603, so create a new lease before every attempt and turn off automatic redialing in your platform. Response shapes are unchanged.
• 22 Oct 2026 (1.43.0): New agent field recordingNotice (boolean) in POST/PATCH /v1/agents, MCP create_agent/update_agent and agent drafts (PUT /v1/agents/{id}/draft, save_agent_draft). The response always carries it (false when unset). The sentence is appended only with recordingNotice: true and recordCalls on; in a draft an absent key means unchanged. The greeting length estimate (first_message_too_long) counts the sentence only when it is on. This changes what recordCalls implies: recording alone no longer adds the sentence. It was removed on 22 Oct 2026 from existing agents that had it added automatically; a sentence written into firstMessage itself stays as it is.
• 22 Oct 2026 (1.42.3): An attempt's reservation (reservedBudgetHal, the item's estimatedCostHal) is the call leg plus the agent leg, each rounded up to a heller exactly as billing does (previously a single rounding of the combined rate, which came out one heller lower for some caps). A call with a duration cap (outbound task) is billed for min(durationSecs, maxDurationSecs); the stored durationSecs stays as measured. A transferred leg of such a call gets at most the remainder up to the attempt's highest price. An agent with recordCalls: false on volai's engine (provider: "engine") has no recording: hasRecording is false and GET /v1/calls/{id}/recording returns no_recording. Saving such an agent requires an engine that knows the flag; otherwise the engine write fails instead of recording silently.
• 21 Oct 2026 (1.42.2): checkCallRateLimit (POST /v1/calls, MCP make_call, outbound tasks) counts the attempts per 24 hours of a call covered by an agent's stored quota (call-quota:agent:{agentId}) or by the PetCenter campaign exception with a daily limit above 1,000 in its own counter ratelimit:callsday-agent:{userId}:{agentId} and compares them with the quota's daily limit. Calls with the default limits, calls without an agent (the website test call, bridge, relay) and calls with a quota that does not raise the daily limit (1,000 or less) still share the account counter ratelimit:callsday:{userId}; a call of the same agent outside the quota's scope (outboundTaskOnly, taskPurposes, after validUntil) follows the campaign exception when it applies, and otherwise uses the default limit of 1,000 and the account counter. The concurrency slots agentcallslot:{userId} (relay_lease_limit) and the per-minute counter ratelimit:calls:{userId} stay shared per account. The code rate_limited, HTTP status 429, the message texts and the default limits of 2 concurrent, 10 per minute and 1,000 per 24 hours do not change; only an admin stores a quota. resolveAgentCallLimitsWithSource in lib/service/call-quotas.ts returns the source of the limits (stored, campaign, default) next to them from a single quota read, and usesAgentDailyCounter picks the counter from them.
• 18 Oct 2026 (1.42.1): An inbound call that the voice engine turned away because the cap on concurrent calls was used up now has status: "missed", endReason: "capacity", durationSecs: 0 and priceHal: 0 in REST (GET /v1/calls, GET /v1/calls/{id}) and MCP (list_calls, get_call); no credit is charged. The call.missed webhook is sent once per call, and an SMS to the caller only for an agent with missedCallSms turned on (as for every missed inbound call); no summary e-mail is sent for it. When the carrier reported the unanswered call first, call.missed is sent at that moment (possibly without endReason) and the existing record is then completed with endReason: "capacity"; no second record and no second webhook are created. Until now such a call stayed in status: "in_progress" forever, because the engine sends no post-call for it. The record is now created by the reconciliation of engine calls, within a few minutes of the rejection. Existing stuck records from the last seven days that are older than two hours are closed retroactively by the hourly check, only with evidence from the engine's call log and without a webhook; if the carrier created its own record for them, they are merged into it. The values missed and capacity already existed in the enumerations, and the response shapes do not change. In the outcome filter (GET /v1/calls, list_calls) such a call counts as no_answer; for an outbound call nothing changes about capacity (relay pool full).
• 18 Oct 2026 (1.42.0): GET /v1/subscription and MCP get_subscription: recommendation has a new field steady, whether the spend is not just a one-off peak: usage over the last 14 Prague days scaled to 30 days, plus the monthly number fees of the 30-day window counted once, reaches at least the price of the recommended tier. The portal offers the plan personally and the MCP sentence suggests it only when worthIt and steady are both true; worthIt and the other fields do not change. The recommendation comes from one function for the portal, REST and MCP; for REST and MCP it is cached next to the credit runway (10 minutes, cleared by every credit movement). Nothing else in the API changes.
• 18 Oct 2026 (1.41.0): GET /v1/subscription and MCP get_subscription: new field previousPeriod, a summary of the paid period before the current one (subscription.periodStart) with the same figures as the renewal e-mail: tier, periodStart and periodEnd (ISO 8601), creditHal, usedHal, usedPercent (rounded down), overHal (spending beyond the monthly credit; with top-ups without debt that the next credit paid off, with the cap including debt; null when the credit history cannot prove it), expiredHal, exhaustionMode and exhaustedAt (ISO 8601, null when the credit did not run out or the history cannot show when). It is saved at every renewal, by card (also when the payment_intent.succeeded webhook completes it) or by a manual payment, and kept for 45 days; it is returned only while the plan is active, whatever available says, and is null without a plan, with status past_due or canceled, in the first period and when the usage cannot be proven. MCP get_subscription also adds a sentence about the last period with Prague dates. GET /v1/balance and MCP get_balance: on an active plan the notice {kind:"subscription_runway",renewsAt,runsOutAt} now computes runsOutAt from the plan's cautious pace, the same as the outlook on the plan card in the portal: the highest of the 28-day average (with a complete credit history), the average usage over the last 7 Prague days without number fees and the average since the current period started (after its first week), instead of the 28-day average. The shape and conditions of the notice do not change (nothing while auto top-up is on) and runway.dailyAverageHal and runway.runwayDays stay the 28-day average. The renewal e-mail for a renewal that the webhook completes now also leaves out the advice when a tier change is scheduled. Nothing else in the API changes.
• 18 Oct 2026 (1.40.1): POST /v1/outbound/dispatch-scopes/petcenter/registrations decoded the result of its Lua script with JSON.parse even when the default Upstash client (redis() with automatic deserialization; only redisRaw() has none) already returns it as an object. Every request therefore ended with the exception SyntaxError: "[object Object]" is not valid JSON and a 500 response. The exception happened after the script had run and before the result was mapped, so a newly stored registration (or a replay of the same operation) showed up as a 500 to the client, and a Lua refusal never reached it as 409 revision_conflict (operation_conflict, manifest_cas_conflict, task_changed_during_registration with error.details), 404 not_found or 400 validation. registerPetcenterDispatchScope now decodes the result with the helper decodeLuaJsonObject: JSON.parse only over a real string, and an object passes unchanged. A script reply that is not an object (valid JSON of another shape, or text that is not JSON) throws and the route answers 500, because the script may already have written the change and the outcome is uncertain; the client then asks for the operation result with GET /v1/outbound/dispatch-scopes/petcenter/registrations?operationId=.... An empty result still ends in registration_failed. The batch pause decodes its results with the same helper and its behavior and error message do not change. The contract does not change: request and response shapes, idempotency by operationId (replayed: true on a repeat), expectedManifestSha, the status codes and the providerActionStarted flag. The only client-visible difference is that the former 500 responses are now 200, 409, 404 or 400 according to the script result; 500 remains only for an unexpected shape of its reply.
• 18 Oct 2026 (1.40.0): GET /v1/subscription and MCP get_subscription: new field recommendation, or null (no plan offer for the account, or less than 30 Prague days of credit history). It holds spendHal (spend over the last 30 Prague days on calls, the agent, numbers and SMS, minus SMS refunds), days (30), cheapestPath (per_second or plan), tier and tierTotalHal (the cheapest tier with top-ups and its cost at that spend), savingsHal, worthIt (a saving of at least 50 CZK and 5%, the same threshold as the portal) and options (every way to pay for the same spend: {path, tier, totalHal} for paying by the second and for each tier). For a subscriber MCP get_subscription also adds a sentence with advice under the same rule as the portal and the e-mail. Nothing else in the API changes.
• 18 Oct 2026 (1.39.1): PUT /api/admin/call-quotas loads the agent (getAgent) and refuses the write when the agent does not exist or is deleted (404 agent_not_found), or when userId in the body is not the agent's owner (400 validation, the message does not reveal the real owner). A refused write stores nothing in call-quota:agent:{agentId}, in the index call-quota:index or in user:{userId}:admin-log. userId stays required in the body so the stored shape from GET can be sent back. The relay_lease_limit message when placing an agent call (POST /v1/calls, MCP make_call, outbound tasks) now reads This agent can have at most 3 running calls at once, and that many are already running on your account. Try again in a moment. (Czech: Tento agent může mít najednou nejvýš 3 běžící hovory a tolik jich teď na tvém účtu už běží. Zkus to za chvíli znovu.; the Czech noun and adjective agree with the count: 1 reads běžící hovor, 2 to 4 běžící hovory, 5 or more běžících hovorů). The number is the threshold of the calling agent from resolveAgentCallLimits (a stored quota, otherwise the default 2, after the pool clamp); the running calls come from the account-wide counter agentcallslot:{userId}, so a slot may be held by another agent of the same account. Before, the message said the maximum was per account although the agent decides the threshold, and the Czech text used the same plural form for every count. The code relay_lease_limit, the HTTP status 400, the counter, the threshold and the way outbound tasks wait on this code do not change. The history table heading on the customer detail page in the admin is now Admin action history (Historie admin akcí), the rows do not change.
• 18 Oct 2026 (1.39.0): New admin endpoint GET/PUT/DELETE /api/admin/call-quotas (admin session, not an API key; writes check the Origin) stores an agent's quota in call-quota:agent:{agentId}: concurrent 1 to 30, perMinute 1 to 60, daily 1 to 20,000, a mandatory note, outboundTaskOnly and the optional taskPurposes (standard, coupon_reminder) and validUntil (milliseconds since the epoch). Every change is written to user:{userId}:admin-log as call_quota_set or call_quota_deleted. resolveAgentCallLimits in lib/service/call-quotas.ts applies it ahead of the PetCenter exception and the default { concurrent: 2, daily: 1000, perMinute: 10 }, only for the same account, an outbound task (when outboundTaskOnly is set), an allowed purpose and a time before validUntil. Concurrency is clamped to min(stored, max(2, number of distinct names in ODORIK_RELAY_NAMES - 2)), the per-minute and daily limits are not. Without a stored quota behaviour is unchanged. Placing a call on a relay name waits for its turn (one shared pointer in Redis, spacing RELAY_PLACEMENT_GAP_MS 3 s, at most RELAY_PLACEMENT_MAX_WAIT_MS 10 s; on a Redis outage the call is placed at once and relay placement spacing unavailable is logged): agent calls (POST /v1/calls, MCP, tasks) and trial calls on the engine and on ElevenLabs, the transfer bridge claim for at most 4 s; not the BYO relay lease (POST /v1/relay) and not callback calls without a relay name. POST /v1/calls and a trial call can therefore take up to 10 s longer during a burst of calls; maxDuration is 100 s for POST /v1/calls and 70 s for POST /v1/agents/{id}/test-call. The outbound task tick starts no further task after TICK_DISPATCH_BUDGET_MS (90 s), the rest waits for the next run. An engine rejection because of the concurrent-call cap carries Retry-After: 30, which volai already forwards (retryAfterSecs, the Retry-After header, items[].nextAttemptAt): once the engine with this cap is deployed, contacts wait 30 s instead of 5 minutes; an engine without the header still means 300 s.
• 18 Oct 2026 (1.38.3): No change in API behaviour. The plan offer is on for every account (PAUSAL_MODE=on), so GET /v1/subscription returns available: true; pausal_unavailable (404) remains for when the offer is switched off. The documentation (/en/docs/credit, SKILL.md, llms.txt) no longer says the plan is limited to some accounts and describes renewals as hourly.
• 18 Oct 2026 (1.38.2): agentCallLimits in lib/service/call-quotas.ts keeps returning { concurrent: 6, daily: 6000, perMinute: 15 } after CAMPAIGN_QUOTA_EXPIRES_AT (2026-10-31T23:00:00Z) when the quota context carries the new optional taskPurpose: "coupon_reminder" and petcenterReminderQuotaActive() holds, that is, the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch is on and the time is before PETCENTER_REMINDER_DISPATCH_END (2026-11-05T19:55:00+01:00, 18:55 UTC; the constant moved into call-quotas.ts and the dispatch tick reads it from there). makeAgentCall passes the purpose to the quota only after it has verified the link to an approved reminder. A call without a purpose gets the default { concurrent: 2, daily: 1000, perMinute: 10 } after 31 October. The other conditions (the exact account, agent and internal outbound-task context match and at least eight distinct ODORIK_RELAY_NAMES) apply to reminders as well; the main campaign still dials nothing after 31 October, petcenterCampaignQuotaActive and the tick logic are unchanged. API behaviour for other accounts is unchanged.
• 18 Oct 2026 (1.38.1): GET /v1/balance and MCP get_balance: an eighth notice shape {kind:"subscription_runway",renewsAt,runsOutAt} (at the recent pace the balance runs out before the renewal; returned to subscribers instead of {kind:"runway"}, nothing while auto top-up is on). POST /v1/subscription/checkout and MCP create_subscription_link: consumerConsent is ignored for an account with a company ID, VAT ID or company name (Stripe metadata get 0); a consumer without a company ID still gets a confirmUrl. Nothing else in the API changes.
• 17 Oct 2026 (1.38.0): New REST endpoints: GET /v1/subscription (response {subscription, tiers, topupBalanceHal, available}; subscription is null without a plan, tiers lists {id, priceHal, creditHal} in hellers excluding VAT, available says whether a plan can be started on the account), POST /v1/subscription/checkout (body {tier, exhaustionMode, consumerConsent?} where tier is "490", "990" or "1990" and exhaustionMode is topup or cap with no default; returns {checkoutUrl}, nothing is charged until a person pays in Checkout; an account without a company ID must send consumerConsent), PATCH /v1/subscription (body {tier?, cancelAtPeriodEnd?, exhaustionMode?}), POST /v1/subscription/pay (a Checkout link to pay a failed renewal by hand, only in status past_due, otherwise invalid_state) and POST /v1/subscription/card (a Checkout link in setup mode to replace the saved card, nothing is charged); the POST endpoints accept Idempotency-Key. PATCH applies a lower tier (from the next period), cancelAtPeriodEnd: true and exhaustionMode: "cap" at once and returns {subscription}; a higher tier, cancelAtPeriodEnd: false (resuming a plan set to end) and exhaustionMode: "topup" change nothing and return 409 subscription_confirmation_required with a confirmUrl (single use, valid for 24 hours) that a person must open and confirm in the portal. The subscription object carries tier, status (active, past_due or canceled), periodStart and periodEnd as ISO 8601 strings (unlike ts in the ledger, which is epoch milliseconds), monthlyCreditHal, monthlyRemainingHal, exhaustionMode, cancelAtPeriodEnd, nextTier and card (brand, last4). GET /v1/balance and the MCP tool get_balance now also carry subscription (null without a plan) and topupBalanceHal (top-up credit alone, negative when the account is in debt); balanceHal is still the total of both. The ledger (GET /v1/credit/ledger, MCP list_ledger) has two new type values, subscription_grant and subscription_expire; a ledger entry for a charge covered by the monthly credit also carries fromSubscriptionHal (the part the monthly credit paid), other entries do not have the field. Five new MCP tools: get_subscription, create_subscription_link, update_subscription, cancel_subscription and create_subscription_payment_link; replacing the card stays REST and portal only. New error codes: 402 subscription_cap_reached (returned instead of insufficient_credit by calls, test calls, gate rings, SMS and purchases of numbers, SMS numbers and relay leases when the plan runs with exhaustionMode: "cap", the monthly credit is used up and the remaining credit does not cover the action), 409 subscription_exists, 404 subscription_missing, 409 subscription_canceled, 409 subscription_confirmation_required, 400 consumer_consent_required, 404 pausal_unavailable (the offer is not enabled for the account), 400 invalid_tier and 409 subscription_cap_active (auto top-up cannot be turned on while the plan runs with the cap); the confirmation page in the portal (not REST) can also end in the state confirm_invalid, confirm_expired or confirm_used. Once the offer is on for an account, the portal shows a plan card on the Credit page and pages to start or change the plan and to confirm a confirmUrl link. Accounts without a plan see no change in existing fields, statuses or codes.
• 16 Oct 2026 (1.37.5): The engine sends rationale and reason as null in every item of analysis.evaluation_criteria_results when they have no value. The post-call webhook schema rejected null and dropped the evaluation of all criteria, so goal in GET /v1/calls, GET /v1/calls/{id} and in the MCP tools list_calls and get_call was null for calls on the engine, the goal filter counted them as not_evaluated and the after-call e-mail had no goal line. The schema now treats null as a missing field for every optional field where null means nothing, and a malformed evaluation item drops only itself. Where null carries meaning (for example recording_url: null = a call without a recording), it stays. No field or endpoint changes. Calls from 16 September to 16 October 2026 do not have an evaluation yet.
• 15 Oct 2026 (1.37.4): Three new agent fields turnDigitTailFloorMs, turnLongSpeechFloorMs (integer, 0 = off, otherwise 400 to 2300 ms; the gap 1 to 399 returns validation) and turnLongSpeechSecs (1 to 30, decimals allowed) on POST /v1/agents, PATCH /v1/agents/{id} (a number sets it, null removes the stored value, an omitted key leaves it unchanged), GET /v1/agents and GET /v1/agents/{id} (always present, a number or null when not set, the engine uses its defaults 0 / 0 / 5), in the draft snapshot (PUT/GET /v1/agents/{id}/draft; an absent key means unchanged, null removes it) and in the MCP tools create_agent/update_agent/save_agent_draft. They are sent to the engine in the turn block as digit_tail_floor_ms, long_speech_floor_ms and long_speech_secs on EVERY save of the agent (the engine does not carry the fields over from the previous version; a missing value goes as the engine default) and the read-back compares them (engine contract ch. 3.5af and 3.5ag). Stored for either provider, read only on the engine in smart_turn mode; ElevenLabs ignores them. Engine guidance: step 1 = 800 for Czech agents that take dictated numbers, step 2 = 1200, practical ceiling 1500; dates, postcodes and years get the floor too. The counters of applied floors stay in the engine (its dump and GET /v1/calls), they are not in volai webhooks. In the portal, the "End of reply" card in the Advanced tab.
• 15 Oct 2026 (1.37.3): New agent field sttLanguageHintsStrict: boolean on POST /v1/agents, PATCH /v1/agents/{id} (true turns it on, false or null turns it off, an omitted key leaves it unchanged), GET /v1/agents and GET /v1/agents/{id} (always a boolean, false when not set), in the draft snapshot (PUT/GET /v1/agents/{id}/draft; an absent key means unchanged, null turns it off) and in the MCP tools create_agent/update_agent/save_agent_draft. It is sent to the engine as stt.language_hints_strict on EVERY save of the agent (the engine does not carry the field over from the previous version) and the read-back compares it. Stored for either provider, read only by the engine (Soniox); best effort, only for engine agents with language cs and outbound calls, never for sk. The call detail GET /v1/calls/{id}, MCP get_call and the call.completed webhook (and call.failed with endReason: "engine_error") carry a new engine: { protectedUtterances: [{ timeInCallSecs?, atSecs, message, words, reason }], protectedUtterancesCount } block - utterances of the person who answered that the engine dropped during the greeting window (metadata.engine.protected_utterances from the engine post-call, contract ch. 3.5ae): not in the transcript, the agent did not react to them; reason is first_message_protect, greeting_courtesy or greeting_identification (open list), at most 10 items, message up to 200 characters, the count covers them all. The block is present only on engine calls from the 15 Oct 2026 build on ([] and 0 when nothing was dropped); older calls, the GET /v1/calls list and agents on ElevenLabs do not have it. In the portal a switch on the Advanced tab and a "What the person said during the greeting" card in the call detail.
• 15 Oct 2026 (1.37.2): cdr-sync: the second leg of an answered ring (same from/to, different active_call_id, starting shortly after the first leg, first leg answered) is matched to the same kind: "ring" record without the per-attempt fee; seconds are billed only when length > 0. The ring.rangSecs description in OpenAPI and the docs: the carrier's figure is usually 1 to 3 s above ringSecs. No field or endpoint changes.
• 15 Oct 2026 (1.37.1): New optional agent field inboundVariables: Record<string, string> on POST /v1/agents, PATCH /v1/agents/{id}, GET /v1/agents and GET /v1/agents/{id}, in the draft snapshot (PUT /v1/agents/{id}/draft, GET .../draft) and in the MCP tools create_agent/update_agent/save_agent_draft: default values for {{variable}} placeholders on INBOUND calls. The initiation webhook merges them into dynamic_variables only for names the call does not supply itself (caller_number, called_number, attempt_id, volai_*, trial_* and system__* take precedence and validation rejects such names); outbound calls (POST /v1/calls, relay, tasks) do not use them. At most 10 keys matching [A-Za-z0-9_]{1,40}, values are trimmed strings up to 200 characters. On PATCH an object replaces the stored values entirely, null or {} removes them and an omitted key leaves them unchanged; the response omits the key when the agent has none. In a draft an absent key means unchanged. The prompt_variables_unavailable_inbound and first_message_empty warnings skip a variable that has a default. Works for either provider - the engine and ElevenLabs read the same webhook.
• 15 Oct 2026 (1.37.0): New POST /v1/rings with body {to, from?, ringSecs?} (from = your active volai number, defaults to the first number of the account; ringSecs 3 to 30, default 10) replies right after the carrier accepts the order with {id, status: "initiated", kind: "ring", from, to, requestedSecs, priceHal}. The result arrives by webhook (call.no_answer for rang and ended_early, call.completed for answered) and in GET /v1/calls/{id} (also with ?waitSecs=) in the new ring: {requestedSecs, outcome, rangSecs} block; outcome is rang, ended_early, answered or unknown. kind has the new value ring; the body of every call webhook now carries kind and, for rings, the ring block. MCP tool ring_number takes the same fields. Limits: 30 rings per minute and 500 per day per account, 120 per hour per target; the manual do-not-call list applies, the automatic 30-day block is neither applied nor fed. Idempotency-Key is supported. New error code: ring_needs_number (account without an active number).
• 13 Oct 2026 (1.36.2): PATCH /v1/numbers/{e164} and MCP set_number_routing return validation when routing.mode is sip, sipUri points at <credentialId>.sip.vapi.ai or <credentialId>.sip.eu.vapi.ai, and sipUsername with sipPassword are sent or stored from before. A Vapi BYO trunk recognises our calls by the IP in its gateways (IP 81.31.45.0, netmask 24) and does not connect authenticated routing. Vapi's native SIP numbers (sip:<name>@sip.vapi.ai) are not affected. A number that already has such routing stored is fixed by sending both fields as empty strings. The set_number_routing description and the /en/integrations/vapi, /en/docs/bring-your-own-agent and /en/docs/sip pages say so; for a failed call to a Vapi BYO trunk, the portal points at the login fields, the gateways and the region.
• 13 Oct 2026 (1.36.1): An outbound agent call through the relay whose route never reached the carrier (the routing webhook did not answer within five seconds) still has status: "no_answer", but now endReason: "rejected" instead of "no_answer", and it does not count towards the automatic destination block (3 failures in 24 hours). In tasks such an attempt has countsAsAttempt: false and errorCode: "relay_not_routed", uses up neither maxAttempts nor the lorela_enterprise schedule, and the contact gets nextAttemptAt no sooner than 60 seconds later. After the third such attempt in a row the contact goes to review with reviewReason: "call:relay_not_routed".
• 12 Oct 2026 (1.36.0): The new internal POST /v1/outbound/dispatch-scopes/petcenter/registrations accepts a durable operationId, manifest SHA-256 and ordered task IDs. The first manifest is pinned to the approved 19-task list; later manifests can only append. GET returns registration state and operation readback. The new /api/cron/outbound-tasks/petcenter cron uses a separately and fairly rotated queue; the general cron and atomic claim both enforce separation. Limits of 6 concurrent calls, 15 attempts per minute and 6,000 per day remain unchanged. GET /v1/tasks?ids=id1,id2 reads one to five selected tasks owned by the authenticated account, reports subset completeness and rejects responses over 4 MiB. POST /v1/outbound/dispatch-scopes/petcenter/pauses safely pauses up to five registered tasks with revision checks; GET returns durable outcomes and an input hash for safe reconciliation.
• 11 Oct 2026 (1.35.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take two new fields: firstMessageProtectSecs: number | null (0 to 20 seconds, decimals allowed, outbound calls only; while the first line plays, a short reaction from the person who answered does not interrupt it: a reply without an interrupting word (for example stop, no, wait) is dropped in the protected window, so it does not interrupt the line, is not in the transcript and the agent does not react to it, while an interrupting word always interrupts it; the interrupting words follow the agent's language, so an English agent is interrupted by stop, no, wait or hold; null or 0 turns the protection off) and silencePromptText: string | null (your own silence reminder sentence, up to 80 characters, spoken word for word instead of the default reminder for the agent's language ("Are you still there?" in English); an empty string or null restores the default text). Unlike silencePromptSecs, WITHOUT a forced default: a missing field on POST is not stored, GET /v1/agents returns it as null for an older agent, and a PATCH without the key leaves the stored value alone, so nothing changes for existing agents. Both fields are accepted and stored for EITHER provider, but only heard on an agent running on volai's own engine. A value outside the bounds fails with the generic validation error (validation, 400), no new code. A transcript turn (transcript[] in GET /v1/calls/{id}, MCP get_call and the call.completed webhook) carries an optional interrupted: true on an agent line the caller interrupted, with message still the full planned text; it is absent on calls handled by ElevenLabs and on calls without an interruption.
• 10 Oct 2026 (1.34.5): GET and POST /v1/sms-numbers and the MCP tools list_sms_numbers and buy_sms_number return dailySendLimit for each SMS number (20 SMS per 24-hour window during the number's first 30 days, 50 after that), dailySendRemaining (0 for a number being released) and dailySendResetsAt (Unix ms when the window ends, null when none is running). The window starts with the first SMS from any SMS number of the account, is shared by all of them and also counts attempts over the limit and SMS the carrier rejected. The message.sent webhook body has a new smsNumber field: the E.164 SMS number for a message sent from an SMS number, null for the shared sender SMSinfo. The internal_error and send_failed_operator messages for SMS now say "The error is on our side and we know about it", sms_number_out_of_stock no longer promises a restock and the rate_limited message for a used-up SMS number limit says how long until the window ends; error codes do not change. In the portal the /en/messages form shows the limit of the selected SMS number and the SMS messages card on the overview also counts received SMS.
• 10 Oct 2026 (1.34.4): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 6, daily: 6000, perMinute: 15 } for the campaign scope; the condition of at least eight distinct ODORIK_RELAY_NAMES stays and guarantees two free names for other callers. The account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged; API behaviour for other accounts is unchanged.
• 10 Oct 2026 (1.34.3): The action for send_unknown no longer says that unknown is always final: for an SMS sent from an SMS number it can still change on its own to sent with a deliveryStatus, or to failed with the credit refunded; for an SMS from the shared sender SMSinfo it stays final. The action for rate_limited no longer promises a Retry-After header in every case: the daily cap for sending from an SMS number (20 SMS a day per account during the first 30 days after buying the number, 50 after that) resets the next day, and a number purchase already running finishes within seconds. POST /v1/messages lists blocked_destination (400, premium-rate numbers) among its errors. Messages received on an SMS number have source: "inbound", the received-message list holds at most the 1,000 newest messages per account, and the message.received webhook is not sent above 300 received messages per hour on one number (the messages are still stored). In message.received, from is an E.164 number or a text sender name (at most 32 characters); a message that was not picked up at once is added by a periodic check within about 15 minutes and its event then arrives late. Neither the delivery report (deliveryStatus) nor a late failed triggers an event; read them from GET /v1/messages/{id}. Releasing an SMS number is not available over MCP, only in the portal and with DELETE /v1/sms-numbers/{e164}.
• 9 Oct 2026 (1.34.2): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 8, daily: 6000, perMinute: 15 } for the campaign scope; the account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged. The rate_limited message for the daily limit now says 6000.
• 9 Oct 2026 (1.34.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-10-31T23:00:00Z; the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, the exact account, agent and internal outbound-task context match and at least eight distinct ODORIK_RELAY_NAMES still apply. API behaviour for other accounts is unchanged.
• 9 Oct 2026 (1.34.0): New endpoints GET /v1/sms-numbers, POST /v1/sms-numbers (no body, Idempotency-Key supported, returns 201) and DELETE /v1/sms-numbers/{e164} (irreversible, the paid period is not refunded), and MCP tools list_sms_numbers and buy_sms_number (confirmedMonthlyFeeHal must equal the current fee in hellers, otherwise nothing is bought). GET /v1/messages and MCP list_messages take direction (out by default, in, all) and also return messages received on an SMS number; messages now carry direction, smsNumber and deliveryStatus (delivered or undelivered, only for SMS sent from a number), status has a new value received and failReason a new value opted_out. POST /v1/messages and MCP send_sms take fromNumber (an active SMS number of the account; Czech +420 recipients only; 1.90 CZK per segment). New webhook event message.received with {id, from, to, body, segments, receivedAt} (receivedAt is Unix ms); the text of a received SMS is untrusted third-party content and MCP marks it with securityNotice. Received SMS are kept for 90 days. New error codes: sms_numbers_unavailable, sms_number_limit, sms_number_out_of_stock, invalid_from_number, from_number_unsupported_destination and recipient_opted_out; the existing codes recipient_rejected, sms_gateway_failed, recipient_is_virtual_number (an SMS from the shared sender to a volai SMS number) and release_failed also apply to SMS numbers. The message from field is still the internal label volai for a message sent without fromNumber, the SMS number itself for one sent from it, and the sender for a received message.
• 8 Oct 2026 (1.33.0): The callback-routing policy accepts an optional missedFirstMessage (up to 500 characters): it replaces firstMessage when the verified preceding outbound call had no conversation with the customer (not answered, voicemail, voice menu, nobody spoke, or the call is not closed yet). Initiation sends the engine volai_callback_kind (missed/contacted) next to volai_call_mode=campaign_callback. The engine post-call may carry caller_optout_requested (outbound calls only): the call then exposes optOutRequested: true in the list and detail, the called number is added to the account's do-not-call list (GET /v1/dnc) and the lorela_enterprise policy schedules no further attempt for that item. An engine call with answered_by: unknown stays unknown - the portal no longer guesses a voicemail from a short reply ("Yes." after the intro), so hasConversation of such a call follows the transcript; a voicemail detected by the engine (voicemailReason present) gets another attempt under the lorela_enterprise policy despite the carrier greeting in the transcript. New reason voicemailReason: digits (a carrier greeting reading the called number digit by digit). Everything is additive; existing policies, calls and tasks are unchanged.
• 8 Oct 2026 (1.32.1): The message from field stays the internal label volai, and OpenAPI now describes it; the source field description says the value inbound never occurs for messages. The MCP server instructions, SKILL.md and the llms files say the same. API behaviour is unchanged.
• 8 Oct 2026 (1.32.0): Save an explicit allowlist of owned active engine agents for returning callers with a unique real outbound call from this number within lookbackSecs (60-604800 seconds). Unknown, ambiguous or unverified callers keep the default agent. Empty agentIds disables the policy. Optional firstMessage applies only to verified callbacks. engineSyncRequired: true means the default agent engine configuration must separately activate webhooks.inbound_route_url with readback; this request does not rewrite live engine configuration. Verified incoming calls expose callbackOf.callId and optional server-owned taskId and taskItemId in call details. New REST GET/PUT /v1/numbers/{e164}/callback-routing and MCP get_callback_routing / set_callback_routing. Signed incoming tool context carries direction=in and empty dispatch/task/item fields. Server-owned volai_call_mode=campaign_callback is set only for verified callbacks. Verified inbound human contact stops later scheduled retries of the same task item without creating an outbound attempt or charge. An already running call and its billing finish normally. The server-owned dispatch/task/item binding is retained for eight days to cover the callback window.
• 8 Oct 2026 (1.31.0): POST /v1/tasks, PATCH /v1/tasks/{id}, create_task and update_task accept optional retryPolicy: "lorela_enterprise" and expiresAt (positive safe-integer Unix milliseconds); both fields are returned in the public task. Without a policy, maxAttempts remains 1-3 with a creation default of 1; with the policy it is 1-4 with a creation default of 4. PATCH without a limit preserves it. The policy can be enabled only before the first dispatch attempt. The second attempt is no earlier than eight minutes after the first real attempt starts, within 08:00-22:00 Europe/Prague; the third uses the next other 08:00-09:00 or 17:00-19:00 window; the fourth uses the opposite window on the following calendar day. A narrower callingWindow, including weekdays, still applies. Only no_answer, missed, busy or completed voicemail without human contact can retry; uncertain results and engine failures need review. The policy rejects manual resolve with action: "retry" and stops calling five days after the first real attempt. expiresAt also works without a policy and prevents any new dial at or after the deadline, including the first attempt; a call already in progress finishes normally. DNC and automatic blocking after three failures within 24 hours are not bypassed, so the fourth attempt is not guaranteed.
• 5 Oct 2026 (1.30.2): A call for which the engine does not send caller_loop in the post-call (the caller first talked to the agent and only afterwards just a repeated message was left on the line) has endReason: "completed" and the regular price, like any other completed call. The fallback sync of a lost post-call (the engine's GET /v1/calls) now reads metrics.caller_loop_reported: the value 1 means the engine sent caller_loop in the post-call, and caller_loop is taken over as before; the value 0 means an ordinary call, which is closed and billed with endReason: "completed" regardless of metrics.caller_loop_released. For an older engine without this field, the existing rule with metrics.caller_loop_released applies (a positive value means an ordinary call). REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.1): endReason: "caller_loop" and priceHal: 0 are now given only to an inbound call with a positive durationSecs; an outbound call, or a call with zero duration, for which the engine sends termination_reason: "caller_loop" takes the regular path (endReason: "completed" and regular billing; a zero-duration call stays unclosed as before). The fallback sync of a lost post-call (the engine's GET /v1/calls) takes over caller_loop only when metrics.caller_loop_released is missing or 0; with a positive value (a person spoke up during the wait) the call is closed and billed like any other completed call with endReason: "completed", and call.completed carries the price, the same as when the post-call arrives on its own. A call with endReason: "caller_loop" is never listed in the portal among calls needing attention (Overview and the Calls filter), and the weekly e-mail summary does not count it as a handled call or a caller and does not list it among calls that need a reaction. REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.0): New endReason: "caller_loop" value (REST GET /v1/calls and GET /v1/calls/{id}, MCP list_calls and get_call, webhook call.completed): an inbound call whose caller was an automated system repeating the same message (a queue, a dialer), ended by the engine's guard. The source is metadata.engine.termination_reason: "caller_loop" in the engine's post-call (for a lost post-call, the same field from the engine's GET /v1/calls). The call has status: "completed", a positive durationSecs and priceHal: 0, and no credit is charged; the price of 0 applies up to five minutes of call duration - a longer call is billed at the regular rates and keeps endReason: "caller_loop". The call.completed webhook carries endReason: "caller_loop". A call where a person spoke up during the wait and the engine carried on with them does not get caller_loop. In the outcome filter (GET /v1/calls, list_calls) such a call counts as agent.
• 4 Oct 2026 (1.29.6): PATCH /v1/agents/{id}, update_agent and draft publish: changing language from a language in which new agents start on ElevenLabs (today en, de, pl) to one in which they start on the engine (cs, sk) triggers, for an agent with provider: "elevenlabs", the same post-save engine switch attempt as turning on transferTo. On success the agent has provider: "engine" and the engine's default voice for the new language (milena, katarina); on failure it stays on ElevenLabs. A change between cs and sk moves nothing. voicemail_requires_engine has new wording: on creation it points to useForOutboundTasks: true, on an existing agent to support.
• 4 Oct 2026 (1.29.5): POST /v1/agents and create_agent return a new code elevenlabs_by_explicit_choice ({code, message: {cs, en}}) in warnings when the request sent useForOutboundTasks: false, the deployment default would have picked the engine for the agent's language, and the agent really stayed on ElevenLabs (a transferTo handoff may have switched it to the engine). The agent is created as before and the code blocks nothing. PATCH /v1/agents/{id}, draft publish and rollback never return it.
• 3 Oct 2026 (1.29.4): Documentation only, the API behavior does not change. maxAttempts (1-3) is the highest number of automatic dials of one contact, the first call included; 1 means no retries. A contact that you give resolve with action: "retry" after its attempts are used up gets one more dial. Every attempt where the call could have happened counts (unanswered, declined by the person called, or with an uncertain result). An attempt rejected before dialing does not count and has items[].attempts[].countsAsAttempt: false.
• 3 Oct 2026 (1.29.3): For attempts recorded from this version on, items[].attempts[].countsAsAttempt is false for every code where the call provably never happened, so they do not count toward maxAttempts: agent_not_found, agent_no_number, insufficient_credit, invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, capacity_busy, call_rejected, validation, rate_limited, relay_lease_limit, invalid_workflow, engine_not_configured and destination_busy. Previously the permanent problems with the number (invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number) were counted, so after lifting a block and another rejection a contact showed more attempts than allowed although nothing was dialed. Attempts written before this version are not rewritten retroactively (the exception is an attempt whose dial intent the accounting repair closes). Uncertain dial errors (for example engine_unavailable) still count, because the call may have happened. A permanent problem still sends the contact to review (you decide), a repairable code (missing credit, an agent without a number and the like) pauses the task; rate_limited and relay_lease_limit leave the task running and only wait. Nothing is dialed in a loop because of this. A contact you return via resolve with retry after its attempts are used up now stays pending after a repairable dial error without a call (for example insufficient_credit) and is dialed again once the cause is fixed; before, it stayed failed and the task could not be started (task_not_startable).
• 3 Oct 2026 (1.29.2): destination_busy while dialing from a task (the call provably never happened): the contact keeps waiting (failed when it already had a counted attempt and has another free one, otherwise pending) with items[].lastError: "destination_busy" and items[].nextAttemptAt from the remaining time of the number lock (at least 30 s, at most 16 min, 90 s without a lock), the attempt has countsAsAttempt: false, the reservation in reservedBudgetHal is released and the other contacts keep running; the task's lastError is not set, only a stale waiting rate_limited or relay_lease_limit is cleared, because a busy result proves the limit passed. After the 6th busy result in a row (5 waits) the contact goes to review with reviewReason: "dial:destination_busy". The seven permanent codes (on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, invalid_number, unsupported_country, blocked_destination) send the contact to review with reviewReason: "dial:<code>", but the task stays running and moves to needs_attention only when no other work is left (previously immediately). Over the API and MCP a block is lifted with two calls: POST /v1/dnc/{e164}/unblock (unblock_destination), then resolve with action: "retry" (resolve_task_item); for your own number, a number of another volai account, an invalid number, a number outside Czechia and Slovakia and a premium-rate line only skip helps. A contact in review can now appear while the task is still running; resolve then returns 409 task_not_editable, so wait for needs_attention or pause the task. POST /v1/calls does not change.
• 2 Oct 2026 (1.29.1): items[].providerCallId points only to the call of the latest attempt: a contact in failed that is waiting for another attempt does not carry it; the call of every attempt stays in items[].attempts[].providerCallId. Previously the item kept the call of the first attempt, the next dialed call was not recorded on the task, and the contact was dialed again without counting the attempt and without adding the price to spentHal. The errors on_dnc, destination_auto_blocked, cannot_call_own_number and cannot_call_volai_number while dialing from a task are provably no call: the attempt gets outcome: "failed", the reservation in reservedBudgetHal is released right away and the contact goes to review with reviewReason: "dial:<code>" (previously outcome: "unknown" and a held reservation). POST /v1/tasks/{id}/start no longer returns 409 task_needs_attention because of a reservation that no contact holds; POST /v1/tasks/{id}/reconcile settles such a reservation and also closes an older open dispatch intent left after an attempt that was never dialed.
• 2 Oct 2026 (1.29.0): New endpoint POST /v1/numbers/orders/{id}/cancel (no body) and MCP tool cancel_number_order: a pending order moves to the new status cancelled (a new status value of the order in GET /v1/numbers/orders and list_number_orders); provisioning returns 409 in_progress, done and failed 409 invalid_transition, a foreign or unknown id 404 not_found; cancelling again returns the order unchanged. A cancelled order no longer counts toward the first top-up gate (one number per account without a top-up). callingWindow.end of tasks is inclusive of the whole minute (current <= end): a 00:00-23:59 window covers the whole day and window_closed no longer occurs in the end minute itself.
• 30 Sep 2026 (1.28.1): PATCH /v1/numbers/{e164} (MCP set_number_routing) with mode: "forward" returns 402 insufficient_credit when the account has never topped up and the number is not forwarded yet. A number that is already in forward can be pointed at a different target without a top-up. POST /v1/numbers (MCP buy_number) and POST /v1/numbers/orders (MCP order_number_from_region) return 402 insufficient_credit when asked for an additional number while an account without a top-up already holds an active number or has an open order (pending, provisioning). Same code and cause (account) as for SMS, different message text - it says what to do (make the first credit top-up); nothing is charged. After the first credit top-up (card, auto top-up) the restriction is gone.
• 25 Sep 2026 (1.28.0): New suspended: boolean field on the agent object (REST and MCP, GET/POST/PATCH /v1/agents). New error codes agent_suspended and account_suspended (403, cause: "account") - account_suspended on every REST call with an API key and every MCP tool (after the rate limit) except reading tax documents (GET /v1/billing/documents, /{id} and /{id}/pdf, the MCP tools list_billing_documents and get_billing_document), which stay available; agent_suspended on POST /v1/calls, POST /v1/agents/{id}/test-call and POST /v1/tasks/{id}/start. An inbound call blocked by a suspension of the agent or the account carries endReason: "suspended" (a new value next to credit_blocked, price 0). An account_suspended/agent_suspended response is never stored under an Idempotency-Key, so the same key succeeds once restored. Custom variable keys (variables on POST /v1/calls and make_call) can no longer start with the volai_ prefix - it is reserved for variables volai fills in itself (such as volai_block_reason), and such a request returns 400 validation; in tasks, such a key is only refused when the contact is dialed. Suspending and resuming is done only by the operator in the admin panel - there is no REST or MCP tool for it. The sentence a caller hears on a blocked line (debt or suspension) is now spoken in the agent's language (cs, sk, en, de, pl).
• 25 Sep 2026 (1.27.3): No interface change: the same warnings code agent_misuse_suspected in the same REST and MCP responses, only broader recognition.
• 24 Sep 2026 (1.27.2): Outbound tasks: relay_lease_limit from dialing (the quota of 2 concurrent agent calls per account) now behaves like rate_limited - the task stays running, sets lastError: "relay_lease_limit", the attempt does not count (countsAsAttempt: false) and waiting contacts get items[].nextAttemptAt one minute later. Previously the item went to review with reviewReason: "dial:relay_lease_limit" and the task to needs_attention. The engine sync (GET /v1/calls) reads the new attempt_id field of an outbound call and uses it to match an initiated record after an uncertain dial (no call_sid, also for an agent without its own number); once matched, call.completed is sent with the price and the relay line and quota are released. Requires an engine that lists attempt_id; an older listing behaves as before.
• 24 Sep 2026 (1.27.1): POST /v1/calls with agentId on an agent on volai's own engine, a trial call with systemPrompt, MCP make_call and outbound tasks: when dialing on the engine ends with a timeout, a dropped connection, a 500/504 response or an unreadable 2xx, the response is still 502 engine_unavailable, but the call stays initiated (no priceHal), the relay line is not released and the same to stays locked for 15 minutes (destination_busy); the concurrent call quota is released right away. If the call happened, the post-call or the engine sync fills in the outcome and price (the post-call now finds it by the attempt identifier even without a call_sid, including agents without a number of their own) and call.completed is sent; if not, the watchdog closes it after 2 h as failed with priceHal: 0. The call.failed webhook is not sent for an uncertain dial. A certain failure (no connection to the engine at all or a timed-out connection attempt, 4xx, 502/503) behaves as before: failed, priceHal: 0, call.failed.
• 24 Sep 2026 (1.27.0): New warnings code agent_misuse_suspected ({code, message: {cs, en}}). Appears in POST/PATCH /v1/agents, PUT /v1/agents/{id}/draft, POST /v1/agents/{id}/simulate, POST .../draft/publish, POST .../draft/rollback, POST /v1/calls (the trial call prompt or variables), POST/PATCH /v1/tasks, POST/PATCH /v1/tools and the matching MCP tools (create_agent, update_agent, save_agent_draft, simulate_agent_draft, publish_agent_draft, rollback_agent_draft, make_call, create_task, update_task, create_tool, update_tool). The warnings field is optional, absent when there is nothing to flag, and /openapi.json describes it on all of these responses.
• 24 Sep 2026 (1.26.3): POST /v1/calls with from (bridge) and MCP make_call: when the connection order to the phone operator ends with a network error, a timeout or a 429/5xx response, the call is returned as a success with status: "initiated" instead of 502 callback_failed and stays initiated until cdr-sync pairs it with the CDR (and bills it), or the watchdog closes it after 24 h as failed with priceHal: 0. callback_failed now means only a provable rejection by the operator (an error response or 4xx). The call.failed webhook is not sent for an uncertain order; the same to number stays locked for about 10 minutes (destination_busy).
• 24 Sep 2026 (1.26.2): The per-account cap on calls within 24 hours (shared by POST /v1/calls with an agent or a bridge, relay and trial calls, MCP make_call and outbound tasks) is now 1000 instead of 200. Exceeding it still returns 429 rate_limited with the daily-limit message; 10/min, concurrency and the engine budget are unchanged.
• 24 Sep 2026 (1.26.1): Outbound tasks: a call record in failed with no conversationId and no priceHal (the engine refused or did not confirm the dial) now settles at 0 in reconcile - previously the item kept reviewReason: "billing_unknown" and the task stayed needs_attention forever. resolve with skip on a billing_unknown item moves a task with remaining work to paused (the original call's reservation keeps counting in reservedBudgetHal, and start accepts it); retry still waits for the price. A decision right after a dial error (reviewReason: "dial:...") no longer loses the link to the call or its reservation. rate_limited while dialing (engine limit, 10 calls per minute, 200 per day) keeps the task running with lastError: "rate_limited" and sets waiting items' nextAttemptAt to the end of the limit (from Retry-After, otherwise in 5 minutes, at most 24 hours) instead of paused; the attempt does not count. invalid_workflow and engine_not_configured while dialing are provably no call (the task becomes paused, the attempt does not count). Every call by an agent on volai's own engine that the engine never dialed (outbound tasks as well as POST /v1/calls, MCP make_call and the portal) has priceHal: 0 and durationSecs: 0 in GET /v1/calls instead of missing values; the call.failed webhook is unchanged.
• 24 Sep 2026 (1.26.0): POST /v1/calls with agentId on an agent on volai's own engine (and MCP make_call): a rejection by the engine's outbound-minute limit (hourly and daily bucket per account) or by full engine concurrency is now 429 rate_limited instead of 502 engine_unavailable; the minute limit adds a Retry-After header (seconds until the end of the hourly window, or until midnight UTC for the daily one). Nothing was dialed or charged; the call stays in the history as failed and the call.failed webhook carries reason: "rate_limited". Outbound tasks treat rate_limited (including the 10 calls/min and 200/day limits) as provably no call: the item is failed without counting an attempt, and the task is paused instead of needs_attention. The POST /v1/calls error table now also lists 502 engine_unavailable - for an agent on volai's own engine it means only a real engine outage, not a limit.
• 23 Sep 2026 (1.25.0): New optional event_id field in the webhook envelope ({event, data, ts, event_id}) for call.completed/call.failed/call.no_answer/call.missed - message.sent and the webhook.test test event are unchanged. A failed delivery of those four events no longer stops after 3 attempts (3s apart): it stays queued and retries over the following minutes, up to 5 rounds; a repeat delivery carries a byte-identical body. GET /v1/webhook/deliveries (and MCP list_webhook_deliveries) now also show rounds before the final one, attempts is the sum of attempts across all rounds, and there is a new optional eventId field.
• 23 Sep 2026 (1.24.1): Two new warnings codes: prompt_variables_unavailable_inbound (an agent with numberE164 whose systemPrompt/firstMessage uses a {{variable}} outside the set an inbound call actually supplies) and first_message_empty (a firstMessage with no letter or digit left in it outside the variables once every {{...}} block is removed). Both REST (POST/PATCH /v1/agents, publish and rollback) and MCP (create_agent, update_agent, publish_agent_draft, rollback_agent_draft) read the same source as the portal's agent editor (agentWarnings).
• 20 Sep 2026 (1.24.0): New optional busyCalendarIds field on the agent (POST/PATCH /v1/agents, MCP create_agent/update_agent, drafts) and on agent-less slot search and booking (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events, MCP find_free_slots, create_calendar_event). The calendars are read in parallel; if any of them fails, the whole lookup fails, so no time is offered over an event we simply could not see. At most four, without duplicates and without calendarId; otherwise 400 calendar_invalid_rules, an unknown calendar 400 calendar_invalid_calendar.
• 20 Sep 2026 (1.23.4): The error tables of POST /v1/agents, PATCH /v1/agents/{id} and draft publish/rollback add the six codes validateCalendar returns: 404 calendar_integration_not_found and 400 calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules. This flows into openapi.json, the /docs/api reference, SKILL.md and llms-full.txt.
• 20 Sep 2026 (1.23.3): maybeQueueMissedCallSms now also fires for an outbound call with answeredBy: "voicemail" (previously only status: "no_answer" and inbound missed). A voice menu (ivr) or unknown does not trigger it. All other conditions (CZ/SK number only, DNC, blocked destinations, one SMS per number per 24 h, quiet hours, last task attempt) are unchanged; CallRecord.missedSms is written the same way.
• 19 Sep 2026 (1.23.2): A timestamp with milliseconds was formatted with a time zone offset one minute short (+01:59 instead of +02:00) - this affected the now field in the agent tools and the start of a created event when a client sent start with fractional seconds. Alternatives returned with 409 calendar_slot_taken (POST /v1/integrations/{id}/events, MCP create_calendar_event) are now computed from the requested time, the same as find_free_slots with a time.
• 19 Sep 2026 (1.23.1): The agent calendar field (POST/PATCH /v1/agents, MCP create_agent/update_agent and drafts) rejects a calendar whose accessRole is reader or freeBusyReader with 400 calendar_invalid_calendar, because the agent writes appointments into the same calendar. list_calendars returns the role as accessRole where the provider reports it; a calendar without a role is accepted as before. No other error codes change.
• 19 Sep 2026 (1.23.0): New CallRecord.rating field (value: "good" | "bad", reason?, note?, at, source: "portal" | "email" | "api" | "mcp") and CallRecord.missedSms; PATCH /v1/calls/{id} and MCP annotate_call accept rating/ratingReason/ratingNote (patchCallAnnotation calls rateCall with source: "api"/"mcp"). New AgentRecord.missedCallSms { enabled, text? } field (variables {firma}, {cislo}, {agent}) on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent/save_agent_draft. GET/PATCH /v1/account and MCP get_account/update_account have companyName (max 80 chars, empty string clears it), and GET now returns notifications.weeklySummary. The test call in the agent editor shows the outcome based on the call goal (call.evaluation.goal) and the collected data.
• 18 Sep 2026 (1.22.0): New endpoints POST /v1/integrations/{id}/availability (free slots without a saved agent - windows omitted means 24 hours every day) and POST /v1/integrations/{id}/events (create an appointment, requires confirm: true, optional idempotencyKey for safe retries; 409 calendar_slot_taken on a collision), MCP tools find_free_slots and create_calendar_event with the same shape. DELETE /v1/integrations/{id} now returns affectedAgents - agents whose calendar field was turned off by disconnecting this integration. New calendar field on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent: integrationId, calendarId, timezone, slotMinutes, minNoticeMinutes, horizonDays, bufferMinutes, windows (an array of {from,to} windows per weekday). Works only on volai's own engine (provider: "engine") - on an agent hosted on ElevenLabs the field is saved and waits for the calendar_pending_engine_switch warning until the agent switches. Eleven new error codes with cause/action: calendar_slot_taken, calendar_confirmation_required, calendar_invalid_range, calendar_integration_not_found, calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules, calendar_too_many_events, calendar_unavailable.
• 18 Sep 2026 (1.21.0): New ledger movement type setup_revision (GET /v1/credit/ledger, MCP) for a done-for-you setup order's revision round beyond the package, amount SETUP_EXTRA_REVISION_HAL (490 CZK excl. VAT). Tax documents (GET /v1/billing/documents, .../{id}, list_billing_documents, get_billing_document) now always carry a kind field ("invoice" - default, or "credit_note"), plus optional correctsNumber and correctionReason fields; a done-for-you setup refund's credit note is numbered in its own OD series and carries positive amounts (the minus sign is added by the PDF). credit() (lib/service/balance.ts) gained an internal notifyTelegram parameter - a done-for-you payment now sends just one Telegram alert ("Na klíč: zaplaceno"), not two. New public landing page at /receptionist-done-for-you (Czech canonical /recepcni-na-klic).
• 18 Sep 2026 (1.20.0): New laughter field (auto/on/off) on POST/PATCH /v1/agents and MCP create_agent/update_agent: auto follows the engine's sensitive-topic detection (debt collection, healthcare, authorities, funeral services), on overrides that detection, off always suppresses it; an omitted key is stored and returned as auto, never absent. GET /v1/agents/{id} and the new MCP tool get_agent (previously missing parity for a single agent's detail) add laughterEffective ({active, reason, sensitiveCategory} | null) nested inside the returned agent object, computed fresh for the published configuration; null means it could not be determined right now (the engine did not respond within 3 seconds, was down, or returned a silent 404 on an older build) - never a guess. MCP update_agent returns the same object as a top-level field next to agent instead, since PATCH /v1/agents/{id} never returns it. The field is accepted and stored for an agent on ElevenLabs too, but has no audible effect there - only a Czech Cartesia voice on volai's own engine plays it.
• 18 Sep 2026 (1.19.0): New REST API v1 and MCP area - source setup-orders, capability area setup (after credit). Seven endpoints (POST /v1/setup-orders, GET /v1/setup-orders, GET/POST /v1/setup-orders/{id}, .../messages, .../checkout, .../launch, .../cancel) and seven matching MCP tools (create_setup_order, list_setup_orders, get_setup_order, message_setup_order, checkout_setup_order, launch_setup_order, cancel_setup_order) over the same service layer, lib/service/setup-orders.ts. The quote is always computed by the catalog in code (lib/setup-catalog.ts); the model only picks items from the conversation. New error codes: setup_order_not_found, order_closed, invalid_transition, quote_pending_confirmation, checkout_open, turn_in_progress, advisor_no_quote, advisor_unavailable, setup_orders_disabled. Documentation at /docs/done-for-you (Czech /docs/na-klic).
• 17 Sep 2026 (1.18.0): The agent draft (PUT/GET /v1/agents/{id}/draft, POST /v1/agents/{id}/draft/publish) and the MCP save_agent_draft tool now treat numberE164 as three-state: an absent key leaves the agent's number untouched, null disconnects it, and a string attaches that number - parity with the semantics PATCH /v1/agents/{id} already had. Reading a draft also reconciles it against the live agent: published.numberE164 always mirrors the live number, and draft.numberE164 does too whenever the draft made no explicit choice, so the editor's pre-publish check and outbound tasks see the true state even after a number was attached or moved outside the editor; "no explicit choice" also covers a string that matches the agent's current LIVE number - that value behaves the same as an absent key, re-checked on every draft read against whatever number is live at that moment; if the number later moves to a different agent outside this draft, the same stored value becomes an explicit choice again and the next publish or rollback reattaches it here - not silently: publish and rollback responses (REST and both MCP tools) now carry a new number_changed_by_publish warning with from/to (E.164, or null for no number) in that case, without blocking the operation either. One read-side compatibility note: draft.numberE164 can now come back as null (an explicit "no number" choice) where the key used to be simply absent - treat it the same as an absent key, meaning the agent has no number. The "tested" marker and the agent fingerprint pinned to a running outbound task are now computed WITHOUT the phone number too (behaviorFingerprint, not draftFingerprint), so attaching or moving a number outside the editor no longer requires a fresh test and no longer stops a running campaign; a draft with a number saved BEFORE this change has its marker computed the old way, including the number, so it asks to be re-earned once - one test or publish after the update restores it, and the new rule applies from then on.
• 15 Sep 2026 (1.17.0): A new goal display state, GoalDisplayState (success/failure/unclear/no_conversation/not_evaluated), replaces the AgentGoalResult triple in the portal's display, in the /hovory filters and in the overview. REST and MCP gained answeredBy: "ivr", goal.reason ("no_caller_speech"/"evaluation_error"), and hasConversation (boolean | null). The goal parameter (GET /v1/calls, MCP list_calls) accepts five new values alongside the existing unknown, which stays backward compatible - it still covers records with no clear result (goal.result missing or unknown): always unclear and not_evaluated, and no_conversation only when its result is also unknown.
• 13 Sep 2026 (1.16.0): A new endReason: "engine_error" value (status failed) appears when the engine sends metadata.engine.termination_reason as engine_stall or engine_error for a call that was actually handled - previously that field was discarded for such calls. priceHal is set to 0 only when the call has no price yet (otherwise it is left unchanged, with an ALERT log). The call.failed customer webhook gained four new optional fields: durationSecs, priceHal, transcript, summary - populated only for this technical branch, missing everywhere else as before. GET /v1/calls/{id} and MCP get_call return the same endReason value. Outbound tasks (POST /v1/outbound-tasks, MCP) treat engine_error as a retryable attempt (the same path as no_answer), not a reason to stop the campaign, and do not record it toward the automatic 30-day destination block.
• 13 Sep 2026 (1.15.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new silencePromptSecs: number | null field (a whole number 3 to 25, null turns it off), bounds matching the engine (engine/types.py, U1). A missing field on POST/create_agent saves the default of 10 - unlike voicemail, the field is accepted and returned for EITHER provider (GET /v1/agents returns the stored value even for provider: "elevenlabs"). A value outside the bounds fails with the generic validation error (validation, 400), no new code. Existing agents on the engine get the default of 10 via a one-off re-sync script (scripts/resync-silence-prompt.mts) that changes only this one field.
• 13 Sep 2026 (1.14.7): OpenAPI adds descriptions to every operation and request field, including nested variants. Agent, tool, SMS and call constraints use product limits shared with the service layer instead of permissive parser ceilings. Automated checks validate all request and response examples against their schemas. API behavior, error codes and provider settings are unchanged.
• 13 Sep 2026 (1.14.6): POST /v1/messages and MCP send_sms return insufficient_credit (HTTP 402, cause account) until the account has a positive topup (card or auto top-up) or admin (manual owner adjustment) ledger entry. The previous cap of 3 SMS for accounts without an active number of their own is gone, and an active number no longer grants an exception. The first top-up is kept as a permanent account flag, so a long ledger history never blocks a customer.
• 13 Sep 2026 (1.14.5): New workflow_node_tool_missing code in warnings on POST/PATCH /v1/agents, on draft publish and rollback, and on MCP create_agent, update_agent, publish_agent_draft and rollback_agent_draft. It applies to both providers, because a deleted tool does not reach the phase on volai's own engine either. workflow_node_tool_not_synced now only covers a tool that is on the account but not among the agent's own. The Reception template also recommends two sentences for the base prompt: do not guess operational details, and ask about one thing at a time.
• 12 Sep 2026 (1.14.4): Setup distinguishes OAuth grant identifiers from API keys when restoring older saved choices. An unavailable status check is not treated as revoked access.
• 12 Sep 2026 (1.14.3): Added the catalog files katty-studio.mp3 and katty-telefon.mp3 using the same generator and content as the other voices. The agent voice, provider and phone service settings are unchanged.
• 12 Sep 2026 (1.14.2): Copy labels and next-step guidance match the selected connection method. Codex desktop with an API key points to config.toml. Closing the mobile menu preserves focus restoration.
• 12 Sep 2026 (1.14.1): Sign-in preserves the assistant setup destination. The workspace preference is stored per account separately from actual MCP verification. Manual guides cover Claude Code, Codex CLI and desktop, with API keys as an alternative. Help and the names Voice agents, Phone numbers and Data & integrations are consistent.
• 12 Sep 2026 (1.14.0): When useForOutboundTasks is omitted, selection depends on VOLAI_ENGINE_DEFAULT_FOR_NEW, engine availability and VOLAI_ENGINE_DEFAULT_FOR_NEW_LANGUAGES (unset means cs,sk). Language alone does not guarantee the engine. Explicit true requests the engine; false starts on ElevenLabs. Applies to the portal, POST /v1/agents and MCP create_agent. Read back provider and voiceId after creation; handoff may trigger a subsequent provider switch attempt.
• 12 Sep 2026 (1.13.0): The workflow field is available in POST and PATCH /v1/agents, in the agent draft, and in the create_agent, update_agent and save_agent_draft MCP tools. A call that went through phases carries workflowPath in GET /v1/calls and GET /v1/calls/{id}. New workflow_*, workflow_not_synced_to_provider and workflow_node_tool_not_synced warnings flag phase configuration issues.
• 12 Sep 2026 (1.12.5): voiceId for an ElevenLabs agent: katty (default, the template voice) or a raw ElevenLabs id; jana is gone from the catalog and from ElevenLabs (the two agents from the afternoon of 12 Sep were switched to Katty and the voice was removed from the workspace). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return katty. The engine's ElevenLabs fallback for Milena, Tereza and Katarina is Katty as well.
• 12 Sep 2026 (1.12.4): Polling no longer interrupts a slow status request. Successful MCP read evidence is found by active access even if writing the helper index failed. Verification still requires get_balance or list_agents through MCP.
• 12 Sep 2026 (1.12.3): Fixed the English calendar privacy link and kept an active goal filter visible even without previous evaluations. Both languages have regression coverage for links and unavailable integrations.
• 12 Sep 2026 (1.12.2): The MCP guide uses existing evidence of successful reads through an active API key or OAuth grant, with no simulated verification. The goal=unknown filter in GET /v1/calls and MCP list_calls also includes records without a goal evaluation. Technical completion does not mean a goal was met. REST and MCP still return individual records; the portal groups them into conversations.
• 12 Sep 2026 (1.12.1): voiceId for an ElevenLabs agent: jana (default, the template voice) or a raw ElevenLabs id; anet passes only on an agent that already has it, otherwise a 400 validation with an explanation (previously a 502 eleven_labs_error from ElevenLabs voice_live_moderated_not_allowed). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return jana. An ElevenLabs agent without voiceId gets Jana explicitly (the record carries her id). SIP registration: the carrier returned 403 INVALID_USER for lines bought through its API until the line's SIP protocol was toggled off and on once; fixed for all lines and done automatically when a new line is bought.
• 12 Sep 2026 (1.12.0): OAuth authorization code + PKCE S256, DCR, resource-bound opaque tokens, refresh rotation/replay detection, OIDC discovery/JWKS/userinfo and revocation. Access tokens last 10 minutes, refresh tokens up to 30 days, grants up to 90 days. Password changes invalidate OAuth access. MCP annotations explicitly distinguish overwrites, paid actions, messages and external side effects.
• 12 Sep 2026 (1.11.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress = sip.volai.cz (volai's own SIP proxy with digest auth, realm sip.volai.cz; measured: the platform refuses an INVITE larger than the UDP MTU, the same call passes over TCP), transport = tcp (schema is now enum [tcp, udp], UDP works too), port 5060 unchanged. The watchdog monitors the proxy healthz (SIP_PROXY_HEALTHZ_URL): ops e-mail when unreachable, when the auth data sync stalls or when the certificate has under 14 days left. The ElevenLabs post-call webhook has its HMAC secret in production and is enabled per agent (ELEVENLABS_POST_CALL_WEBHOOK_ID).
• 12 Sep 2026 (1.10.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress is driven by its own configuration (it may equal server), field descriptions no longer mention a realm; inboundSignallingCidrs unchanged. The ElevenLabs post-call webhook matches inbound calls via metadata.phone_call.call_sid (it used to read the SIP Call-ID call_id, which never matched the call:sid key written by the initiation webhook) through findExistingCallByKeys shared with the conversations-sync cron (order call:conv -> call:attempt -> call:sid). Per-agent post-call webhook settings (platform_settings.workspace_overrides.webhooks) are migrated by the cron once ELEVENLABS_POST_CALL_WEBHOOK_ID is set; until then the cron keeps closing calls. The engine post-call accepts phone_call.external_number: null and caller_presentation; the uri_ caller prefix is stripped as in the initiation webhook. The call transfer target (transfer_to_number) is built from a separate VOLAI_SIP_TRANSFER_HOST, not from the public SIP domain. New internal source of auth data for the SIP proxy (GET /api/internal/sip-subscribers, outside v1, bearer + IP allowlist + rate limit).
• 12 Sep 2026 (1.9.0): POST/PATCH /v1/agents and MCP create_agent/update_agent can now return a second warnings code: first_message_too_long, independent of first_message_no_ai_disclosure - and publishing an agent draft (POST /v1/agents/{id}/draft/publish, MCP publish_agent_draft) and rolling it back to an earlier revision (POST /v1/agents/{id}/draft/rollback, MCP rollback_agent_draft) now return the same warnings too, which they previously omitted entirely - both of them write the first line to the live agent. The estimate counts words, digits per character, and all-caps abbreviations up to four characters; a longer all-caps word counts as one word, so a company name written in capitals no longer inflates the estimate. The single threshold (an estimated duration over 7 seconds) is measured against what the caller actually hears - the greeting plus the call-recording notice, when enabled. An unchanged default greeting template never gets the warning, only a line the customer has edited.
• 12 Sep 2026 (1.8.2): Documentation, integration guides and error actions point to AI assistant for access management. MCP makes clear that the voice engine is required to start an outbound task; a task can also be created with an ElevenLabs agent.
• 12 Sep 2026 (1.8.1): OpenAPI now describes Idempotency-Key for 14 supported operations, response headers and the optional revision JSON body when deleting a task. Documentation corrections without changing paid-action behavior: useForOutboundTasks distinguishes true/false/omission, tasks support 1000 recipients and billing_unknown retains the original call and reservation until its price is known. Credit tax documents are available over REST and MCP; an API key can revoke only itself over REST; integration disconnect is REST/portal. Correction to 1.6.1: preview_task_csv is not an MCP tool; use POST /v1/tasks/csv-preview or the portal. Install commands share the onboarding generator, example tabs have unique anchors and Python preserves JSON values.
• 11 Sep 2026 (1.8.0): The new REST POST /v1/dnc/{e164}/unblock and the corresponding MCP tool unblock_destination lift an automatic destination block; they also work for blocks created before this deployment. Older blocks may be absent from GET /v1/dnc and list_dnc because they predate the listing index, but direct unblock by phone number still works. Indexed blocks are returned in a blocked: [{e164, blockedAt, expiresAt}] array (times are Unix milliseconds) alongside the unchanged numbers. After a block is lifted, the failed-attempt counter starts over - three new failed attempts to the same number block it again, and lifting it again is not limited. groupCallsByConversation (the shared primitive behind /hovory, the CSV export, the Previous/Next navigation, and the stats) now sorts by representative.startedAt descending; it used to sort by key, i.e. alphabetically by conversation id. TestCallOutcome has a new no_answer value kept separate from failed, so the panel never claims a cause it doesn't know. A name written in ALL CAPS now gets an ALL CAPS vocative form (RADEK -> RADKU) in both the e-mail and the Overview header.
• 11 Sep 2026 (1.7.1): agent_busy (HTTP 409, cause: "busy") was added to the shared error map PUBLIC_ERROR_HTTP/PUBLIC_ERROR_CAUSE (lib/types.ts). It is returned by switchAgentProvider (lib/service/engine-provider.ts) - the only portal admin action that switches an agent's provider; REST v1 and MCP have no such input (agents.switch_provider in the capability catalog, lib/capabilities.ts). The check uses a new GET /v1/calls/active client (lib/engine.ts listActiveCalls): the agent's call is matched PRIMARILY by the agent_id field, which the engine carries on an active call since the version that added it was deployed; the number stays a fallback for an older engine without it.
• 11 Sep 2026 (1.7.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new voicemail: {enabled, action: "mark"|"hangup"|"message", message?} field - only for an agent with provider: "engine", otherwise voicemail_requires_engine; message is required when action: "message", up to 400 characters (invalid_voicemail_message). GET /v1/agents returns the configured value. The engine's post-call now carries answered_by/voicemail_reason/voicemail_message_left/voicemail_detected_at_secs; answered_by takes precedence over the previous transcript-based estimate (lib/answered-by.ts) only with human and voicemail - unknown is treated as "the engine didn't decide" and the transcript-based estimate is used instead. GET/list_calls/get_call for an outbound call handled by the engine also return voicemailReason (a fourth value, human_reply, for a short human reply), voicemailMessageLeft, and voicemailDetectedAtSecs.
• 11 Sep 2026 (1.6.5): For an outbound call ended before answer the engine deletes the room and delivers a post-call webhook: empty transcript, call_duration_secs: 0 and the new additive field metadata.engine.termination_reason (no_answer or disconnected_before_answer). The call gets status: no_answer, endReason: no_answer and price 0 as before, only immediately. The GET /v1/calls reconciliation pairs engine outbound calls by call_sid and sends zero duration for calls that never connected. GET /openapi.json: answeredBy now carries a description about the outbound-only limitation.
• 11 Sep 2026 (1.6.4): POST /v1/tasks and PATCH /v1/tasks/{id} (and create_task/update_task in MCP) accept up to 1000 recipients, POST /v1/tasks/csv-preview up to 1000 rows. A new task record size check (2 MB of serialized JSON) returns validation with field recipients.
• 11 Sep 2026 (1.6.3): ElevenLabs initiation webhook: the payload's agent_id is now checked against the routed agent's elevenAgentId OR id - a foreign agent_id gets only a minimal response without conversation_config_override; the same check guards closing the conversation in the post-call webhook and the conversations-sync cron. CDR-sync cron: an unrecognized outbound CDR record from your own line (excluding the demo number), older than 600s and without an ambiguously matching existing record, is now billed as kind: "sip" at the outbound rate with no agent surcharge (it shows up in GET /v1/calls with kind: "sip"; the chargedSip counter is only in the cron's own response, not in the public API); a younger or ambiguously matching record is still just held for manual review. CallKind extended with "sip". The CDR shape of a real SIP client call has no production evidence yet (no registered softphone) - hence both safeguards.
• 11 Sep 2026 (1.6.2): New endpoint POST /v1/tasks/{id}/items/{itemId}/resolve with body { action: "retry" | "skip", revision } and the MCP tool resolve_task_item; new error code item_not_resolvable (409, account), task_not_editable for a running or completed task. The engine call sync matches the account's own outbound leg by relay line and start time, closes an unanswered outbound call as no_answer and releases the tenant concurrency quota after closing. relay_lease_limit while dialing a task is a transient state that does not consume an attempt.
• 11 Sep 2026 (1.6.1): POST /v1/tasks/csv-preview and the portal recognise the phone column regardless of case, surrounding spaces and a trailing colon and accept aliases (telefon, tel, mobile, phone number); the response always names the column phone. A single-column input without a header whose first value is a phone is treated as data. Without a phone column the preview returns a single phone error on the header instead of Phone is required on every row. The agent_not_ready contract is unchanged. Documentation correction, 12 Sep 2026: the original MCP-tool claim was incorrect; CSV preview is REST/portal-only.
• 11 Sep 2026 (1.6.0): GET /v1/numbers/{e164}/sip and the MCP get_sip_credentials tool now also return outboundTrunkAddress, port, transport and inboundSignallingCidrs alongside server/username/password; MCP create_relay_lease and the get_sip_credentials description now explicitly distinguish server (registration) from outboundTrunkAddress (a platform's outbound trunk). The /en/docs/bring-your-own-agent guide, the ElevenLabs integration page and the blog post no longer put server into outbound_trunk_config.address - only outboundTrunkAddress.
• 11 Sep 2026 (1.5.1): GET /v1/calls, GET /v1/calls/{id}, the call.completed webhook and MCP list_calls/get_call: answeredBy is present only when direction: "out" (older records included). POST /v1/messages and send_sms: an account without an active number and without a positive topup/refund/admin ledger entry gets insufficient_credit (HTTP 402, cause account) after three sent SMS.
• 8 Sep 2026 (1.5.0): New REST endpoints: GET/PATCH /v1/account, PUT /v1/account/billing, GET /v1/api-keys, DELETE /v1/api-keys/{id} (self-revoke); PATCH /v1/calls/{id} and GET /v1/calls extended with from, to, agentId, flagged, goal, outcome query parameters; POST /v1/tools/test, POST /v1/tools/{id}/test, DELETE /v1/webhook, and GET /v1/tools/{id} now additionally returns agents; POST /v1/agents/{id}/draft/rollback; GET /v1/numbers/{e164}, GET/POST /v1/numbers/waitlist, DELETE /v1/numbers/waitlist/{offerId}, GET /v1/numbers/{e164}/sip/status; POST /v1/integrations, DELETE /v1/integrations/{id}, POST /v1/integrations/{id}/events/{eventId}/propose; GET /v1/changelog (no API key, x-volai-version on every v1 response including errors, 429 and /openapi.json). 16 matching new MCP tools: get_account, update_account, update_billing_details, list_api_keys, annotate_call, test_tool, remove_webhook, list_webhook_deliveries, rollback_agent_draft, reconcile_agent_draft_operation, test_call, get_number, join_number_waitlist, leave_number_waitlist, get_sip_status, get_changelog - revoking someone else's API key, creating an API key, and disconnecting an integration or card stay REST-only or portal-only (spec §3). The new capability catalog holds a capability field on every endpoint and tool; guard tests verify the error table and response example on /docs/api match the real error codes for every endpoint. Additive only - no existing status or code changed. The new content/changelog.json file is the single source of truth: /en/changelog, the changelog section on /docs/api, the Versioning section in SKILL.md, RSS (/en/feed/<area>), GET /v1/changelog and the MCP get_changelog tool are all generated views over it. Additive only - no existing content disappeared. New REST endpoints: GET/POST /v1/tasks, GET/PATCH/DELETE /v1/tasks/{id}, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/pause, POST /v1/tasks/{id}/reconcile, POST /v1/tasks/csv-preview. 7 matching new MCP tools: list_tasks, get_task, create_task, update_task, pause_task, reconcile_task, start_task (which requires repeating the real recipient count and budget, otherwise it returns an error with the real numbers) - deleting a task and previewing a CSV stay REST and portal only (spec §3). Portal: a Delete task button on the task detail page with type-to-confirm. Additive only - no existing status or code changed. New REST endpoints: GET /v1/credit/ledger, POST /v1/credit/topup, GET/PATCH /v1/credit/auto-topup, POST /v1/credit/auto-topup/setup, POST/DELETE /v1/credit/auto-topup/card, GET /v1/billing/documents, GET /v1/billing/documents/{id}, GET /v1/billing/documents/{id}/pdf; GET /v1/balance now additionally returns runway and notice. 6 matching new MCP tools: list_ledger, create_topup_link, get_auto_topup, disable_auto_topup, list_billing_documents, get_billing_document (get_balance extended with the same runway/notice) - get_billing_document does not return the PDF, which stays REST-only via GET /v1/billing/documents/{id}/pdf (binary output); turning auto top-up on and changing its amount or card stay behind a Stripe Checkout link only, MCP has neither (spec §2, §3). Additive only - no existing status or code changed. GET /v1/account now returns a new notifications.productUpdates field (on by default); there is a matching toggle in portal Settings. The daily email digest (cron 0 6 * * * UTC) only sends to accounts with a verified email and productUpdates !== false, at most one email per account per day. The List-Unsubscribe header and cookie-free one-click unsubscribe now also cover the reactivation email when UNSUBSCRIBE_SECRET is configured on the server - without it the email still sends, just without the unsubscribe link. Additive only - no existing status or code changed.
• 8 Sep 2026 (1.4.3): Every input property of all 44 MCP tools carries its own description (clients see it in tools/list; the PATCH .../events/{eventId} and PUT /v1/agents/{id}/draft bodies expose it in openapi.json too). The invoice endpoints GET /v1/integrations/{id}/invoices[/{invoiceId}] list their error codes by real reachability in the docs and in OpenAPI - integration_storage_error was removed, it never came from the API - and their query validation returns the human-readable message like the rest of v1 (same for GET .../events). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.2): Fixed Apple event reads and confirmed updates: iCloud rejects UID searches, so event lists now return opaque CalDAV resource IDs. Pass externalId unchanged as eventId; reload any Apple event IDs saved from earlier versions. Invalid Apple IDs return 400 calendar_invalid_query. Google identifiers are unchanged.
• 8 Sep 2026 (1.4.1): POST /v1/agents and create_agent accept useForOutboundTasks (choosing volai's own voice engine at creation, the same choice as the portal checkbox "Use for outbound tasks"; omitted = the deployment default, today ElevenLabs). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.0): Apple Calendar shares the same calendar flow over REST and MCP as Google. Fakturoid and ABRA Flexi added GET /v1/integrations/{id}/invoices[/{invoiceId}] plus the list_invoices and get_invoice tools (the interface only reads invoices). GET /v1/integrations and list_integrations also return providers with setup readiness and a browser connection URL. Provider credentials still require connection in the portal. Additive only - no status or code changed.
• 7 Sep 2026 (1.3.0): Google Calendar entered the public interface - GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET/PATCH /v1/integrations/{id}/events/{eventId} and six MCP tools (list_integrations, list_calendars, list_calendar_events, get_calendar_event, propose_calendar_update, confirm_calendar_update), which takes REST to 50 endpoints and MCP to 42 tools. Every error response also carries cause (request / account / busy / service - who fixes it) and action (one sentence on what to do). validation messages name the field, the actual value and the accepted maximum instead of the raw validator text; the input caps for an agent's name, instructions, goal and knowledge are ten times the product limits, so the limit is always reported by the product error with the exact number. MCP errors carry the same fields in structuredContent.error (including requestId) and a text prefixed by cause. Additive only, no status or code changed.
• 6 Sep 2026 (1.2.0): The /v1/agents/{id}/draft* and /simulate endpoints lost the ok wrapper and plain-string errors - errors now share the same shape, {error:{code,message,requestId,docsUrl}}, as the rest of v1; revision in request bodies was renamed to expectedRevision; added hasMore/nextBefore pagination fields, X-Request-Id and RateLimit-* headers, POST /v1/webhook/test, GET /v1/webhook/deliveries, and GET /openapi.json. The draft endpoints were already public from 5 Sep 2026, but without a stable contract - they are therefore excluded from the versioning guarantee (rule 1 of the Versioning section) up to and including 1.2.0.

Die vollständige, laufend aktualisierte Liste finden Sie auf der Seite Changelog (auch als RSS-Feed verfügbar).

Konventionen

Gewohnheiten, die endpunktübergreifend gelten - nicht nur bei einem einzelnen.

Bezeichner

Jede ID trägt ein Präfix, das den Datensatztyp benennt, und ist ansonsten opak (nicht weiter zerlegen):

vk_ API-Schlüssel, ag_ Agent, ad_ Agent-Entwurf, ado_ Entwurfsoperation, c_ Anruf, msg_ SMS-Nachricht, tl_ Tool, whd_ Webhook-Zustellung, rl_ Relay-Lease, int_ verbundene Integration, inv_ Steuerdokument (GET /v1/billing/documents), l_ Eintrag im Guthabenjournal, task_ ausgehende Aufgabe, item_ Empfänger einer Aufgabe, attempt_ Anrufversuch zu einem Aufgabeneintrag, req_ Anfrage-ID (siehe Fehlerformat oben).

Zeitstempel

Zeitstempel sind fast überall Unix-Millisekunden (createdAt, startedAt, boughtAt, issuedAt, taxableAt) - die AUSNAHME sind die Felder der verbundenen Kalender UND der verbundenen Rechnungen: start, end, fetchedAt (Kalender) und die Parameter timeMin/timeMax sind RFC-3339-Strings (2026-09-08T10:00:00.000Z), nie eine Zahl; GET /v1/integrations/{id}/invoices und .../invoices/{externalId} sind ebenfalls Strings - fetchedAt hat dieselbe RFC-3339-Form, dueDate ist ein einfaches Datum (2026-09-08) direkt von Fakturoid/ABRA Flexi, oder null, wenn der Anbieter keines geliefert hat. Der Monatstarif ist eine zweite Ausnahme: periodStart und periodEnd (/v1/subscription, /v1/balance) sind ISO-8601-Strings in UTC, keine Millisekunden.

Paginierung - drei Schemata, plus Listen ohne jede

GET /v1/messages, GET /v1/calls und GET /v1/billing/documents nehmen limit + before (ein Zeitstempel in ms, exklusiv) und antworten mit hasMore/nextBefore - Einzelheiten siehe Paginierung oben. Termine verbundener Kalender (GET /v1/integrations/{id}/events) verwenden stattdessen ein opakes pageToken/nextPageToken - timeMin/timeMax/search müssen zwischen den Seiten unverändert bleiben, pageToken allein garantiert das nicht. GET /v1/credit/ledger nimmt nur limit (1-200, Standard 50), überhaupt keinen Cursor - es beginnt immer beim jüngsten Eintrag. GET /v1/tasks ohne ids liefert höchstens die 100 jüngsten Aufgaben; ids liest bis zu fünf bestimmte Aufgaben pro Anfrage, ohne ein vollständiges Inventar des Mandanten zu versprechen. GET /v1/webhook/deliveries hat ebenfalls keinen Cursor und liefert höchstens die letzten 50 Zustellungen (erfolgreiche, fehlgeschlagene und Testzustellungen). Auch die Suche in verbundenen Rechnungen ist stillschweigend begrenzt - die ersten 40 Zeilen bei Fakturoid oder 50 bei ABRA Flexi, ohne Cursor, um mehr zu sehen; schränken Sie stattdessen die Suche ein. Alles andere, was eine Liste liefert (Agenten, Nummern, Mobilnummern, Tools, API-Schlüssel, die Do-not-call-Liste, Stimmen), gibt die gesamte Menge in einer Antwort zurück - es gibt nichts zu blättern.

Unbekannte und tschechisch benannte Parameter

Ein unbekannter Query-Parameter wird fast überall stillschweigend ignoriert (damit ein älterer Client nicht an einem zusätzlichen Parameter scheitert) - die Ausnahme sind die Endpunkte der verbundenen Kalender und Rechnungen (/v1/integrations/{id}/...), die einen unbekannten Parameter mit 400 validation abweisen, weil sie ihn an den Upstream-Anbieter weiterreichen und ein dort stillschweigend verworfener Filter wie fehlende Daten aussähe, nicht wie ein Fehler; und aus einem anderen Grund GET /v1/credit/ledger und GET /v1/billing/documents, deren Query-Schemata absichtlich strikt sind, damit ein Tippfehler bei limit/before laut scheitert, statt stillschweigend ignoriert zu werden.

Einige Felder behalten absichtlich einen tschechischen Namen: Der Adressablauf für Nummern (GET /v1/numbers/address-options, dann POST /v1/numbers/orders - das einfache POST /v1/numbers nimmt nur e164/region und ignoriert eine Adresse) übergibt psc, obec, cobce, ulice (nur wo die Adresse eine Straße hat) und cp - die exakten Feldnamen des RÚIAN-Registers (der Adresscodeliste des Betreibers), bei dem die Nummer bestellt wird, damit ein zwischen beiden hin- und hergereichter Wert nie unbemerkt falsch übersetzt wird. GET /v1/calls/{id}/recording?stahnout=1 ist der einzige tschechisch benannte Parameter außerhalb dieses Ablaufs (Download als Anhang statt Inline-Wiedergabe). Alles andere - Bezeichner, Felder und Parameter gleichermaßen - ist englisch.

Kontingente an einem Ort

Jedes Kontingent wird auch bei seinem eigenen Endpunkt oben erwähnt - dies ist nur die Zusammenfassung:

• 60 Anfragen/min pro API-Schlüssel (REST und MCP teilen es sich, siehe Rate-Limits oben)
• SMS: 1 alle 2 s und 100/Tag pro Konto, erst nach der ersten Guthabenaufladung
• SMS von einer Mobilnummer (fromNumber): zusätzlich 20 Nachrichten pro Tag und Konto in den ersten 30 Tagen nach dem Kauf der Nummer, danach 50; höchstens zwei Mobilnummern pro Konto
• Ausgehende Anrufe (Agent, Bridge, Test): 10/min und 1000/Tag pro Konto, höchstens 2 gleichzeitig laufende Anrufe des integrierten Agenten
• Klingelanrufe (POST /v1/rings): 30/min und 500/Tag pro Konto und 120/Stunde zu einer Nummer, unabhängig von den Anruflimits
• Sprachnachrichten (POST /v1/voice-messages): höchstens 200 pro 24 Stunden und Konto, zusätzlich zu den regulären Anruflimits
• Testanruf ohne eigene Nummer (POST /v1/calls mit systemPrompt statt agentId/from): zusätzlich 3/24 h pro Konto UND ein gemeinsames Limit von 30/Stunde über ALLE Konten zusammen - das gemeinsame Limit kann Sie ohne eigenes Verschulden treffen.
• POST /v1/agents/{id}/test-call: 3/Tag pro Konto
• POST /v1/tools/test und .../{id}/test: 10/min pro Konto
• POST /v1/agents/{id}/simulate: 20/Stunde pro Konto
• POST /v1/webhook/test: 10/Stunde pro Konto
• GET /v1/changelog: 30/min pro IP (ohne API-Schlüssel)
• Aufgaben: Eine laufende Aufgabe wählt pro Cron-Tick höchstens EINEN Empfänger an. Die allgemeine Warteschlange bleibt bei */2 * * * * und berührt über alle Konten hinweg höchstens 20 Aufgaben; registrierte PetCenter-Aufgaben nutzen einen getrennten Tick * * * * * und eine eigene Warteschlange, mit denselben Grenzen für Parallelität und Anrufrate. Beide Warteschlangen rotieren fair, wenn mehr als 20 Aufgaben warten.

Webhook-Wiederholungen

Eine fehlgeschlagene Zustellung erhält bis zu 3 Versuche im Abstand von 3 Sekunden innerhalb desselben Versands. Bei Anrufereignissen (call.completed, call.failed, call.no_answer, call.missed) und bei message.received ist das nicht das Ende: Das Ereignis bleibt in der Warteschlange, und die Zustellung wird in den folgenden Minuten noch einige Male wiederholt, insgesamt bis zu 5 Runden - entfernen Sie Duplikate anhand von event_id im Body für den seltenen Fall, dass es mehr als einmal ankommt. message.sent und das Testereignis webhook.test haben keine Warteschlange: Nach einem Fehlschlag wird es nur protokolliert und nicht erneut gesendet. Den Fortschritt, auch der Runden vor der letzten, sehen Sie über GET /v1/webhook/deliveries (oder list_webhook_deliveries) - attempts ist dort die Summe der Versuche über ALLE Runden.

Abkündigung

v1 hat bisher nur Dinge hinzugefügt (siehe Versionierung oben) - die einzige Ausnahme war Version 1.5.1, die answeredBy bei EINGEHENDEN Anrufen nicht mehr zurückgab (das Feld hatte dort nie einen sinnvollen Wert; bei ausgehenden Anrufen ist es unverändert). volai hat bisher noch kein Feld vollständig abgeschafft. Geschieht das, wird das Feld in GET /openapi.json mit deprecated: true markiert, die Antwort trägt mindestens 90 Tage im Voraus die Header Deprecation/Sunset, und eine MCP-Antwort, die es berührt, erhält einen Eintrag in warnings (demselben Feld, das heute schon für den Hinweis zur Offenlegung nach dem AI Act dient) - die Entfernung selbst erscheint immer nur als neue Hauptversion (v2), nie stillschweigend innerhalb von v1.

Anrufe vs. Gespräche - siehe den gleichnamigen Absatz unter Anrufe unten, bevor Sie Zahlen addieren.

Zugangsdaten (ein Passwort, ein Token, ein app-spezifisches Passwort) gehören nur dorthin, wo der Benutzer sie bereits an einer für Sie lesbaren Stelle abgelegt hat (eine Umgebungsvariable oder eine von ihm genannte Datei) - fragen Sie nie im Gespräch danach und geben Sie sie nie zurück; gilt heute für Apple Kalender und ABRA Flexi (siehe die Abschnitte zu Kalender und Rechnungen unten).

Was die API nicht kann

Die gesamte Telefonseite steuern Sie über API und MCP - Nummern, Anrufe, SMS, Agenten, Webhooks, Relay und die Do-not-call-Liste. Auch Ihr Profil, die Rechnungsadresse und die Firmendaten laufen über die API (Abschnitt Konto oben). Einige Dinge bleiben bewusst nur im Portal:

In der Gegenrichtung fehlt bewusst mehr als eines: Das Freigeben einer gekauften Nummer (DELETE /v1/numbers/{e164}), einer Mobilnummer (DELETE /v1/sms-numbers/{e164}) oder einer Nummer für Anrufe und SMS (DELETE /v1/voice-sms-numbers/{e164}) gibt es sowohl in der REST-API als auch im Portal, aber nicht unter den MCP-Tools - eine unumkehrbare Aktion ist dort nur einen missverstandenen Satz vom zu großen Risiko entfernt. Bewusst fehlen außerdem: der Download einer Aufnahme (ein binärer Body, GET /v1/calls/{id}/recording), das Detail einer einzelnen Nachricht oder eines Tools (die Auflistungen list_messages/list_tools enthalten dieselben Felder bereits, nur nicht für eine einzelne ID) und ein eigenes Testanruf-Tool - make_call mit agentId wählt denselben Anruf wie POST /v1/agents/{id}/test-call, nur ohne dessen strengeres Tageslimit von 3 Anrufen.

Konto

Profil, Notfalladresse, Rechnungsdaten und eine Übersicht der API-Schlüssel. Das Anlegen neuer API-Schlüssel (POST /v1/api-keys) ist hier nicht verfügbar - ein Schlüssel, der Schlüssel erzeugt, würde den Verlust eines einzigen zu dauerhaftem Zugriff machen. Neue Schlüssel legen Sie im Portal an (Bereich Zugang und API). E-Mail-Benachrichtigungen (callSummary, lowCredit, reactivation, productUpdates) sind über diese Schnittstelle nur LESBAR - Schreiben ist nur im Portal möglich, denn lowCredit ist die einzige Bremse zwischen einem leeren Guthaben und einem unbemerkten Ausfall.

curl https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "cs",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  },
  "testCalls": { "max": 3, "remaining": 2, "resetAt": 1755086400000 },
  "serviceStopped": null
}

curl -X PATCH https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"en"}'

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "en",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  }
}

curl -X PUT https://volai.cz/v1/account/billing \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Ukázková s.r.o.","dic":"SK9999999999","address":{"street":"Na Zámku 636","city":"Nehvizdy","zip":"250 81"}}'

{
  "billing": {
    "company": "Ukázková s.r.o.",
    "ico": null,
    "dic": "SK9999999999",
    "dicCountry": "SK",
    "dicVerified": true,
    "dicName": "Ukázková s.r.o."
  },
  "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
  "vies": { "dic": "SK9999999999", "country": "Slovakia", "name": "Ukázková s.r.o." }
}

curl -X POST https://volai.cz/v1/account/cancellation-request \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"callers_hang_up","note":"Volající zavěšují po první větě."}'

{
  "cancellationRequest": {
    "reason": "callers_hang_up",
    "note": "Volající zavěšují po první větě.",
    "requestedAt": 1793520000000,
    "alreadyRequested": false
  }
}

curl https://volai.cz/v1/api-keys \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "apiKeys": [
    {
      "id": "3f9a2c8e1b04",
      "label": "Production integration",
      "prefix": "vk_8h2j4kx",
      "createdAt": 1750000000000,
      "lastUsedAt": 1757280000000
    }
  ]
}

curl -X DELETE https://volai.cz/v1/api-keys/3f9a2c8e1b04 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "revoked": true
}

Guthaben

balanceHal und alle Tarife in dieser API verstehen sich ohne MwSt. - volai ist umsatzsteuerpflichtig, aber die MwSt. wird nur beim Aufladen des Guthabens per Karte im Portal angewendet (siehe die Seite /cenik), die API selbst rechnet sie nicht ein. Eine vollständige Anleitung mit Ablaufbeispielen finden Sie unter /docs/kredit.

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "balanceHal": 8730,
  "balanceCzk": 87.30,
  "currency": "CZK",
  "runway": { "dailyAverageHal": 2910, "runwayDays": 3 },
  "notice": { "kind": "runway", "days": 3 },
  "topupBalanceHal": 8730,
  "subscription": null,
  "serviceStopped": null
}

curl "https://volai.cz/v1/credit/ledger?limit=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "ledger": [
    { "id": "l_9f2a1c8e", "ts": 1757280000000, "type": "call_out", "amountHal": -420, "grossHal": null, "description": "Outbound call" },
    { "id": "l_7c1e9a2f", "ts": 1757193600000, "type": "number_fee", "amountHal": -9900, "grossHal": null, "description": "Monthly number fee for +420601234567" },
    { "id": "l_3b7e1c9a", "ts": 1757107200000, "type": "topup", "amountHal": 50000, "grossHal": 60500, "description": "Card top-up" }
  ]
}

curl -X POST https://volai.cz/v1/credit/topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-2026-09-08-01" \
  -d '{"amountCzk": 500}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 10000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X PATCH https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thresholdHal": 20000}'

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 20000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X POST https://volai.cz/v1/credit/auto-topup/setup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: autotopup-setup-2026-09-08-01" \
  -d '{"thresholdHal": 10000, "amountHal": 50000}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X POST https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X DELETE https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "removed": true
}

curl https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "spendCap": {
    "enabled": true,
    "capHal": 500000,
    "warnShare": 0.8,
    "inboundAboveCap": false,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": 316600,
    "reached": false,
    "updatedAt": 1793520000000
  }
}

curl -X PUT https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capHal": 500000, "warnShare": 0.8, "inboundAboveCap": false}'

{
  "spendCap": {
    "enabled": true,
    "capHal": 500000,
    "warnShare": 0.8,
    "inboundAboveCap": false,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": 316600,
    "reached": false,
    "updatedAt": 1793520000000
  }
}

curl -X DELETE https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "spendCap": {
    "enabled": false,
    "capHal": null,
    "warnShare": null,
    "inboundAboveCap": null,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": null,
    "reached": false,
    "updatedAt": null
  }
}

curl "https://volai.cz/v1/billing/documents?limit=2" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "documents": [
    {
      "id": "inv_4kX9mQ2pRtLz",
      "number": "VF2026000042",
      "issuedAt": 1757280000000,
      "taxableAt": 1757280000000,
      "netHal": 50000,
      "vatHal": 10500,
      "grossHal": 60500,
      "vatRatePercent": 21,
      "reverseCharge": false,
      "kind": "invoice",
      "description": "Prepaid credit for volai telecommunications services",
      "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
      "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
      "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "document": {
    "id": "inv_4kX9mQ2pRtLz",
    "number": "VF2026000042",
    "issuedAt": 1757280000000,
    "taxableAt": 1757280000000,
    "netHal": 50000,
    "vatHal": 10500,
    "grossHal": 60500,
    "vatRatePercent": 21,
    "reverseCharge": false,
    "kind": "invoice",
    "description": "Prepaid credit for volai telecommunications services",
    "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
    "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
  }
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -o invoice.pdf

Monatstarif

Ein Monatstarif belastet die gespeicherte Karte einmal im Monat und fügt monatliches Guthaben hinzu, das vor dem aufgeladenen Guthaben verbraucht wird und am Ende des Zeitraums verfällt. Jede Stufe hat einen Preis und ein größeres Monatsguthaben, beides ohne MwSt. (siehe tiers in GET /v1/subscription). Geld bewegt sich nur, wenn ein Mensch an der Karte sitzt: Diese API startet oder erhöht wiederkehrende Abbuchungen nie von selbst. Das Starten eines Tarifs, das Bezahlen einer fehlgeschlagenen Verlängerung und das Ersetzen der Karte liefern einen Stripe-Checkout-Link, und das Erhöhen der Stufe, das Fortsetzen eines zum Ende vorgemerkten Tarifs oder der Wechsel zu Aufladungen von der Karte liefert eine confirmUrl, die ein Mensch im Portal bestätigen muss. Eine vollständige Anleitung finden Sie unter /docs/kredit.

curl https://volai.cz/v1/subscription \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "subscription": {
    "tier": "990",
    "status": "active",
    "periodStart": "2026-10-17T08:00:00.000Z",
    "periodEnd": "2026-11-17T09:00:00.000Z",
    "monthlyCreditHal": 130000,
    "monthlyRemainingHal": 98500,
    "exhaustionMode": "topup",
    "cancelAtPeriodEnd": false,
    "nextTier": null,
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  },
  "tiers": [
    {
      "id": "490",
      "priceHal": 49000,
      "creditHal": 60000
    },
    {
      "id": "990",
      "priceHal": 99000,
      "creditHal": 130000
    },
    {
      "id": "1990",
      "priceHal": 199000,
      "creditHal": 280000
    }
  ],
  "topupBalanceHal": 8500,
  "available": false,
  "recommendation": {
    "spendHal": 105500,
    "days": 30,
    "cheapestPath": "plan",
    "tier": "490",
    "tierTotalHal": 94500,
    "savingsHal": 11000,
    "worthIt": true,
    "steady": true,
    "options": [
      {
        "path": "per_second",
        "tier": null,
        "totalHal": 105500
      },
      {
        "path": "plan",
        "tier": "490",
        "totalHal": 94500
      },
      {
        "path": "plan",
        "tier": "990",
        "totalHal": 99000
      },
      {
        "path": "plan",
        "tier": "1990",
        "totalHal": 199000
      }
    ]
  },
  "previousPeriod": {
    "tier": "990",
    "periodStart": "2026-09-17T08:00:00.000Z",
    "periodEnd": "2026-10-17T08:00:00.000Z",
    "creditHal": 130000,
    "usedHal": 105500,
    "usedPercent": 81,
    "overHal": 0,
    "expiredHal": 24500,
    "exhaustionMode": "topup",
    "exhaustedAt": null
  }
}

curl -X POST https://volai.cz/v1/subscription/checkout \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: plan-2026-10-17-01" \
  -d '{"tier": "990", "exhaustionMode": "cap", "consumerConsent": true}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X PATCH https://volai.cz/v1/subscription \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "490"}'

{
  "subscription": {
    "tier": "990",
    "status": "active",
    "periodStart": "2026-10-17T08:00:00.000Z",
    "periodEnd": "2026-11-17T09:00:00.000Z",
    "monthlyCreditHal": 130000,
    "monthlyRemainingHal": 98500,
    "exhaustionMode": "topup",
    "cancelAtPeriodEnd": false,
    "nextTier": "490",
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  }
}

curl -X POST https://volai.cz/v1/subscription/pay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: plan-pay-2026-11-18-01"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X POST https://volai.cz/v1/subscription/card \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: plan-card-2026-11-18-01"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

Aufgaben

Eine Aufgabe wählt mit einem Agenten eine Liste von Empfängern an, nach vorab festgelegten Regeln (Budget, Anrufzeitfenster, Zahl der Versuche) - nichts wird gewählt, bevor Sie sie selbst starten (POST .../start). Eine vollständige Anleitung mit CSV-Import, Status und globalem Durchsatz finden Sie unter /docs/ukoly. Ein Agent mit einer Nummer für Anrufe und SMS ruft in einer Kampagne nur tschechische Nummern (+420) an, und von der Nummer läuft immer nur ein Anruf gleichzeitig: Ein Kontakt mit einer anderen Nummer kommt in die Prüfung, während die Aufgabe die übrigen weiter anruft, und eine belegte Nummer lässt die Aufgabe kurz warten.

curl https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "tasks": [
    {
      "id": "task_9f3a2c1d",
      "name": "Payment reminder - September",
      "agentId": "ag_4e91a2f0",
      "taskType": "custom",
      "purpose": "standard",
      "source": "manual",
      "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
      "maxAttempts": 2,
      "maxDurationSecs": 120,
      "budgetHal": 50000,
      "reservedBudgetHal": 0,
      "spentHal": 0,
      "status": "draft",
      "revision": 0,
      "createdAt": 1757280000000,
      "updatedAt": 1757280000000,
      "items": [
        { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
      ]
    }
  ]
}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/registrations \
  -H "Authorization: Bearer vk_YOUR_KEY"

{"registration":null,"operation":null}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/registrations \
  -H "Authorization: Bearer vk_YOUR_KEY" -H "Content-Type: application/json" \
  --data-binary @petcenter-manifest-operation.json

{"registration":{"manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","taskCount":19,"updatedAt":1791802800000},"operation":{"operationId":"registration-2026-10-12","manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","taskCount":19,"acceptedAt":1791802800000,"replayed":false}}

curl 'https://volai.cz/v1/outbound/dispatch-scopes/petcenter/pauses?operationId=pause-batch-2026-10-12-01' \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "operation": {
    "operationId": "pause-batch-2026-10-12-01",
    "manifestSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "requestHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "tasks": [{ "taskId": "task_abcdefgh", "revision": 12 }],
    "acceptedAt": 1791802800000,
    "complete": true,
    "outcomes": [{ "taskId": "task_abcdefgh", "outcome": "paused", "revision": 13 }]
  }
}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/pauses \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"pause-batch-2026-10-12-01","manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","tasks":[{"taskId":"task_abcdefgh","revision":12}]}'

{
  "operation": {
    "operationId": "pause-batch-2026-10-12-01",
    "manifestSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "requestHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "tasks": [{ "taskId": "task_abcdefgh", "revision": 12 }],
    "acceptedAt": 1791802800000,
    "complete": true,
    "outcomes": [{ "taskId": "task_abcdefgh", "outcome": "paused", "revision": 13 }]
  }
}

curl -X POST https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-2026-09-08-01" \
  -d '{
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "maxAttempts": 2,
    "budgetHal": 50000,
    "recipients": [
      { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
    ]
  }'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ],
    "issues": []
  }
}

curl -X PATCH https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 0, "budgetHal": 80000}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 1,
    "createdAt": 1757280000000,
    "updatedAt": 1757280060000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/start \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-start-2026-09-08-01" \
  -d '{"revision": 1}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/pause \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 2}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "paused",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280180000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl "https://volai.cz/v1/tasks/task_reminder_9f3a/items/item_1a2b3c/reminder-call?callId=c_reminder_7e2d" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "reminderCall": {
    "callId": "c_reminder_7e2d",
    "tenantId": "u_4a8d2c",
    "agentId": "ag_4e91a2f0",
    "taskId": "task_reminder_9f3a",
    "taskItemId": "item_1a2b3c",
    "dispatchIntentId": "dispatch_8d2a4f",
    "purpose": "coupon_reminder",
    "phoneSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "direction": "out",
    "status": "no_answer",
    "startedAt": 1791882000000,
    "durationSecs": 0,
    "priceHal": 0,
    "endReason": "no_answer",
    "optOutRequested": false,
    "hasConversation": false,
    "quality": {
      "turnFailures": { "observed": false, "count": null },
      "toolFailures": { "observed": false, "count": null },
      "dismissReminder": { "observed": true, "invoked": false }
    }
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/items/item_1a2b3c/resolve \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry", "revision": 5}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 2400,
    "spentHal": 0,
    "status": "needs_attention",
    "revision": 6,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "reviewReason": "billing_unknown",
    "items": [
      {
        "id": "item_1a2b3c",
        "phone": "+420777123456",
        "variables": { "jmeno": "Jana Novakova" },
        "paymentStatus": "not_applicable",
        "status": "pending",
        "attempts": [
          { "id": "attempt_7c2d", "startedAt": 1757280180000, "finishedAt": 1757280230000, "providerCallId": "c_late_price", "outcome": "completed" }
        ],
        "reviewReason": "billing_unknown",
        "providerCallId": "c_late_price",
        "estimatedCostHal": 2400,
        "reservedCostHal": 2400
      }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/reconcile \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "completed",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/process \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-process-2026-10-08-tick-001" \
  -d '{"revision": 2}'

{
  "status": "idle",
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [], "nextAttemptAt": 1757280180000 }
    ]
  }
}

curl -X DELETE "https://volai.cz/v1/tasks/task_9f3a2c1d?revision=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "deleted": true
}

curl -X POST https://volai.cz/v1/tasks/csv-preview \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv": "phone,jmeno\n+420777123456,Jana Novakova\nneplatne,Petr Svoboda\n"}'

{
  "headers": ["phone", "jmeno"],
  "delimiter": ",",
  "rows": [
    { "line": 2, "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "errors": [] },
    { "line": 3, "variables": { "jmeno": "Petr Svoboda" }, "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }] }
  ],
  "validRows": [
    { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
  ],
  "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }]
}

Nummern

curl "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800}}

curl -X PUT "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentIds":["ag_campaign"],"lookbackSecs":604800}'

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800},"engineSyncRequired":true}

curl https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "numbers": [
    {
      "e164": "+420601234567",
      "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
      "monthlyFeeHal": 2500,
      "boughtAt": 1756111640000,
      "region": "objednavka",
      "regionLabel": "Czech number",
      "billingMonths": 1
    }
  ]
}

curl "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl -X POST https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "number": {
    "e164": "+420266266647",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "praha",
    "regionLabel": "Prague",
    "billingMonths": 1
  }
}

curl https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "offers": [
    { "offerId": "praha", "label": "Prague", "joined": false, "available": true },
    { "offerId": "brno", "label": "Brno", "joined": true, "available": false },
    { "offerId": "internet", "label": "Internet number", "joined": false, "available": true },
    { "offerId": "bratislava", "label": "Bratislava", "joined": false, "available": true }
  ]
}

curl -X POST https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offerId": "brno"}'

{
  "joined": true
}

curl -X DELETE https://volai.cz/v1/numbers/waitlist/brno \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "left": true
}

curl "https://volai.cz/v1/numbers/available?region=brno" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "region": "brno",
  "numbers": ["+420510510129", "+420510510132"],
  "regions": [
    {
      "id": "praha",
      "label": "Prague",
      "description": "A landline with a Prague area code.",
      "numbers": ["+420266266643", "+420266266645"]
    },
    {
      "id": "brno",
      "label": "Brno",
      "description": "A landline with a Brno area code.",
      "numbers": ["+420510510129", "+420510510132"]
    },
    {
      "id": "internet",
      "label": "Internet number",
      "description": "Area code 910, not tied to any region - works from anywhere.",
      "numbers": ["+420910084099"]
    },
    {
      "id": "bratislava",
      "label": "Bratislava",
      "description": "A Slovak number with the Bratislava area code +421 2. Billed three months upfront.",
      "numbers": ["+421222205798"]
    }
  ]
}

curl "https://volai.cz/v1/numbers/address-options?psc=70200&obec=554821&cobce=413950" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "obce": [{ "value": "554821", "label": "Ostrava" }],
  "casti": [{ "value": "413950", "label": "Moravská Ostrava" }],
  "ulice": [{ "value": "353710", "label": "28. října" }],
  "cp": [],
  "recap": null
}

curl -G https://volai.cz/v1/numbers/address-options \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  --data-urlencode "query=Nádražní 100, 702 00 Ostrava"

{
  "obce": [],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": "28. října 102/1, Ostrava, 70200",
  "selection": {
    "psc": "70200",
    "obec": "554821",
    "cobce": "413950",
    "ulice": "353710",
    "cp": "3180026"
  }
}

{
  "obce": [
    { "value": "554821", "label": "Ostrava" },
    { "value": "554813", "label": "Fulnek" }
  ],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": null,
  "selection": { "psc": "70200", "obec": "", "cobce": "", "ulice": "", "cp": "" },
  "ambiguousLevel": "obec",
  "message": "The given address is ambiguous - choose the municipality (obec) from the options. Repeat the query WITHOUT query and with the step parameters: psc=70200, obec=<value from the options>."
}

curl -X POST https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"psc":"70200","obec":"554821","cobce":"413950","ulice":"353710","cp":"3180026"}'

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "pending",
    "address": "70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756111640000
  }
}

curl https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "orders": [
    {
      "id": "Xa3Kd9pQmR2v",
      "status": "done",
      "address": "28. října 102/1, Ostrava, 70200",
      "e164": "+420596123456",
      "createdAt": 1756111640000,
      "updatedAt": 1756118840000
    }
  ]
}

curl -X POST https://volai.cz/v1/numbers/orders/Xa3Kd9pQmR2v/cancel \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "cancelled",
    "address": "28. října 102/1, Ostrava, 70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756112240000
  }
}

curl -X DELETE "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "agent", "agentId": "ag_kx91fa2b"}}'

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

curl "https://volai.cz/v1/numbers/+420601234567/sip/status" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "target": { "kind": "own_line", "host": null },
  "registration": { "registered": true },
  "lastInbound": {
    "at": 1756118900000,
    "status": "completed",
    "from": "+420777123456",
    "recent": true
  },
  "serviceStopped": null
}

Nachrichten

curl "https://volai.cz/v1/messages?limit=20&direction=all" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "messages": [
    {
      "id": "msg_5b7e0d93",
      "to": "+420777123456",
      "from": "+420770112233",
      "body": "Bestätigt, wir sehen uns am Freitag um 10:00 Uhr. - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 190,
      "segments": 1,
      "createdAt": 1756112200000,
      "source": "api",
      "direction": "out",
      "smsNumber": "+420770112233",
      "deliveryStatus": "delivered"
    },
    {
      "id": "msg_3d9b5e71",
      "to": "+420770112233",
      "from": "+420777123456",
      "body": "Danke, ich komme am Freitag um 10:00 Uhr.",
      "status": "received",
      "failReason": null,
      "priceHal": 0,
      "segments": 1,
      "createdAt": 1756111900000,
      "source": "inbound",
      "direction": "in",
      "smsNumber": "+420770112233",
      "deliveryStatus": null
    },
    {
      "id": "msg_7c1f9a2e",
      "to": "+420777123456",
      "from": "volai",
      "body": "Hallo von volai! - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 136,
      "segments": 1,
      "createdAt": 1756111500000,
      "source": "api",
      "direction": "out",
      "smsNumber": null,
      "deliveryStatus": null
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/messages" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_MESSAGES_ID" \
  -d '{"to":"+420777123456","body":"Hallo von volai! - My App"}'

{
  "id": "msg_7c1f9a2e",
  "status": "sent",
  "priceHal": 136,
  "segments": 1
}

Der status einer Nachricht: pending (gespeichert, wird noch gesendet), sent (der Netzbetreiber hat die Nachricht zum Senden angenommen, auch eingereihte Nachrichten; das ist keine Zustellbestätigung), failed (der Netzbetreiber hat sie abgelehnt, bei einer von einer Mobilnummer gesendeten Nachricht möglicherweise erst nachträglich - nicht berechnet, bereits abgebuchtes Guthaben wird erstattet, priceHal 0), received (eine auf Ihrer Mobilnummer oder Nummer für Anrufe und SMS empfangene Nachricht, immer mit direction: "in" und priceHal 0) und unknown (der Netzbetreiber hat die Annahme nicht bestätigt, typischerweise wegen eines Timeouts seiner Antwort) - sie wird dennoch zum vollen Preis berechnet, da die Nachricht durchgegangen sein kann. Bei einer von einer Mobilnummer gesendeten Nachricht kann sich unknown noch von selbst ändern: zu sent mit einem deliveryStatus, sobald der Netzbetreiber die Nachricht bestätigt, oder zu failed mit erstattetem Guthaben, wenn er sie ablehnt. Erhalten Sie unknown, senden Sie sie bitte nicht blind erneut - wenden Sie sich an den Support, und wir erstatten jede doppelte Berechnung.

Bei status: "failed" erhalten Sie außerdem failReason: unsupported_characters (ein Emoji oder Zeichen, das das Netz nicht zustellen kann), unsupported_recipient (das Netz akzeptiert die Nummer nicht), forbidden_sender und low_balance (ein Fehler auf unserer Seite), gateway_failed (das Gateway des Betreibers), network_rejected (eine sonstige Ablehnung), opted_out (der Empfänger hat auf Ihre Mobilnummer mit STOP geantwortet). Bei anderen Status ist es null.

deliveryStatus (delivered oder undelivered) ist der Zustellbericht des Netzbetreibers und existiert nur für Nachrichten, die von Ihrer Mobilnummer gesendet wurden. Er ist null für Nachrichten, die unter dem gemeinsamen Namen SMSinfo gesendet wurden, der keine Zustellberichte hat, für Nachrichten, die von einer Nummer für Anrufe und SMS gesendet wurden, die ebenfalls keine hat, und für empfangene Nachrichten. sent bedeutet weiterhin nur, dass der Netzbetreiber die Nachricht angenommen hat, und belegt keine Zustellung. Eine Nachricht mit undelivered wird dennoch berechnet, weil der Netzbetreiber sie angenommen hat. Meldet der Netzbetreiber später einen Fehler, wechselt der status der Nachricht zu failed, priceHal fällt auf 0, und das Guthaben dafür wird erstattet. Der Zustellbericht kommt, sobald der Netzbetreiber ihn meldet; trifft die Statusbenachrichtigung nicht ein, füllt ihn eine regelmäßige Prüfung alle 15 Minuten nach. Meldet ihn der Netzbetreiber nie, bleibt er null.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "fromNumber": "+420770112233", "body": "Bestätigt, wir sehen uns am Freitag um 10:00 Uhr. - My App"}'

{
  "id": "msg_5b7e0d93",
  "status": "sent",
  "priceHal": 190,
  "segments": 1
}

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Příliš žluťoučký kůň úpěl ďábelské ódy - a tahle věta má přes sedmdesát znaků, takže spadne do druhého segmentu."}'

{
  "id": "msg_9a3f1c7d",
  "status": "sent",
  "priceHal": 272,
  "segments": 2
}

curl https://volai.cz/v1/messages/msg_7c1f9a2e \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "message": {
    "id": "msg_7c1f9a2e",
    "to": "+420777123456",
    "from": "volai",
    "body": "Hallo von volai! - My App",
    "status": "sent",
    "failReason": null,
    "priceHal": 136,
    "segments": 1,
    "createdAt": 1756111500000,
    "source": "api",
    "direction": "out",
    "smsNumber": null,
    "deliveryStatus": null
  }
}

Mobilnummern

curl https://volai.cz/v1/sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "smsNumbers": [
    {
      "number": "+420770112233",
      "status": "active",
      "createdAt": 1756111640000,
      "monthlyFeeHal": 29000,
      "nextChargeAt": 1758703640000,
      "dailySendLimit": 20,
      "dailySendRemaining": 17,
      "dailySendResetsAt": 1756198040000
    }
  ]
}

curl -X POST "https://volai.cz/v1/sms-numbers" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_SMS_NUMBERS_ID"

{
  "smsNumber": {
    "number": "+420770112233",
    "status": "active",
    "createdAt": 1756111640000,
    "monthlyFeeHal": 29000,
    "nextChargeAt": 1758703640000,
    "dailySendLimit": 20,
    "dailySendRemaining": 20,
    "dailySendResetsAt": null
  }
}

curl -X DELETE "https://volai.cz/v1/sms-numbers/+420770112233" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

Nummer für Anrufe und SMSs

Die Nummer für Anrufe und SMS ist eine dritte Art von Nummer neben Sprachnummern und Mobilnummern: eine Prager Festnetznummer (+420 2xx), die Anrufe und SMS empfängt und von der Ihr Agent anruft und SMS sendet. Eine Sprachnummer kann keine SMS empfangen, und eine Mobilnummer hat keine Anrufe. Die Nummer wird beim Betreiber im Namen des volai-Dienstanbieters registriert, und Sie nutzen sie; nach der Bestellung ist sie meist innerhalb von 1 Werktag aktiv, spätestens nach 48 Stunden, und die Gebühr wird erst nach der Aktivierung berechnet. Eingehende Anrufe nimmt ein Agent an, der auf der eigenen Sprach-Engine von volai läuft, und die Nummer verarbeitet höchstens zwei gleichzeitige Anrufe. Der SMS-Empfang wurde im Netz von O2 geprüft, und Verifizierungscodes von Diensten garantieren wir nicht. Mit country im Bestell-Body erhalten Sie statt der Prager Nummer eine Nummer in einem anderen Land: eine Festnetz-Nummer in einem anderen Land, die Anrufe empfängt (ein Agent nimmt sie an), aber keine SMS hat (sie weder empfängt noch sendet) und nur in das Land der Nummer und nach Tschechien anruft. Der Preis hängt vom Land ab (lesen Sie ihn aus monthlyFeeHal des Landes in GET /v1/voice-sms-numbers/countries), und die übrigen Regeln sind dieselben wie bei der Prager Nummer; die Nummer wird beim Betreiber im Namen des Anbieters mit einer Adresse in diesem Land registriert und ist meist innerhalb von 1 Werktag aktiv, spätestens nach 3 Werktagen (innerhalb einer Stunde in Ländern ohne Registrierung). Die Länder, in denen Sie bestellen können, ändern sich, lesen Sie sie also aus GET /v1/voice-sms-numbers/countries (MCP list_voice_sms_countries) und führen Sie nie eines aus dem Gedächtnis auf. Sie bestellen selbst im Portal, über REST (POST /v1/voice-sms-numbers) oder MCP (order_voice_sms_number), nach Ihrer ersten Guthabenaufladung. Sind Bestellungen vorübergehend pausiert, liefert die Bestellung voice_sms_numbers_unavailable, und es wird nichts berechnet; versuchen Sie es später erneut oder schreiben Sie an den Support.

curl https://volai.cz/v1/voice-sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "voiceSmsNumbers": [
    {
      "number": "+420292000001",
      "country": "CZ",
      "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
      "status": "active",
      "routing": { "mode": "agent", "agentId": "ag_9f3a2b7c4d1e", "sipTarget": "engine", "hasSipPassword": false },
      "monthlyFeeHal": 4900,
      "smsFromNumberHal": 250,
      "nextChargeAt": 1758703640000,
      "smsInboundReady": true,
      "createdAt": 1756101640000,
      "activatedAt": 1756111640000
    }
  ],
  "pendingOrders": [{ "createdAt": 1758790000000, "country": "CZ" }]
}

curl https://volai.cz/v1/voice-sms-numbers/countries \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "countries": [
    {
      "country": "CZ",
      "name": "Czechia",
      "prefix": "+420",
      "numberKind": "landline, Prague (+420 2)",
      "sms": true,
      "outboundTo": ["CZ"],
      "activation": "within_business_days",
      "monthlyFeeHal": 4900
    },
    {
      "country": "GB",
      "name": "United Kingdom",
      "prefix": "+44",
      "numberKind": "landline, London (+44 20)",
      "sms": false,
      "outboundTo": ["CZ"],
      "activation": "within_hour",
      "monthlyFeeHal": 2900
    }
  ],
  "waitlisted": ["NL"]
}

curl -X POST https://volai.cz/v1/voice-sms-numbers/countries/NL/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "country": "NL",
  "joined": true,
  "alreadyJoined": false
}

# Example: a number in another country (choose the country from GET /v1/voice-sms-numbers/countries)
curl -X POST https://volai.cz/v1/voice-sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"GB"}'

{
  "voiceSmsNumber": {
    "number": "+442000000001",
    "country": "GB",
    "capabilities": { "calls": true, "sms": false, "outboundTo": ["CZ"] },
    "status": "awaiting_registration",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2900,
    "smsFromNumberHal": null,
    "nextChargeAt": null,
    "smsInboundReady": false,
    "createdAt": 1756101640000,
    "activatedAt": null
  }
}

curl -X POST "https://volai.cz/v1/voice-sms-numbers" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_VOICE_SMS_NUMBERS_ID"

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "awaiting_registration",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": null,
    "smsInboundReady": false,
    "createdAt": 1756101640000,
    "activatedAt": null
  }
}

curl "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "active",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": 1758703640000,
    "smsInboundReady": true,
    "createdAt": 1756101640000,
    "activatedAt": 1756111640000
  }
}

curl -X PATCH "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing":{"mode":"agent","agentId":"ag_9f3a2b7c4d1e"}}'

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "active",
    "routing": { "mode": "agent", "agentId": "ag_9f3a2b7c4d1e", "sipTarget": "engine", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": 1758703640000,
    "smsInboundReady": true,
    "createdAt": 1756101640000,
    "activatedAt": 1756111640000
  }
}

curl -X POST "https://volai.cz/v1/voice-sms-numbers/+420292000001/cancel" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "cancelled": true
}

curl -X DELETE "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

Anrufe

curl "https://volai.cz/v1/calls?limit=20" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "calls": [
    {
      "id": "c_8f2ac1d4",
      "direction": "in",
      "from": "+420777123456",
      "to": "+420601234567",
      "status": "completed",
      "startedAt": 1756111400000,
      "durationSecs": 47,
      "priceHal": 236,
      "agentId": "ag_kx91fa2b",
      "note": null,
      "flag": null,
      "handledAt": null,
      "rating": null,
      "goal": null,
      "hasConversation": true,
      "source": "inbound",
      "kind": "inbound",
      "endReason": "completed",
      "hasRecording": true,
      "data": {
        "name": "Erika Mustermann",
        "coffee_count": 2,
        "urgency": "normal"
      }
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/calls" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_CALLS_ID" \
  -d '{"to":"+420777123456","agentId":"ag_kx91fa2b","variables":{"jmeno_zakaznika":"Jana","cislo_objednavky":"A-42"},"ringingTimeoutSecs":30}'

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420777123456",
    "systemPrompt": "Sie sind die Rezeption im Café Nula. Sie nehmen Bestellungen zur Abholung entgegen und fassen sich kurz und freundlich.",
    "firstMessage": "Guten Tag, hier ist der Testagent von volai, wie kann ich Ihnen helfen?"
  }'

{
  "id": "c_2f7a91mn",
  "status": "initiated",
  "trial": true,
  "from": "+420266266641"
}

curl -X POST "https://volai.cz/v1/voice-messages" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_VOICE_MESSAGES_ID" \
  -d '{"to":"+420777123456","text":"Achtung: Der Server api-1 antwortet seit fünf Minuten nicht mehr. Bitte prüfen Sie seinen Status.","repeat":2}'

{
  "id": "c_k4m8p2q7r1s5",
  "status": "ringing",
  "from": "+420266266641"
}

{
  "call": {
    "id": "c_k4m8p2q7r1s5",
    "direction": "out",
    "from": "+420266266641",
    "to": "+420777123456",
    "status": "completed",
    "kind": "voice_message",
    "durationSecs": 17.4,
    "voiceMessage": {
      "text": "...",
      "repeat": 2,
      "repeatPlayed": 2,
      "completed": true
    }
  }
}

curl -X POST "https://volai.cz/v1/rings" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_RINGS_ID" \
  -d '{"to":"+420777123456","from":"+420601234567","ringSecs":10}'

{
  "id": "c_x7f2k9a1b3c4",
  "status": "initiated",
  "kind": "ring",
  "from": "+420601234567",
  "to": "+420777123456",
  "requestedSecs": 10,
  "priceHal": 25
}