Trovacast

Resources

Changelog

What changed in the Trovacast API and its SDKs, newest first. Within v1 every change is additive.

Within v1 the API changes only additively — new endpoints, optional fields, enum values, event types and error codes — so an integration that ignores what it does not know keeps working; only a security fix may tighten a default, always announced in the changelog (Versioning).

API

  1. A +1 call is held to the called party's own local time

    Unreleased

    Added

    • PATCH /v1/settings/calls takes recordingRequired — the console's "Record every call" — alone or with aiCallsEnabled (at least one of the two; aiCallsEnabled is no longer required). false lets each call say whether it is recorded (recording.enabled, a flow's record); true records every call, and POST /v1/calls then needs recording.consentEvidence. A new organization still starts with it on. Same compare-and-set on version, audited against the key (organization.updated, recordingRequired.from / .to). An integration acting for an organization it provisioned (with settings:write delegated) can now set that organization's recording policy without the console.
    • A test organization's call settings can be set with a test key: PATCH /v1/settings/calls with a tc_test_ key acting for a test organization (livemode: false — one a test integration key provisioned) now sets aiCallsEnabled and recordingRequired, which its sandbox calls and AI routes follow, so an integration can exercise AI answering end to end without the console. A test organization has no live side to protect. A test key on a live organization is still 422 TEST_MODE_UNSUPPORTED, and the TCPA acknowledgement, Verify and SMS settings are unchanged (a test key changes none).
    • A call flow can tell the caller's keys: "events": { "dtmf": true } on a flow document (stored flows, a FLOW call's definition, a number's route document) has every key the caller presses during the flow's steps — into a gather or a menu, or while nothing listens — told as the opt-in call.dtmf, as an AI conversation's are; never a key pressed into a sensitive gather, never a dialled party's. sequence now counts through all of a call's keys, a flow's and its AI steps' alike. Test calls tell their scripted keys the same way.
    • Staff-first click-to-call over the API: POST /v1/calls (mode: BRIDGE) takes bridge.to.phoneId, one of your own phones (/v1/phones), rung by id so your staff's number never leaves the platform. With ringFirst: agent it rings that phone first and dials the contact once it answers (assigned to no one; a phone already on a call is 409); with the contact first, the contact is connected to it. Either way it is your staff's own handset, never held to the called party's calling window. A phoneId that is not one of your phones is 400 VALIDATION_FAILED. The call's bridge gains phoneId and target: "phone".
    • An SMS refused once its recipient is known — no opt-in (CONSENT_REQUIRED), an opt-out, the sender, the window — carries the contact's contactId in the error body, as WhatsApp and email refusals already did, so a send by to.phone that created the contact can record its consent and retry.
    • Verification is country-aware. GET /v1/verifications/requirements publishes what a business must give in a country — its profile (in, us, gb, eu for the 27 member states, international for any other), each identifier the country collects (local label, example, and the older field that carries it), a US state of registration's codes, and for each type of business its local name, fields, identifiers asked and owed (any-of groups: an EU business gives a VAT number or its national registration number) and documents — so a form needs no country table of its own. POST /v1/verifications takes identifiers (by kind: gstin, pan, cin, ein, company_number, vat_number, registration_number, tax_number) and jurisdiction (a US state of registration); gstin, pan and cin keep working as the kinds they stand for in the business's country. The verification resource gains business.jurisdiction, identifiers.last4ByKind, requirements.profile and requirements.identifiers; a refused submission (422 VERIFICATION_INCOMPLETE) gains missingIdentifiers. A new document type, tax_registration (an EIN letter, a VAT certificate).
    • POST /v1/sandbox/verifications/review (test keys only) decides a test organization's submitted verification — approved, needs more information, or rejected with a note — as a reviewer would, so an integration scripts every outcome; verified stays false (a test organization never goes live).
    • India in the sandbox: a test key orders +91 sandbox numbers — +91 <area> 0000 0XXX in Delhi (11), Mumbai (22), Kolkata (33), Hyderabad (40), Chennai (44) and Pune (20), subscriber numbers no Indian exchange can issue (a leading 0 is the trunk prefix in every SDCA) — routes them and takes simulated and outbound test calls on them as on US and UK ones. They are local and cannot text (an Indian business texts from its DLT header). Strict phone validation (libphonenumber's full metadata) calls them invalid; its default metadata accepts them.
    • GET /v1/sms/registration says which SMS registration regime applies to the organization's country — dlt (India), us_10dlc (the US), sender_id (the UK) or none — and where it stands under it, step by step, counted from its own records.
    • One webhook feed for an integration: with the new integration scope organizations:events, an integration key registers its own endpoints (/v1/integration/webhook-endpoints — create, list, get, update, delete, rotate-secret, test, deliveries, resend one, resend in bulk) that receive the events of every organization the integration provisioned, signed, retried, paused and resent exactly as an organization's endpoints are (which keep working beside them). GET /v1/integration/events (and …/{eventId}) reads the stored events back across those organizations, optionally one organization's (organizationId). An endpoint carries only the event types whose reading scopes the platform delegated to the integration (403 API_KEY_SCOPE_MISSING naming the scope otherwise), and takes the key's mode (a test key's receives test traffic). A webhook.test to an integration endpoint names no organization (organizationId is the nil UUID) and carries integrationId.
    • Event envelopes (deliveries and GET /v1/events) of an organization an integration provisioned carry externalReference, the integration's own reference for it, beside organizationId.
    • The integrator pays: billing: { payer: "integration" | "organization", spendCap?: { amountMinor, period: "month" } } on POST and PATCH /v1/organizations bills an organization's calls, messages, plan fees and numbers to the integration's billing organization (set by the platform; 409 BILLING_PAYER_NOT_CONFIGURED until it is), each ledger entry naming the organization; refunds and re-ratings go back to the wallet that was charged. The organization resource and GET /v1/balance gain billing (payer, cap, this month's spend). A dial, send or number activation past the monthly cap is 402 BILLING_SPEND_CAP_REACHED (spendCapMinor, spentThisPeriodMinor; also a message's failure.code when the send worker refuses it); a top-up of an organization its integration pays for is 409 BILLING_PAID_BY_INTEGRATION. New GET /v1/organizations/{organizationId}/usage (getOrganizationUsage, organizations:read): one organization's usage rows, as its own GET /v1/usage. GET /v1/usage?breakdown=organization breaks a billing organization's spend down by the organizations it paid for (each row's organizationId), and statements (GET /v1/invoices…) carry paidFor.
    • Acting for an organization (integration keys): an integration key holding the new scope organizations:act sends Trovacast-Organization: <organizationId> on any organization route and the request is that organization's — one the integration provisioned — with the scopes the platform delegated to the integration (none by default). Another integration's organization is 404; a suspended one 409 ORGANIZATION_NOT_ACTIVE; an undelegated scope 403 API_KEY_SCOPE_MISSING. Writes are audited in the organization naming the integration and key; Idempotency-Key, the rate limit and the request log are per organization. GET /v1/me answers the integration's delegatedScopes and, with the header, actingFor. A live key acting for an organization that awaits its business verification is refused except on /v1/verifications. The SDKs take an organization option.
    • Test integration keys (tc_test_…): their POST /v1/organizations provisions test organizations (livemode: false on the organization — test keys only, never billed, never live), and acting for an organization they reach its test partition and the sandboxes. Each mode's organizations are its own: a key finds and administers its own mode's only.
    • An integration's terms, and calling for the organizations it provisions: POST /v1/organizations takes entitlements ({ calling, messaging }, messaging only by default), planId (your default plan by default) and country (ISO 3166-1 alpha-2, the deployment's home country by default), and the new PATCH /v1/organizations/{organizationId} (updateOrganization, organizations:write) renames an organization, switches its product lines and moves its plan. Both stay within your integration's terms, which the platform sets: the ceilings and plan list of the partner it binds your integration to (your organizations become that partner's clients), or messaging on your default plan when it binds none. New error codes PRODUCT_LINE_NOT_OFFERED (409, line) and PLAN_NOT_OFFERED (409, planId). The organization resource gains planId and country. The platform may also require your organizations to pass business verification before live features.
    • Caps on counted resources are deployment settings with a per-organization override: the sending domains an organization may hold (EMAIL_DOMAIN_LIMIT_PER_ORGANIZATION, default 10 — a constant until now) and its subaccounts (SUBACCOUNT_LIMIT_PER_PARENT, default 10), each of which the platform can raise or lower for one organization. 409 EMAIL_DOMAIN_LIMIT now carries limit (the cap that applies, as SUBACCOUNT_LIMIT_REACHED already did).
    • Simulated inbound calls (T8): POST /v1/sandbox/inbound-calls (createSandboxInboundCall, calls:write, test keys only) rings one of your sandbox numbers from a scripted caller, and the number's route runs on the platform's real call logic instead of a carrier — the flow runner, your answer URL (fetched and signed), queues and seats answered by your script, and a mock AI agent whose session webhook and tool calls are real signed requests, with a real opt-out and hand-off. script sets the keys and speech for each gather, who answers each ring (and confirms, and talks how long), what the caller says to a voicemail, when they hang up and the AI conversation; at sets the call's clock for hours. Every event a live call fires reaches your test endpoints. Each number a connect, a transfer or a hand-off rings is admitted by the rules a live leg is (the destination policy, the organization's list for transfers): a refused one is never rung, and with none left the step fails as live (FLOW_CONNECT_FAILED). New error code SANDBOX_NUMBER_NOT_ROUTED (409, with reason).
    • Test calls play on the same path (T8): once answered, a test FLOW or BRIDGE call's flow runs on the sandbox's media plane and an AI_AGENT call's mock agent talks — the session webhook, real signed tool calls, the opt-out and the hand-off — scripted by the new sandbox field on POST /v1/calls (test keys only; a live key is 400 VALIDATION_FAILED), which takes the inbound script plus machine: the answering-machine verdict (call.machine_detected, the flow's amd, and a machine hung up on without a word where the call says to). The call completes when its flow or agent ends it, with the time the script ran.
    • A test call's recordings are real and fetchable (T8): GET and DELETE /v1/calls/{id}/recording now take a test key, for its own test calls (a sandbox call's recording is a WAV of the scripted length).
    • Sandbox picture messages and HELP replies (T8): POST /v1/sandbox/inbound-messages takes media (one to ten { contentType }, SMS only) and records a test MMS whose files the media worker stores from the sandbox's own samples (message.media.ready); a HELP or INFO is answered with your helpReply as live, returned as the new reply field (else null). text may be left out when media is given.
    • 10DLC in test mode (T8): POST /v1/sms/brands, /v1/sms/campaigns and /v1/sms/campaigns/{id}/numbers (and DELETE) take a test key, which registers in the sandbox (livemode: false: never filed with the registry), and the new POST /v1/sandbox/sms-registrations/review (reviewSandboxSmsRegistration, sms:manage, test keys only) approves or rejects one, as the registry would; each move is sms.registration.updated to test endpoints. Brands, campaigns and number assignments, and the event's registration, gain livemode.
    • Sandbox numbers for test keys (T8): a test key searches (GET /v1/numbers/available), orders (POST /v1/numbers with country and areaCode or prefix, or a number its search offered), reads, labels, tags, routes (PATCH, PUT /v1/numbers/{id}/route) and releases numbers of its own — fictional numbers from the ranges regulators keep for drama (NANP 555-01XX in the US and Canada, Ofcom's in the UK), assigned at once and never bought from a carrier, held, priced or charged. The number resource gains livemode (false for a sandbox number). A key sees and changes the numbers of its own mode only; a test key's order ids are its own. Releasing a sandbox number deletes it (status: retired in the answer), its digits free again. A carrier's call or text to sandbox digits is never routed. A test call may present a sandbox number as from, and presents one by default.
    • Ordering a number by place, under your own order id (T7): POST /v1/numbers takes country with areaCode (as dialled at home: 415, UK 020) or prefix, type and sms — the cheapest number you may order there, the platform's inventory first, then a carrier's stock at your plan's price. Nothing that matches is the new 409 NO_NUMBERS_AVAILABLE (another area code may have numbers). Every order takes reference and metadata (kept on the number: reference is new on the number, set by PATCH too and listed by GET /v1/numbers?reference=) and orderId, your own id for the order for good: the same id answers the number it bought, never a second one (409 NUMBER_ORDER_CONFLICT with another request or once the number is no longer yours, 409 NUMBER_ORDER_IN_PROGRESS while the first is placed); the order answers it as orderId.
    • A number its carrier holds for the regulator's review is no longer a failed purchase (502 NUMBER_SUPPLIER_ORDER_FAILED): it is bought for you, on hold, not live and not charged — pendingCompliance: true on the number (new), pending.code NUMBER_PENDING_COMPLIANCE on the order and the refusal of POST /v1/numbers/{numberId}/activate while it lasts — until the review settles. The new webhook event number.updated (numbers:read) tells how: approved (activated and charged, or still on hold with why) or rejected (handed back, the carrier's reason).
    • The TCPA acknowledgement over the API (T9): POST /v1/settings/destinations/tcpa { statementVersion } gives it with the organization's own key (settings:write; 409 DESTINATION_STATEMENT_OUTDATED when the statement changed) and DELETE /v1/settings/destinations/tcpa withdraws it — the console's step, now automatable; GET /v1/settings/destinations answers the statement's words as tcpa.statement. New error code DESTINATION_STATEMENT_OUTDATED.
    • A voice application's fallback flow (T9): fallbackFlowId on POST/PATCH /v1/applications (a published call flow of yours, of the application's mode) runs when neither the answer URL nor the fallback URL gives usable instructions — your own routing while your server is down — instead of the apology; the call's timeline gains the entry type application.fallback (applicationId, flowId, code).
    • Per-organization live-call caps (T9): the platform can raise (or lower) one organization's live /v1 call caps over the deployment's (PUBLIC_API_MAX_LIVE_CALLS_PER_ORGANIZATION / _PER_KEY); GET /v1/settings/calls answers the caps the organization is held to as liveCallLimits: { perOrganization, perKey }. A call over either is still 429 CALL_CONCURRENCY_LIMIT, its limit the organization's own.
    • Port-out (T7): POST /v1/numbers/{numberId}/port-out unlocks a number for the carrier you are moving it to and answers the account number and a transfer PIN (once; valid validForDays, default 7); POST /v1/numbers/{numberId}/port-out/cancel relocks it; GET /v1/numbers/port-outs and GET /v1/numbers/port-outs/{portOutId} read them (numbers:read / numbers:write). The new webhook event number.port_out.updated tells every step — unlocked, completed (the number left the platform), failed (refused, given up, or the PIN expired: relocked) and cancelled. New error codes PORT_OUT_NUMBER_NOT_PORTABLE, PORT_OUT_NOT_OPEN, PORT_OUT_INVALID_TRANSITION and PORT_OUT_VERSION_CONFLICT.
    • Port-in detail (T7): a rejected port request carries rejection (the losing carrier's own reason and code), a completed one completedNumbers (each number with its id), and number.port_request.updated carries previousStatus (a new focDate within approved reads as such).
    • A number bought from Plivo is attached to the platform's Plivo application on purchase (PLIVO_APP_ID), so it rings on the platform from its first call.
    • Plivo carries SMS and MMS (T6): a deployment can run the platform's Plivo account as an SMS vendor — texts, picture messages both ways, delivery receipts and incoming messages. A send from one of your numbers now goes through the vendor that holds the number, whatever the route or pin says: a Plivo number is texted through Plivo only (a deployment where that vendor is not configured fails it SMS_VENDOR_NOT_CONFIGURED, uncharged, never sent another way).
    • US 10DLC registration over the API (T6): POST/GET /v1/sms/brands, POST/GET /v1/sms/campaigns and POST/GET/DELETE /v1/sms/campaigns/{campaignId}/numbers (sms:read / sms:manage, live keys only) register a brand, its campaigns and the numbers assigned to them — each idempotent on your reference (another body with the same reference is 409 SMS_REGISTRATION_REFERENCE_CONFLICT) — filed with the platform's SMS provider (or reviewed by the platform) and read back until decided. The new webhook event sms.registration.updated (sms:read) tells every status change. A number assignment approved activates the number's SMS sender (sms.sender.updated); removing it sends the sender back to pending_verification. New error codes SMS_REGISTRATION_REFERENCE_CONFLICT, SMS_REGISTRATION_CLOSED, SMS_NUMBER_NOT_ELIGIBLE and SMS_NUMBER_ALREADY_ASSIGNED.
    • The SMS HELP auto-reply (T6): GET /v1/settings/sms and PATCH /v1/settings/sms (settings:read / settings:write) set helpReply — what the platform texts back, from the number that got it, to a contact who texts HELP or INFO (beside STOP and START), at most once per thread every 10 minutes, outside India, never to an opted-out contact. null (the default) sends nothing, as before.
    • Incoming MMS (T6): a picture message a contact sends arrives as type: "mms", with every file it carries (up to ten) in the new **mediaItems** list on the message — media stays its first file — each with an index. Files are fetched from the vendor, checked and stored; message.media.ready / message.media.failed fire once the last of a message's files has settled. GET /v1/messages/{messageId}/media takes index to fetch any one of them. While a file whose type the vendor did not say is still pending, its kind reads unknown.
    • An AI conversation can run with its own configuration besides its agent's: POST /v1/calls (mode: AI_AGENT) takes aiAgent.firstMessage, aiAgent.instructions, aiAgent.tools and aiAgent.session; a number's ai route takes route.ai with the same fields (read back as route.ai); a call flow's ai verb takes firstMessage, instructions, tools, session and onUnavailable. A first message is said word for word, instructions and tools replace the agent's own for the call.
    • The session webhook (session: { url, timeoutSeconds? }): your endpoint is asked once, when the conversation starts, for its firstMessage, firstSpeaker, instructions, language, endCallPhrases, maxTurns and tools — a signed POST (event: agent.session, with the call's context) answered within timeoutSeconds (default 5). A session that does not answer leaves the call on its own options and the agent's configuration; a flow's ai verb can take onUnavailable instead. Test calls ask it too. New error code AGENT_TOOL_SECRET_REQUIRED (422): tools and a session are signed with the agent's tool-signing secret.
    • An AI agent's tool call body carries call: which call it is about — direction, from and to (your number in full, the contact masked to the last four digits, with contactId), numberId, the call's and the number's metadata, and your reference.
    • POST /v1/calls takes reference: your own id for the call, echoed on the call as reference and in an AI agent's tool and session requests.
    • An AI call can hand the caller to a person: transfer: { number | phoneId, ringTimeoutSeconds?, whisper? } on aiAgent, a number's route.ai (phoneId only) or a session's answer. The agent is offered a transfer_to_person tool; the person rings with the caller on hold — answered, the person has the caller and the agent leaves the call; not answered, busy or refused, the caller is back with the agent, told why. Webhook event call.ai.transfer (calls:read): { call, transfer: { id, outcome: answered | no_answer | failed, cause, target, numberLast4, phoneId, phoneReference, childCallId, returnedToAi } }, once per hand-off.
    • A built-in opt-out for AI conversations: optOut: { key?, phrases?, reply? } on aiAgent, a number's route.ai, a flow's ai verb or a session's answer. The caller pressing the key or saying a phrase marks the contact do-not-call at once (CONTACT_DO_NOT_CALL on any later call), the agent says the reply and the call ends. Webhook event call.ai.opt_out (calls:read): { call, optOut: { method, key, phrase, contactId, doNotCall } }, recorded with the mark.
    • POST /v1/calls takes notAfter: nothing is dialled at or after it — a request that arrives too late is 422 CALL_NOT_AFTER_PASSED (new error code), and a call caught by the dial's last check fails NOT_AFTER_PASSED. POST /v1/calls/cancel (calls:write, cancelCalls): { reference } ends every queued or live call placed with it, idempotently, answering each one's outcome (cancelled, ended, pending, unsupported).
    • The answering-machine verdict reaches a call's flow as the amd variable (human, machine, unknown; a switch on it waits a few seconds for the verdict), and aiAgent.onMachine: hangup ends an AI call a machine answered without a word (its agent waits for the verdict before speaking; hangup.reason: machine_detected).
    • Webhook event call.dtmf (calls:read, opt-in): each key the caller presses while an AI agent has them — { call, dtmf: { id, digit, sequence, pressedAt } } — never one pressed into a sensitive gather.
    • A call flow's connect rings several parties: targets in place of to (up to 10; each a number, an agent or a client, with its own timeoutSeconds, skip windows — weekly local ranges in a timezone, and spans between two instants — and your reference), rung one after another (strategy: sequential, the default) or every number at once (simultaneous, within CALL_CHILD_LEGS_MAX legs), within totalTimeoutSeconds in all. The first to answer takes the call and the other legs are hung up; a party skipped now is passed over unrung, and one the dial rules refuse is passed over while the others ring.
    • connect takes confirm: { key, prompt, timeoutSeconds }: the answering party of an outside number must press the key (after the whisper) before they are connected, hearing only the prompt until then; a pickup that does not is hung up and counts as no answer, so the next party rings, then onNoAnswer.
    • A recording notice: connect, record and voicemail take notice, spoken before the recording starts. connect with record: true now records the connected conversation — once the notice has played to both parties, never without it — and a recording pause or a sensitive gather keeps what is said meanwhile out of it.
    • voicemail takes keys and reply: a key pressed through the greeting or the message ends the voicemail (what was recorded is kept), becomes the digits variable, and the reply is spoken. The key is kept on the voicemail: call.missed's missed.voicemail.key.
    • PUT /v1/numbers/{numberId}/route (numbers:write): one call replaces a number's whole routing with a call-flow document (flow) under your own rising version. The document becomes a new published version of the number's own call flow and the number routes to it, atomically; a version that is not newer than the one held is ignored and the answer says so (outcome: applied, unchanged for a retry of the applied version, stale), so changes sent out of order leave the newest one live.
    • A number carries metadata: your identifiers for it (a string map with a call's metadata rules), set with PATCH /v1/numbers/{numberId} and read back on the number. It is copied onto every inbound call to the number as the call's metadata, so it is echoed on the call's events.
    • GET /v1/calls takes metadata=key:value (repeat for up to 5 pairs), as GET /v1/messages does: calls whose metadata — their own, or their number's — holds every pair, by exact match, indexed.
    • call.ringing and call.answered are told for an inbound call a number routes, which is answered by the platform on arrival and so had neither: call.ringing when a connect starts ringing someone (ringing: the strategy and each party — its place in targets, your reference, a number's last four digits and the /v1/phones phone it is), and call.answered when someone takes the caller (answeredBy: the party, confirmed, the leg; a seat that took a queue's caller names the queue). A pickup that never pressed the confirm key is never told. An outbound call's own call.ringing and call.answered carry ringing: null and answeredBy: null.
    • Webhook event call.voicemail.ready (calls:read, transcripts:read): a caller's message is ready — voicemail with its recordingId, key, and transcript ({ status, text }): the voicemail step's transcribe (on by default) is now honoured, the caller's words in the message taken from the call's live transcript and sealed on the voicemail. Told once per voicemail, a few seconds after the message ends, so it can come after call.missed.
    • A call's recording (and GET /v1/calls/{callId}/recording) says what it is of — purpose: call or voicemail — and whether a recording notice played before it started (noticePlayed). GET /v1/calls/{callId}/recording takes recordingId to fetch one recording of the call by id, such as a voicemail's beside the call's own.
    • POST /v1/calls takes calledPartyTimeZone: the IANA zone the called party is in, when you know it. The request's own calling window and, for a +1 number, the TCPA window are then asked in that one zone. It is believed only when it keeps the same clock as a zone of the number's own country.
    • A call flow's hours verb takes the schedule itself in place of a schedule id: schedule: { timezone, weekly, holidays, overrides, closures }. weekly is the usual local ranges per ISO weekday; holidays are local dates closed all day (the holiday branch); overrides give one date its own same-day ranges in place of its weekday's (none: closed that day); closures are spans closed whatever the hours say, as ISO instants. A flow that carries its hours is the whole of a number's routing, so replacing the flow replaces its hours with it. Stored schedules by id work as before.
    • Webhook event call.missed (calls:read): an inbound caller reached nobody — every phone or seat a route rang went unanswered, they hung up waiting, or the business was closed. missed.reason says which, missed.queueId names the queue involved, and missed.voicemail is the message they left ({ id, recordingId, durationSeconds }) or null. Told once per call when its flow ends, so a missed call can be texted or called back without polling.
    • /v1/phones (settings:read, settings:write): the organization's own phones — the staff handsets its calls are forwarded to. POST /v1/phones registers one (number, with your own label and reference), GET lists and reads them with the number masked, DELETE removes one. A leg a call flow's connect, or a transfer, dials to a registered phone is your staff answering their own handset (legRole: AGENT_PHONE on the leg), not a called party: it must still be a number the organization may dial and is priced like any leg, but the called party's calling window is not asked of it. New error codes OWN_PHONE_IS_CARRIER_NUMBER (400) and OWN_PHONE_LIMIT_REACHED (409).

    Changed

    • A test SMS to India now carries the SMS_DLT_ENTITY_MISSING warning whenever no DLT principal entity is set — with no SMS settings too, where it used to say SMS_NOT_CONFIGURED alone (a test organization an integration provisioned never has SMS settings, and now sees DLT's entity check in sandbox form beside the template check).
    • A tightened requirement (P5): a business in the US, the UK or an EU member state now verifies under its own country's profile rather than the generic international one. Its identifiers are checked against the country's shape (an EIN of nine digits, a Companies House number, an EU VAT number of that member state), a US business also owes its state of registration (jurisdiction) and its IRS EIN letter (tax_registration), and pan is India's only: sent for a business elsewhere it is now 400 VALIDATION_FAILED (it was stored and meant nothing). A draft saved before shows any new gap in requirements; a submission is refused 422 VERIFICATION_INCOMPLETE until it is filled. India's requirements are unchanged.
    • An agent-first BRIDGE (ringFirst: agent) now presents to the contact the number the call says it presents — its from, or one of your own numbers on the channel — where the carrier's leg to the contact used the agent's allocated number or the account's caller ID even when the call named from. A seat with an allocated number and no from presents it as before.
    • A test key's POST /v1/sms/brands, POST /v1/sms/campaigns and the number-assignment writes are no longer 422 TEST_MODE_UNSUPPORTED: they register in the sandbox (T8), and sms.registration.updated is delivered to test endpoints for sandbox registrations. A tightened requirement: the GET /v1/sms/brands, /campaigns and …/numbers reads now list the registrations of the key's own mode only, and a live registration is 404 NOT_FOUND to a test key (a test key used to see the live ones). A test key reads no live record; read your live registrations with a live key.
    • A tightened requirement: a test key's numbers are its sandbox numbers (T8). Its GET /v1/numbers now lists its sandbox numbers only — it used to list the organization's live numbers — and a live number is 404 NOT_FOUND to it on GET /v1/numbers/{numberId}, PATCH, PUT …/route, activate and release (the writes used to answer 422 TEST_MODE_UNSUPPORTED), as a sandbox number is to a live key: a test key never reads or changes a live record. Read and manage live numbers with a live key. Its GET /v1/numbers/available answers sandbox numbers instead of the platform's inventory; ordering with numberId (the inventory) is still 422 TEST_MODE_UNSUPPORTED for a test key; PATCH, PUT …/route, activate and release work on its own sandbox numbers.
    • A test FLOW, BRIDGE or AI_AGENT call no longer completes on a three-second timer once answered: it completes when its flow or agent ends it (T8). Its timeline holds the flow's flow_step.* entries, its transcript what was said on it, and its hangup who ended it (an AI_AGENT call with no script: the agent, application / ai_ended, after a short scripted conversation). EXTERNAL_AGENT and agent-first BRIDGE test calls are unchanged.
    • The TCPA calling window for a +1 number (409 DESTINATION_CALLING_WINDOW_CLOSED) is asked in the zones the number's area code serves, not in every zone of the United States at once: a New York number can be called from 08:00 Eastern, not from 08:00 in Honolulu. An area code that spans zones is asked in all of them; a toll-free number, or an area code the platform does not know, is still asked in every zone of its numbering plan. respectCallingWindow reads a number abroad the same way.
    • A leg that rings the organization's own staff (an agent's handset on an inbound bridge) is not held to the called party's calling window, as the agent-first leg of a BRIDGE call never was. A forward or transfer to any other number is a called party's and still is.

    Fixed

    • A request that names an organization in Trovacast-Organization and is refused spends the key's own rate limit. Requests naming an organization are budgeted per key and organization, and that budget was chosen from the header before the key was known: a key that named a different organization id on each request — one it could not act for (404, 403 API_KEY_SCOPE_MISSING, 409 ORGANIZATION_NOT_ACTIVE, 400) — was never rate limited, and an organization's own key that sent its own id had twice its budget. Such a request now also counts against the key's own 600 a minute (429 RATE_LIMITED with Retry-After once it is spent). An integration key acting for an organization it may act for is budgeted per organization exactly as before.
    • An integration's webhook endpoint is not sent an event type the platform no longer delegates to the integration, however the delivery came to be due. Narrowing the delegation stopped new events of the type being recorded for the endpoint and GET /v1/integration/events from listing them, but a delivery recorded earlier — one waiting out a retry, or any of the last 30 days resent with POST /v1/integration/webhook-endpoints/{endpointId}/deliveries/resend (or one delivery's /resend) — was still sent. It is now failed at once with lastError: "SCOPE_NOT_DELEGATED", nothing is sent and the endpoint's health is untouched; resend it once the scope is delegated again. An organization's own endpoints are unaffected.
    • POST /v1/calls takes one of your sandbox numbers as from in every country that has them. India's sandbox range (+91 11 0000 0XXX and its five sister area codes) is one no real line can have, and the format check on from refused it (400 VALIDATION_FAILED, "from must be in international format"), so a test key could not place a call from its own +91 sandbox number as the caller ID. A real number is checked as before, and one the organization does not hold is still 422 CALLER_ID_NOT_OWNED.
    • A call forwarded by the carrier to a +1 number was refused DESTINATION_BLOCKED even for an organization +1 was opened for. It now asks the organization's own destination policy, as every other leg does.
    • The sandbox rang one of your own phones (/v1/phones, registered with the test key) as a called party: a connect or hand-off to a registered +1 staff phone outside 08:00–21:00 in its zone failed the step (DESTINATION_CALLING_WINDOW_CLOSED) where a live call rings it. A sandbox leg to one of your test phones is now your staff's own handset, as live.
    • On a plan that prices calls by destination, the sandbox asked the wallet for every leg a test call rang (and every outbound test call), so a test organization without live credit had each connect fail (FLOW_CONNECT_FAILED, cause BILLING_INSUFFICIENT_CREDIT). A test call is never billed: the sandbox now asks only whether your plan prices the destination (BILLING_RATE_UNAVAILABLE, as live), never the credit.
    • A test key could not read back the number of a caller its own test traffic created: GET /v1/contacts/{contactId}/export was 422 TEST_MODE_UNSUPPORTED for every contact, so an integration that texts a caller back, or matches them in its CRM, could not be tested in the sandbox. A test key now exports a test contact (livemode: false — a simulated inbound call's or message's caller, a test send by number); a live contact stays 422 TEST_MODE_UNSUPPORTED to it.
    • A test key could change a live person's consent: an outbound test AI_AGENT call to a live contact's number (by to.phone or contactId) whose script pressed the opt-out key, or said an opt-out phrase, marked that live contact do-not-call. A test call now marks only a test contact; for a live one call.ai.opt_out says doNotCall: false and their consent is left as it was.
    • A simulated inbound call nobody took (POST /v1/sandbox/inbound-calls) was filed on the console desk's missed-call list, as a live caller to call back, and counted in the desk's missed-call report. It is now told as call.missed to your test endpoints only, as before, and never filed on the desk.
    • The voicemail a simulated caller left (POST /v1/sandbox/inbound-calls) appeared in the console desk's voicemail inbox beside live callers' messages, to be heard and called back. It is now told as call.voicemail.ready to your test endpoints and read with your test key as before, and never shown on the desk.
    • One of a test key's US sandbox numbers could be registered as an SMS sender from the console (Settings › SMS), and a live text could then be sent from its fictional digits. A number sender is now one of your live numbers only, at registration and again at every send; a sandbox number texts through the sandbox alone.
    • Two HELP (or INFO) texts landing on one thread at the same moment — two auto-responders, a texter tapping send twice — could both be answered, live or in the sandbox. The HELP reply now goes out once per thread in its 10-minute window however many arrive together; every HELP is still recorded.
    • Releasing a sandbox number that was assigned to a sandbox 10DLC campaign took the assignment away without a word: it simply stopped existing. The assignment now ends first, told as sms.registration.updated (status: removed, statusReason "The number was released") to your test endpoints, as a registration's every other move is.
    • The contract listed 422 TEST_MODE_UNSUPPORTED among the refusals of PUT /v1/numbers/{numberId}/route, POST /v1/numbers/{numberId}/activate and POST /v1/numbers/{numberId}/release, which a test key cannot meet since it got sandbox numbers: it routes, activates and releases its own, and a live number is 404 to it. The refusal is no longer listed there (ordering an inventory number, a DLT header, an SMS sender and porting still answer it).
  2. Contacts keep the attributes they already carry

    2026-11-07

    Fixed

    • Re-sending a contact's stored attributes no longer refuses the save. An attribute value is checked for a phone number when it is new or changed; one identical to what the contact already carries is not checked again. A contact imported with a long identifier in an attribute (an 8-digit facility id, an accreditation number, an address with a PIN and a plot number) could not be saved at all once the check counted it as a number, because the console — and many integrations — send every attribute back on each update. POST /v1/contacts on an existing contact follows the same rule. A new or changed value holding a phone number is still refused (400, "must not contain a phone number").
  3. A party still on at a call's end leaves its timeline, an unstaffed queue in the sandbox, every cause of a broken AI route

    2026-11-07

    Changed

    • Each warning names every cause. A number's AI route or flow step that fails for more than one reason now carries one warning per cause, each with the same numberId and step — on the number (GET /v1/numbers/{numberId}) and in the answers to PATCH/DELETE /v1/agents/{agentId} and PATCH /v1/settings/calls — the first being the one its calls fail with. With AI calls off, a step whose agent is archived warned only AI_CALLS_DISABLED, and switching AI calls back on answered warnings: [] while the step still failed AGENT_INACTIVE. A client that read only the first warning per number still reads the cause its calls fail with.
    • Switching AI calls on answers with warnings too. PATCH /v1/settings/calls with aiCallsEnabled: true lists the numbers that still cannot take AI calls, and why (it answered []).

    Fixed

    • An archived agent's warning says what can actually be done. The AGENT_INACTIVE warning told you to switch the agent on with PATCH /v1/agents/{agentId} (active: true) whether it was switched off or archived, and that PATCH refuses an archived agent. The reason is unchanged; the message now says which it is: a switched-off agent is switched on, an archived one cannot be, so the step must name another agent (a new version of the flow) or the number must route elsewhere.
    • "AI agent", never "AI profile". PATCH and POST …/tool-secret on an archived agent answer 400 VALIDATION_FAILED "An archived AI agent cannot be changed or switched back on…" (it said "An archived AI profile cannot be edited"), and an agent whose voice cannot run here is described as "This AI agent …" in warnings and refusals (AI_PROVIDER_UNAVAILABLE, MODEL_UNAVAILABLE).
    • A live call's timeline says when each leg left. A party still on when the call ended — a transfer target, a conference party, a desk agent — showed leg.joined with no leg.left, though a test call's timeline shows both. Each now leaves with the call: its leg.left follows the end, once, with the childCallId its leg.joined named (a party's leg.left named none before). A conference's parties still on at its end are told by conference.ended, as before — no conference.participant.left for them. A blind transfer's agent leaving the call now always writes its leg.left too.
    • The sandbox shows a transfer to a queue nobody staffs as live does. A test call sent to a queue with no seat signed in showed queue.entered, then queue.left (ABANDONED) and transfer.failed (CALLER_HUNG_UP); a live call never enters such a queue. The sandbox now decides staffing as the ACD does for a live caller: transfer.started, transfer.ringing, then transfer.failed (NO_AGENTS) when the call ends or another transfer takes the caller; a second queue transfer meanwhile is 409 CALL_ACTION_IN_PROGRESS, as live. The live caller's voicemail is not modelled (the sandbox runs no flow).
  4. Phone numbers caught however they are written; dates no longer masked

    2026-11-07

    Changed

    • **A tightened requirement: an attributes value holding a phone number written with any separator is refused.** POST /v1/contacts refused an attribute value with eight or more digits once ASCII spaces, hyphens, dots and brackets were removed; one written with an en dash, a non-breaking hyphen, a middle dot, a zero-width space or another script's digits was stored, unmasked. A value with seven or more digits of any script, whatever separates them, is now 400 VALIDATION_FAILED; a calendar date (15/11/2026, 2026-11-15) is not a phone number and is accepted. Send phone numbers in phone.
    • **displayName**: a phone number in it, however written, is stored masked to its last four digits, as one written with ASCII separators already was.

    Fixed

    • Transcripts, summaries and extraction fields mask a number written with any separator (GET /v1/calls/{callId}/transcript, …/summary): "98765– 43210" with an en dash used to be published whole. And a date is no longer masked as if it were a number: "callback 15/11/2026" reads as said (it read "callback •••• ••2026").
    • **A call whose AI ran only in a flow's ai step is summarized with that agent.** Its summary and extraction (GET /v1/calls/{callId}/summary) ran on the platform's own model account, whichever agent the step used; they now run on the step's agent — its provider, model and credentials — and, once that agent is switched off or archived, the summary reads unavailable instead. When one call runs several agents, the first one the call reached is the call's.
    • Switching an agent off is described as it behaves. The agent references called it an emergency stop; it stops new calls, new AI steps and campaign dials at once, while a conversation the agent is already having finishes — hang that call up (POST /v1/calls/{callId}/hangup) to stop it now. Behaviour is unchanged.
  5. A test call's actions on its timeline, a webhook for a call's charge, every broken AI route named

    2026-11-07

    Added

    • **call.rated** (calls:read): the call, with its charge, once the charge is written — charged, waived or not_connected, with the rule and reason it was rated by. A call is rated after its final call.* event, so those carry charge: null (0 of 35 final deliveries carried a charge in review), and a webhook-only integration never learned what a call cost. An unrated charge (no price yet) fires nothing until a re-rate or the backfill charges it — then once, charged; a charged call fires again only when its minutes are corrected. Never for a test call (test calls are never rated).
    • **PATCH /v1/settings/calls answers with warnings.** While AI calls are off, every number whose ai route or routed flow's AI step now refuses its callers (AI_AGENT_UNAVAILABLE, reason: AI_CALLS_DISABLED), in the shape PATCH /v1/agents/{agentId} answers; [] while they are on. Switching AI calls off listed nothing before.
    • **flowId and detail on the warnings a change answers with** (PATCH/DELETE /v1/agents/{agentId}, PATCH /v1/settings/calls): the routed flow a step warning is about (null for an ai route's own), and whether the number's details are in the warning (below).

    Changed

    • **DELETE /v1/agents/{agentId} answers 200 with the archived agent and warnings** (it answered 204 with no body). Archiving an agent only a routed flow's AI step names was allowed and said nothing, while the number then warned AGENT_INACTIVE; the answer now names each number (and flow) whose step falls back, as the agent PATCH does. A repeat answers 200 again. A client that treated any 2xx as success is unaffected; one that checked for 204 should accept 200. An agent a number's ai route answers with is still refused 409 AI_AGENT_IN_USE.
    • **A tightened requirement: a change's warnings name a number's route only for a key with numbers:read.** A key with only agents:* scopes was refused GET /v1/numbers (403) yet read number ids, channels and route state in the agent PATCH answer. Without numbers:read each warning now carries only numberId, code and reason — provider, agentId, step and flowId null, detail: false, and a message that names no route. Give the key numbers:read for the whole warning.
    • One condition, one code. Pointing a number at a new AI agent that cannot take calls is refused with the code POST /v1/calls answers the same cause with: 409 AI_AGENT_INACTIVE for an agent switched off or archived and 404 AI_AGENT_NOT_FOUND for one that is not your organization's live one (a test agent reads exactly as an unknown id) — both were 400 VALIDATION_FAILED — beside the unchanged 409 AI_CALLS_DISABLED and 422 AI_PROVIDER_UNAVAILABLE. An inbound call's failure.code stays AI_AGENT_UNAVAILABLE for every cause (it is the call's outcome, not a refusal); the docs' table maps each cause on every surface.

    Fixed

    • A test call's timeline shows the actions taken on it. Hold, resume, transfer and recording pauses fired their webhooks (call.held, call.resumed, call.transferred) while GET /v1/calls/{callId}/events showed only created … ended. Each action now writes the entries the same action writes on a live call, in the transaction that fires its webhook: held, resumed; a transfer to a number holds the caller, adds the target's leg.joined (childCallId: null — the sandbox dials no leg) and resumed, and leg.left once the call ends; a transfer to a queue adds transfer.started, transfer.ringing and queue.entered, then queue.left (ABANDONED) and transfer.failed (CALLER_HUNG_UP) when the caller hangs up waiting; record adds recording.paused and recording.resumed. A gather, speak or play writes no entry on any call.
    • A test call refuses what a live call refuses. resume when the caller is not on hold is 409 CALL_NOT_HELD; record on a call whose channel records it itself is 409 RECORDING_NOT_CONTROLLABLE; a second queue transfer while the caller waits is 409 CALL_ACTION_IN_PROGRESS. The sandbox answered all three 200.
  6. Client-voice billing refusals in plain words, failed authentications counted per IPv6 /64, every hang-up reason in the contract, a switched-off agent stops its calls

    2026-11-07

    Changed

    • Switching an AI agent off, or archiving it, stops its calls. An AI_AGENT call admitted while the agent was on, whose agent is switched off or archived before it rings, fails AI_AGENT_UNAVAILABLE (call.failed) without ringing; one whose agent goes off between dial and answer is hung up when its audio arrives, failed AI_AGENT_UNAVAILABLE, and — answered with nobody speaking — charged at the channel's manual rate for its connected time (charge.rule AI_VOICE_NEVER_STARTED, charge.reason "The AI agent could not run (AI_AGENT_UNAVAILABLE): …"). Such a call used to run on the platform's default agent instead. Its summary is unavailable rather than graded. A conversation already under way when the agent is switched off finishes (a carrier re-connect of its audio is refused like a new call). failure.reason for AI_AGENT_UNAVAILABLE now reads "The call was refused: its AI agent cannot take calls now."
    • A client-voice app is told a billing refusal in plain words. A dial from @trovacast/sdk/voice (call:place) that the billing gate refuses still answers its BILLING_* code and status (402 or 503), now with the plain sentence for that code — BILLING_INSUFFICIENT_CREDIT reads "Not enough credit to place this call; ask a project admin" — instead of the sentence POST /v1/calls answers your key with, which names your plan or the minutes your calls in progress may run to. The token may be held by an end user or an anonymous visitor; your server still reads the figures with its key (GET /v1/balance, GET /v1/pricing). Branch on code, never on the sentence. /v1/calls itself is unchanged.
    • A tightened requirement: an IPv6 client's failed authentications are counted per /64. The budget of 30 failed authentications a minute (keys that never existed, no key, a malformed one) counted each IPv6 address apart, so the addresses of one /64 — which one ISP or cloud subscriber holds — had a budget each. Every address of a /64 is now one client address, and an IPv4-mapped address (::ffff:192.0.2.1) is its IPv4 address; past the budget the whole /64 is answered 429 RATE_LIMITED (with Retry-After) until the block ends. As before, a key that authenticated recently keeps working through the block, and a key first used from that /64 during it waits the block out.

    Fixed

    • **The contract names every hangup.reason.** The OpenAPI description of a call's hangup.reason (and the SDKs' doc comments made from it) now lists agent-hangup (an agent hung up in the console) and supervisor-end (a supervisor's End call), which calls already carried and this reference already listed; hangup.side's says a person in the console is agent. No call reads differently.
  7. Test calls on the timeline, every refused AI route warned, unchanged routes always saved, why a call was charged, supervisors end calls

    2026-11-07

    Added

    • A supervisor can end a live call from the desk. Such a call reads hangup: { side: "agent", reason: "supervisor-end" }; a call an agent hung up in the console reads reason: "agent-hangup" (it already did; both are now documented beside the other reasons).
    • A call's charge says why it was rated as it was. charge on a call (as GET /v1/calls/{callId} reads it, and on the call.* events sent after the call is rated) and the timeline's rated entry carry rule and reason. A call is rated after its final event, so call.completed, call.failed, call.no_answer and call.busy carry charge: null; the call.rated event (see the later 2026-11-07 entry) carries the charge. (This entry said "in every call.* event" until then.) rule names the rule the call was rated by when it was not its talk time at its plan's rate for its type: STALL_SILENT and STALL_PAST_CEILING (a stuck call a supervisor cleared — silent inside its ceiling, rated from answer to its last sign of life plus 60 s; or past its ceiling, rated to it), AI_VOICE_NEVER_STARTED (an AI call whose voice never started, rated at the manual rate), TALK_TIME_UNKNOWN (waived); null otherwise. reason is the rating's own sentence (null when there is nothing to say). Switch on rule; v1 may add values.
    • **AI_AGENT_UNAVAILABLE on a number's warnings**, with reason AI_CALLS_DISABLED (AI calls are switched off for your organization), AGENT_INACTIVE (the agent is switched off or archived) or TEST_AGENT — on an ai route (its calls are refused AI_AGENT_UNAVAILABLE) and on a routed flow's AI step (the caller takes the step's fallback). A number used to warn only when the agent's voice could not run (AI_PROVIDER_UNAVAILABLE, unchanged), while its calls were refused for any of the four.
    • **PATCH /v1/agents/{agentId} answers with warnings**: each number the change leaves failing (numberId and the number's own warning). Switching off an agent a number routes to stays allowed — new calls, new AI steps and campaign dials stop using it at once, while a conversation already running finishes — and this says what it stopped. Only in that answer.

    Changed

    • A route save that leaves the target as it is always saves. A PATCH /v1/numbers/{numberId} (or the console's route) that keeps the number's route target — a label, the same route sent again, or both — saves, with its warnings. Only a change of target is checked, and pointing a number at a new AI agent that cannot take calls is still refused (409 AI_CALLS_DISABLED, 422 AI_PROVIDER_UNAVAILABLE, 400). A price gap never refuses a save.

    Fixed

    • A test call's timeline is no longer empty. GET /v1/calls/{callId}/events with a test key answered [] for every test call while its call.* webhooks fired. A test call now has the entries a live call of its mode has as the sandbox walks it: created, queued, ringing, answered, ended (a busy, unanswered or failed one without the steps it never reached). The sandbox runs no flow and connects no AI, so there are no flow or AI steps, and a test call is never rated, so there is no rated entry. A live key still reads none of them (404).
    • **Re-sending a number's ai route after its agent lost its voice** was refused 422 AI_PROVIDER_UNAVAILABLE although the docs said a route is saved regardless; it saves now, with the warning (above).
    • The backfill of unrated calls (an operator's console action) refuses a dryRun that is not a JSON boolean (400): the string "false" used to read as a dry run.
    • Dates. The timeline keeps flow outcomes, AI admissions, recording pauses and the ceiling from 2026-11-07 (the docs said 2026-11-10), and every entry here is dated the day it reached production (several were dated 2026-11-08 to 2026-11-10, after they shipped on 2026-11-06 and 2026-11-07). Payload 2 of the answer-URL request is every application's made from 2026-11-06 22:35 UTC, the release that shipped it.
  8. New organizations' first calls, stuck-call billing, forwards held to the call ceiling

    2026-11-07

    Fixed

    • A new organization's first concurrent calls are all answered. The first billable requests of an organization that had never been billed — several POST /v1/calls at once, say — could answer 500 for all but one (its wallet and subscription were being created by each of them at once). They are now answered as any other call: 201, or the usual 402/503 billing refusal.
    • A stuck call cleared because it went silent is billed to its last sign of life. A call closed failure.code: WATCHDOG_EXPIRED because a supervisor cleared it as stuck and silent (no hang-up ever arrived) was billed from answer to the moment it was cleared, capped at its ceiling. It is now billed from answer to the last sign of life it showed (its audio stream's last heartbeat, a carrier status, an event) plus 60 seconds, capped at its ceiling; one cleared because it ran past its ceiling is billed to its ceiling, as before. The charge's reason says which.

    Changed

    • A number's forward and agent bridge are held to the call ceiling. On Plivo, a call to one of your numbers that is forwarded to another number, or bridged to an agent's phone, is now ended at the deployment's call ceiling — the same limit every outbound call is held to — instead of a fixed hour.
    • A tightened requirement: ElevenLabs coaching and post-call summaries follow an agent's own provider credential. An AI agent whose provider credential is a tenant's own (set by the platform for your organization) and whose reasoning provider is ElevenLabs was coached, and had its outcome and summary written, on the platform's ElevenLabs account. It now uses your credential and your own ElevenLabs coach agent; until the platform has configured that coach agent for you, such a call has no live coaching and its summary ends unavailable once its grading gives up, exactly as when the credential itself is unavailable. Agents with no credential of their own are unchanged.
  9. A call's timeline, numbers that warn when their AI cannot answer, unpriced calls never charged by surprise

    2026-11-07

    Added

    • **GET /v1/calls/{callId}/events** (calls:read, listCallEvents in the SDKs): the call's timeline, oldest first and paged like every list — created, queued, ringing, answered, ended (with the call's status and failure); each flow step (flow_step.started, then flow_step.ended with its outcome, whether it took its fallback and the code why); each AI step admitted or refused (ai_step.admitted, ai_step.refused with its code); queue waits, transfers and legs; the recording paused and resumed; speech-to-text gaps; the ceiling reached; and, once rated, the charge (rated, always last). Entries carry ids the API already shows, closed words and machine codes, and a transfer target's number masked to its last four digits — never transcript text, digits pressed or a secret. A call of the other mode answers 404, as every /v1/calls/{callId}/… route does. Flow outcomes, AI admissions, recording pauses and the ceiling are kept from today; an earlier call shows what was kept then.
    • Number warnings for a route that cannot answer. warnings on the number resource gains AI_PROVIDER_UNAVAILABLE: the AI agent an ai route answers with — or one an AI step of a flow route hands the caller to — cannot speak on this deployment (its availability.runnable is false: a provider key, or a credential alias, it needs is gone), with the same reason GET /v1/agents/{agentId} reports. A flow route also warns BILLING_RATE_UNAVAILABLE (callType: full_ai) for an AI step whose AI call your plan does not price. Each warning gains agentId, reason and step ({ node, index }, null when it is about the route itself). Warnings never block a save.
    • **PROMOTIONAL_NUMBER_REQUIRED**, PROMOTIONAL_PURPOSE_REQUIRED and PROMOTIONAL_WINDOW_CLOSED are listed with the other dial refusals of POST /v1/calls (they were refused all along).

    Changed

    • An unpriced call is re-rated only within 7 days of its end. A call your plan did not price is recorded charge.status: unrated (with shadow billing, where such calls are taken). It is charged automatically if the plan gains a price for it within 7 days of the call's end; after that it stays unrated unless the platform, on your request, runs an audited backfill for your organization and a window of dates — which reports what it would charge before it charges anything. Before, adding a price charged every unpriced call since go-live in one go.
    • The shadow-billing warning says what happens. A route your plan does not price, with billing in shadow, now reads "recorded unpriced, and charged only if the plan prices it within 7 days of the call" (it said the calls "stay unpriced", while they were charged later, with no limit).

    Fixed

    • AI_AGENT_UNAVAILABLE's documented cases now list every one the platform refuses with it: the agent switched off or archived, a test agent on a live call, AI calls switched off, and its voice unable to run here.
    • Where the docs said an AI "never spoke", they now say its AI voice never started: an AI that connected and stayed silent did start, and is billed as AI.
  10. Refused inbound calls on the record, route pricing warnings, AI whose voice never started billed as manual

    2026-11-07

    Added

    • **warnings on the number resource.** GET /v1/numbers, GET /v1/numbers/{numberId} and PATCH /v1/numbers/{numberId} answer each number with warnings: [{ code, direction, provider, callType, message }] — today one kind, BILLING_RATE_UNAVAILABLE: your plan has no inbound rate for the calls the number's route answers on its channel (callType full_ai for a route to an AI agent, manual for any other route). A route is saved all the same — a price can be added later — and the warning goes once the plan prices it. GET /v1/pricing lists the inbound cells your plan has.
    • New call failure codes for refused inbound calls: BILLING_* (BILLING_RATE_UNAVAILABLE, BILLING_INSUFFICIENT_CREDIT, BILLING_SUBSCRIPTION_PAST_DUE, BILLING_SUBSCRIPTION_SUSPENDED, BILLING_SUBSCRIPTION_CANCELED) and AI_AGENT_UNAVAILABLE, each with its own failure.reason.

    Changed

    • An inbound call the platform refuses is recorded. With billing enforced, a call to one of your numbers whose route your plan does not price (or that the wallet cannot pay for), and a call to a number routed to an AI agent that cannot answer (switched off, archived, a test agent, AI calls switched off), still hears a short apology — and is now a call: GET /v1/calls/{callId} reads it direction: inbound, status: failed, failure.code the refusal's code, it fires call.failed (never call.inbound), and it is never charged. Before, nothing was written and nothing fired.
    • A call whose AI voice never started is charged at the manual rate. An AI call (inbound to an AI route, or an outbound AI_AGENT call) that was answered but whose AI voice could not start — failure.code: AI_PROVIDER_UNAVAILABLE, the AI voice never started — is charged at the channel's manual rate for its connected time, not the AI rate (charge.ratePerMinuteMinor says which).
    • An AI step checks its agent's availability first. A call flow's ai verb or connect to an AI agent whose availability.runnable is false is refused before it starts — the step reads failed, cause: AI_PROVIDER_UNAVAILABLE — so the flow takes its fallback and the call is not charged as an AI call. A transfer action to a call flow that hands callers to such an agent is 422 AI_PROVIDER_UNAVAILABLE (reason, provider, leg, agentId) before anything happens to the call.
    • The default caller ID prefers the contact's country. A /v1 call with no from presents your number in the contact's own country (the same E.164 country calling code) first, then the oldest of your numbers on the channel as before — a +91 number to an Indian contact, however old your +1 number is. fromSource still reads organization_number.

    Fixed

    • The answer-URL request section of the reference stated payload 1's call fields after payload 2's example; each version's fields are now stated once, under its version.
  11. Tenant AI credentials bound to their organizations, AI agents checked wherever a flow or a number hands them a caller, inbound forwards priced

    2026-11-07

    Changed

    • A tenant's own AI credential is usable only by the organizations it is granted to (a security fix: a tightened requirement). An agent's credential alias (set in the console; never read or written over the API) now resolves only for an organization the platform granted it to, and never falls back to the platform's key. An agent naming one its organization may not use reads availability: { runnable: false, reason: "voice_key_missing" } on GET /v1/agents, and an AI_AGENT call to it is 422 AI_PROVIDER_UNAVAILABLE (reason: "voice_key_missing") before anything is written. The answers are the same for an alias that does not exist, so they never tell you whether another tenant's does. Agents with no alias are unaffected.
    • A flow that hands the caller to an AI agent that cannot speak is invalid (a tightened requirement). An ai step, or a connect to { ai }, naming an agent whose availability.runnable is false is 422 CALL_FLOW_INVALID when the flow is created, versioned, published or validated, and when it is sent inline on POST /v1/calls (nothing is dialled); the issue's message names the reason, e.g. (voice_key_missing). A published flow whose agent loses its voice later still takes the step's failed path at call time (onEscalate, else the next verb).
    • A number is routed only to an AI agent that can speak (a tightened requirement). PATCH /v1/numbers/{numberId} with route: { kind: "ai" } naming such an agent is 422 AI_PROVIDER_UNAVAILABLE with reason, provider and leg, as an AI_AGENT call to it is; nothing changes. At the answer, a route whose agent lost its voice since gives the caller the short apology, with no call row and nothing billed.
    • A burst of dials in one organization waits its turn. Each organization's dials enter its admission lock at most two at a time per server; the rest wait without holding database connections. A dial that cannot start within 30 s, or arrives behind 500 waiting, is answered 503 (retry with backoff) before anything is written.

    Fixed

    • Inbound forwards and agent-handset bridges are priced under the dial lock. Two inbound calls forwarded at once could both pass the credit check and spend the same credit; the leg is now reserved, in the transaction that prices it, before the carrier is handed the forward. A forward refused for credit answers the caller with the greeting. The reserved leg is what the carrier's report binds and what is rated.
    • One tenant's failing speech-to-text credential no longer delays another's. Transcription reconnects back off per vendor and credential, not per server, and a reconnect probe that never reports is handed on after 15 s, so a call's transcript gaps reflect its own outage only.
    • A call whose in-process clock was lost is ended within the margin it was priced for. The durable sweep that ends a /v1 call past its ceiling runs on every server; it no longer waits out a scheduler lease held by a server that died.
  12. A call's ceiling for its whole life, every call in flight priced, null refused, test objects unseen

    2026-11-06

    Changed

    • **A call keeps its maxDurationSec for its whole life** (a security fix: a tightened requirement). A /v1 call is ended at its ceiling, counted from its answer, whatever happened before it: a flow that handed the caller to an agent or a queue, a transfer to a call flow, a voice application or a number, a new flow run. Before, a FLOW or BRIDGE call's ceiling ended with its first flow run, and a call handed on ran for as long as anyone talked. The call and every live leg dialled from it (a transfer target, a conference party, a flow's connect) are hung up, and call.completed reports hangup: { side: "platform", reason: "max_duration" }. A call whose own AI agent or external agent ends the conversation at the ceiling still does so gracefully; the call's own clock only backstops it, at most a minute later.
    • Every dial is priced beside every call in flight (a tightened requirement). POST /v1/calls was priced beside your other API calls in flight; it is now priced beside every call your organization has up — console and campaign calls, inbound calls, and each leg dialled from a live call, which is priced at the ceiling of the call it ends with. A root call with two transfer or conference legs counts three times. The 402 BILLING_INSUFFICIENT_CREDIT refusal's inFlightMinutes includes them. (Console and campaign dials are held to the same rule: a campaign never dials past the credit for the calls it already has up.)
    • **An undocumented null is 400 VALIDATION_FAILED on every write.** Every POST, PATCH and PUT body takes null only where the contract documents the field as nullable (it clears the value, it unassigns); any other null, at any depth of the body, is refused before anything is written. Omit an optional field instead of sending null. For example POST /v1/conversations/{conversationId}/assign with {"email": null} answered 500; it is 400 now ({"userId": null} still unassigns).
    • A test object reads as an unknown id to a live key. A live key naming something a test key created — an AI agent, a call flow or a voice application in POST /v1/calls, a call flow's definition, a number's route, or a sandbox message in POST /v1/messages/{messageId}/read — is answered exactly as an id that does not exist: the same status, code and message (404 AI_AGENT_NOT_FOUND, CALL_FLOW_NOT_FOUND, APPLICATION_NOT_FOUND, NOT_FOUND; 422 CALL_FLOW_INVALID with "no AI agent … in this organization"; 400 "Route to an active AI agent of this organization"). The messages no longer say "created by a test key".
    • **POST /v1/verify/{verifyId}/check counts parallel checks one after the other.** Checks sent at the same time are serialized on the verification: each is counted against the attempts the one before it left, so none is refused with 409 VERIFY_NOT_PENDING while the verification is still pending. The attempt limit holds as before — of ten parallel wrong codes, five are counted and the fifth fails the verification; the other five are 409 VERIFY_NOT_PENDING (failed).
    • A DLT header is refused under a rejected or suspended entity. POST /v1/dlt/headers naming an entity the platform rejected is 409 DLT_REGISTRATION_REJECTED, and one it suspended 409 DLT_REGISTRATION_LOCKED. Register the corrected entity and file the header there.

    Fixed

    • A dial Plivo refused answers 502 with the status alone — never Plivo's own error text, which could quote the number dialled.
  13. AI agents that cannot speak, cross-mode call routes, your own caller ID, answer-URL payload 2, transcript reasons

    2026-11-06

    Added

    • **422 AI_PROVIDER_UNAVAILABLE before an AI_AGENT call is written.** An agent whose voice cannot run on this deployment — its provider has no key, an ElevenLabs voice has no ElevenLabs agent id, a composite voice lacks its transcription or reasoning key — is refused with a reason (voice_key_missing, agent_id_missing, transcription_key_missing, reasoning_key_missing), provider and leg, before the contact is created or the call written: no call, no call.queued, no call.failed. A test call is held to the same check. New error code.
    • **availability on the agent.** GET /v1/agents[/{agentId}] reads availability: { runnable, reason } — whether a call with the agent would be admitted here now, in the same reason vocabulary.
    • **fromSource on calls and every call.* event**: where an outbound call's from came from — request, organization_number, agent_number, carrier_account or platform; null inbound.
    • **payloadVersion on voice applications** (1 or 2; create and update take it). Payload 2 of the answer-URL request reads the call as the call resource does (see Changed).
    • **unavailableReason and gaps on the call transcript.** unavailableReason says why a transcript is unavailable — disabled, too_short, processing_failed, stt_unavailable or not_recorded — and gaps: [{ startedAt, endedAt, phase }] lists when the call's speech-to-text was down (readable while the call is up; a ready transcript with gaps is a partial one). The outage is noted on the transcript, not sent as new webhook events.

    Changed

    • **A call with no from presents the organization's own number** (a changed default). It is one of your inventory numbers on the call's channel — ASSIGNED, outbound-capable, of a series the call may present (a 140-series number for a PROMOTIONAL call only), the oldest assignment first — with its numberId, instead of the platform's shared number a contact could not call you back on. Only when you hold none there does the channel's own caller ID apply (fromSource: platform or carrier_account). An agent-first call keeps the seat's allocated number first. To present a particular number, name it in from.
    • Answer-URL payload 2 for every voice application made from today: call has the call resource's id, from (the calling number) and to (the number dialled) whichever way the call goes — on an outbound call from is your caller ID and to the contact masked •••• ••3210 — a lowercase direction, livemode, numberId and contactId, and the request carries version and livemode. Payload 1 is deprecated and is removed after 2027-02-08: every application that existed before today keeps it (now marked "version": 1) until you switch it with PATCH /v1/applications/{applicationId} { "payloadVersion": 2 }.
    • **An AI_AGENT call that fails after it was written is answered 201** with that call (status: failed, failure.code: AI_PROVIDER_UNAVAILABLE), never a 503 naming no call; its replay with the same Idempotency-Key is that 201 with Idempotent-Replayed: true.
    • Saving an agent that could not take a call is refused (a tightened requirement): /v1/agents answers 422 MODEL_UNAVAILABLE with the reason (an ElevenLabs voice with no ElevenLabs agent id is agent_id_missing), and a model neither the catalog lists nor its provider confirmed is 400. MODEL_UNAVAILABLE for a provider with no key now carries reason too. Agents saved before keep working as they did, and say so in availability.
    • **Every /v1/calls/{callId}/… route answers a call of the other mode as an unknown id** (a tightened requirement): 404 NOT_FOUND, both ways, for the transcript, transcript stream, summary, recording and every live-call action — before, a live key read a test call's transcript and summary and could hold it, and a test key was told a live call existed with 422 TEST_MODE_UNSUPPORTED. Ending a test call stays open to any key (it touches no person, carrier or wallet, and frees a test-call slot); a test key ending a live call is now the 404 too.
    • A live call naming test configuration is answered exactly as an unknown id (CALL_FLOW_NOT_FOUND, APPLICATION_NOT_FOUND, AI_AGENT_NOT_FOUND, the same message), and a live flow document's reference to test configuration reads as a reference to nothing in CALL_FLOW_INVALID's issues.

    Fixed

    • Conferences on a test call. A live key's POST /v1/conferences on a test call is the unknown-call 404 CONFERENCE_NOT_FOUND, not "not available in test mode; use a live key"; a test key is told conferences are live-only whatever the id.
    • Docs: test keys and member presence. A test key reads the same members and teams, with presence: null for every member.
    • Docs: answer URLs in test mode. What a test key can and cannot do with answer-URL applications is stated plainly: the sandbox never fetches an answer URL.
  14. Calls through a speech-to-text outage, caller IDs, event modes, test configuration kept apart

    2026-11-06

    Added

    • Every webhook event says its mode at the top level. Each delivery envelope — and each GET /v1/events item — carries livemode beside type and id: false for test traffic (it reaches test endpoints only), true for live traffic and for every event about what has no test side (balance.low, a port-in, DLT registrations, SMS senders, the WhatsApp account, conferences). It is decided by the same rule that picks the endpoints, so it always matches the livemode of the resource in data; those copies stay. A webhook.test delivery carries its endpoint's mode. The SDKs' envelope types require it.
    • Outbound calls name their caller ID. An outbound call's from is the business number it presents to the contact, in E.164 — the request's from, else the assigned agent's allocated number, else the channel account's own caller ID — and numberId is that number's id when it is in your inventory. Stored when the call is written, so call.queued carries it as every later call.* event does; a test call names what a live one would.
    • Mock summary and extraction on test calls. A test call an AI agent runs (mode: AI_AGENT) ends with the sandbox's mock summary of its scripted conversation (status: ready, mock: true) and, for an agent with an extraction schema, a mock extraction filled from it (valid against the schema, mock: true), told as call.summary.ready once, after call.transcript.ready — so the event and the extraction can be built against before going live. The summary and extraction objects carry mock (always false on a live call).
    • **speechUnavailable on call.gather.completed**: true on a timeout when the gather asked for speech and nothing could listen (see below).
    • **The live gather action takes the flow verb's names.** timeoutSeconds, interDigitTimeoutSeconds and speechTimeoutSeconds are accepted as aliases of timeoutSec, interDigitTimeoutSec and speechTimeoutSec; a name and its alias together is 400 VALIDATION_FAILED.

    Changed

    • A streamed call survives a speech-to-text outage. On a FLOW, BRIDGE, client-voice or browser-voice call (and a listen-only leg), a transcription that cannot connect or drops no longer fails the call: the call goes on untranscribed — its flow runs, it is recorded and rated — and the transcription is retried with a capped backoff. A speech-only gather that nothing can listen to ends at once and takes its onTimeout branch (an answer URL's result says speechUnavailable: true); a dtmf_speech gather listens for keys alone. An AI_AGENT call whose AI cannot start still fails, now as failed with failure.code: AI_PROVIDER_UNAVAILABLE instead of a generic media failure.
    • A live key sees none of a test key's configuration. Test AI agents, call flows and voice applications (livemode: false) are no longer in a live key's GET /v1/agents, /v1/call-flows or /v1/applications, and every route of one — read, PATCH, DELETE, a flow's archive, versions and publish, an application's rotate-secret, an agent's tool-secret — is 404 NOT_FOUND, as an unknown id. A /v1 queue naming a test flow as overflowFlowId is 400 VALIDATION_FAILED, as an unknown flow. Templates, media, webhook endpoints and the status-callback secret were already partitioned.
    • **Cross-mode conversation writes are 404.** A live key's POST /v1/messages with a test conversation's conversationId (the sandbox's thread, a test contact's) is 404 CONVERSATION_NOT_FOUND (was 409 NO_SENDER_AVAILABLE); a test key's on a live customer's thread the same (was 422 TEST_MODE_UNSUPPORTED); a replyToMessageId / reaction.messageId naming a message of the other mode 404 REPLY_TARGET_NOT_FOUND either way — the body an unknown id gets.
    • **Whole numbers are integer in the contract.** Limits, durations, counts, versions and minor-unit amounts were typed number; only latitude, longitude, confidence and itemPrice are fractional. The Go SDK's fields are int / *int (Limit: trovacast.Ptr(50)), and a call flow's Definition is a typed *CallFlowDocument (the contract marks each call-flow definition with x-document: CallFlowDocument).
    • **The test-call cap names its count testCalls.** A test call over the sandbox's cap is 429 CALL_CONCURRENCY_LIMIT with livemode: false and testCalls (was liveCalls, added the day before); the live caps keep liveCalls.
    • **GET /v1/members leaves out platform staff** who hold no role in the organization (the platform administrator who created it was listed as a member).

    Fixed

    • **A 401 names its scheme**: WWW-Authenticate: Bearer realm="trovacast".
    • The API reference's event catalog lists number.port_request.updated, and is checked against the published catalog so it cannot drift again.
  15. India SMS checked against DLT at every send, call ceilings held on every carrier, `null` refused on upserts

    2026-11-06

    Changed

    • An SMS to India needs its header's own verified DLT registration at every send — a tightened requirement. The header must be one your organization recorded as an SMS header and the platform verified, under a verified entity (Settings › DLT, or POST /v1/dlt/headers). Otherwise POST /v1/messages (and POST /v1/verify to an Indian number) answers 409 SMS_SENDER_NOT_ALLOWED (country: "IN"), and a message already queued fails with SMS_SENDER_NOT_ALLOWED instead of reaching a carrier. When a header is not named, a registered one is preferred. And when India becomes reachable for you — your SMS countries gain IN, or the platform enables India — every active header without that registration goes back to pending_verification (sms.sender.updated) until the platform activates it again.
    • **An AI_AGENT call ends at its maxDurationSec on every channel.** The line already playing is let out, then the call is hung up, and the call's hangup reads { side: "platform", reason: "max_duration" }. On Airtel IQ, which takes no per-call time limit, nothing ended such a call before; on other channels the carrier's own limit ended it up to 75 s later.
    • A call in flight is priced at its own ceiling only while something holds it there — its media leg (an AI agent's conversation, a flow, an external agent) or its carrier's time limit. One that nothing holds — an agent-first BRIDGE on a channel whose bridge takes no per-call limit — is priced at the deployment's call time limit, so a 402 BILLING_INSUFFICIENT_CREDIT may come sooner while one is up.
    • **Client voice: a token that binds callerIds places a call that names no from from its first bound number** — never your organization's default caller ID. A token that binds none is unchanged.
    • **GET /v1/members answers presence: null to a test key.** Who is on a call right now is live traffic; the seats themselves are listed as for a live key.
    • A rejection is sticky across your account. A DLT header or SMS sender value the platform rejected for one organization cannot be recorded by its parent organization or any of its subaccounts either (409 DLT_REGISTRATION_REJECTED, 409 SMS_SENDER_REJECTED) until the platform lifts the rejection.
    • A rejected DLT entity cannot be edited (409 DLT_REGISTRATION_LOCKED), as a verified or suspended one already could not; ask the platform to reopen it, or record the corrected one as a new entity.
    • holder_gone on dlt.contest.updated and sms.sender_contest.updated means the value your claim waits on became free; it never says what happened to the holder.

    Fixed

    • POST /v1/contacts on an existing contact answered attributes: null with a 500 and silently reset the name on displayName: null. null in displayName, email, externalReference or attributes is now 400 VALIDATION_FAILED; leave a field out to keep it (PATCH /v1/contacts/{contactId} clears externalReference).
    • POST /v1/verifications answered country: null with a 500; null in country or version is now 400 VALIDATION_FAILED.
  16. Teams and members, both ends of a call, calls admitted by mode

    2026-11-06

    Added

    • Teams and members. GET /v1/teams (teams:read) and GET /v1/members (members:read), read-only and cursor-paged: the team ids POST /v1/queues takes, and the seat ids a queue's members and a BRIDGE call's bridge.to.agentMembershipId take, with each member's display name, email masked (a•••@example.com), status, roles, teams and desk presence. A test key reads the same rows (Teams and members).
    • Both ends of a call. The call resource — and so call.inbound and every call.* event — carries to and numberId: an inbound call's to is your number the caller dialled (international format) and numberId its id; an outbound call's to is the contact masked to the last four digits (•••• ••3210). An inbound call's from is now the caller, masked the same way (it was null); an outbound call's from is unchanged.
    • Conversations say their mode. Every conversation carries livemode (false for a test contact's thread or one on the platform's test sender).
    • A credit refusal of a call (402 BILLING_INSUFFICIENT_CREDIT) carries inFlightMinutes and, when a shorter call would be placed now, maxDurationSecAvailable — the longest maxDurationSec that fits.
    • A test call over the sandbox's own cap is 429 CALL_CONCURRENCY_LIMIT with livemode: false (10 test calls at once per organization).
    • A Go SDK. github.com/trovakap/recalling-new/packages/trovacast-go (Go 1.24+, standard library only): a typed method per operation, a Go type per schema, the same idempotency, retry, error and pagination rules as the Node.js and Python SDKs, and VerifyWebhook — not published yet (SDKs).

    Changed

    • Calls are admitted by mode. Test calls never count against your live calls' caps or billing exposure, and live calls never against test calls' — a test call has a cap of its own instead.
    • Each call in flight is priced from its own ceiling, at its own rate. A live call is priced beside your live calls in flight, each at its own maxDurationSec (every mode now stores it; a FLOW, BRIDGE or AI_AGENT call was priced at the hour-long fallback) and its own rate (a flow or bridge at the manual rate, an AI or external-agent call at the AI rate) — never the new call's. A refusal's advice is only ever one that would be placed: a shorter maxDurationSec when one fits, else waiting for a call in progress to end.
    • Conversations are read in the key's own mode. GET /v1/conversations, GET /v1/conversations/{conversationId} and its messages answer a live key's live threads and a test key's test threads only; another mode's thread is a 404.
    • A test contact becomes live when live traffic uses it — a live message or call to it, a real inbound message or call from its number, or a live key's write — for good, audited, clearing the opt-ins recorded in test mode; its consent and conversation events are live events from then on.

    Fixed

    • A test key's reply into a live customer's conversation, or its reaction to (or reply quoting) a live message, is 422 TEST_MODE_UNSUPPORTED; it was written into the live thread.
    • A jump a live call takes into another flow (a queue's overflow, a closed queue's after-hours flow) never runs a flow a test key created.
    • A Plivo call whose callbacks were lost before it was answered is read back from Plivo's Call API and closes in minutes (no_answer, busy, …), instead of holding a live-call slot for 15 minutes.
    • The docs said conversation.opened fires for WhatsApp only; SMS and email threads open the same way.
  17. Sender values belong to their business: claims survive the holder, rejections stick, voice headers follow their number

    2026-11-06

    Added

    • dlt.contest.updated (dlt:read) and sms.sender_contest.updated (sms:read): every outcome of your claim on a DLT header or SMS sender another organization held — opened, holder_gone, awarded (headerId / senderId), dismissed. Never names the holder.
    • Codes: 409 DLT_REGISTRATION_CONTESTED, 409 DLT_REGISTRATION_REJECTED, 409 SMS_SENDER_CONTESTED, 409 SMS_SENDER_REJECTED; client voice 403 VOICE_CALLER_ID_NOT_ALLOWED.
    • POST /v1/voice/access-tokens: purpose (what the token's calls are for, default TRANSACTIONAL) and callerIds (the from numbers its calls may use — your own assigned voice numbers), bound into the token and echoed in grants.

    Changed

    • A DLT header someone claims cannot be withdrawn (nor its entity) until the platform decides; a value the platform rejected for you cannot be recorded again until it lifts the rejection; a reject no longer dismisses the other claims on the value.
    • A 140/160-series header is released with its number — a cancelled or lapsed hold, a release, an erased organization.
    • A suspended or rejected DLT entity cannot be deleted by its organization, and a principal-entity id typed into the SMS settings must be one of your own verified entities.
    • An SMS sender holds its header only while live; a claim on a held header waits for the platform; a disabled header cannot be registered again by the organization it was disabled for until lifted; for India a header is activated only under your own verified DLT header of the same value.
    • Client voice: call:place refuses respectCallingWindow and purpose (400 VALIDATION_FAILED): a client call always keeps to the calling window and takes its purpose from the token. A new socket is refused client:revoked service_unavailable when the platform cannot count connections (caps are now exact across replicas).
  18. `null` means clear, or it is refused

    2026-11-06

    Changed

    • **null in a nested or PUT field is refused — a tightened requirement.** On every PATCH and PUT, a field nested in an object (voice, tracking, …) or in an array's elements (members[]), and every PUT field, takes null only where the contract declares it nullable; anywhere else it is 400 VALIDATION_FAILED. Twenty fields read null as "left as it is" or as their default — PATCH /v1/email/domains/{domain} with tracking: { opens: null } left open tracking on. They are voice.voiceId, reasoning.provider and transcription.model on /v1/agents (create and update), marketing, updates, textShown and capturedAt on PUT /v1/contacts/{contactId}/consent/{channel}, tracking.opens and tracking.clicks (and tracking must be an object), and a member's priority and skill and the list's version on PUT /v1/queues/{queueId}/members. To keep a value, leave the field out.
  19. A sensitive gather pauses every recording of the call, or does not run

    2026-11-06

    Added

    • GET /v1/calls/channels answers sensitiveGather per channel: whether a sensitive gather can run on the channel's recorded calls (its carrier pauses its own recording for it — Twilio and Telnyx — or keeps none).
    • 503 RECORDING_PAUSE_FAILED: the carrier did not confirm it paused its recording for a sensitive gather; nothing was collected. Retry with a new Idempotency-Key.

    Changed

    • A tightened requirement: a sensitive gather runs only while every recording of the call is paused. It used to pause Trovacast's own recording only, while a carrier that records the call itself kept recording the digits. Now, on a recorded call, the carrier's recording is paused before the action answers (Twilio, Telnyx) and resumed when the gather ends — or, on a channel whose carrier cannot pause it (Plivo, Exotel, Airtel IQ: sensitiveGather: false), the gather is refused with 409 RECORDING_NOT_CONTROLLABLE and nothing is collected. A flow's sensitive gather that is refused fails its run (FLOW_ERROR; call.flow.failed names flow.cause). A call that is not recorded is unaffected on every channel. To collect card numbers or PINs on those carriers, collect them on a call that is not recorded.
  20. Test traffic stays on test endpoints, examples that run, AI agents before provider keys

    2026-11-06

    Added

    • AI agents in test mode without provider keys. A test key's GET /v1/models also lists the mock provider's mock-voice and mock-reasoning (testOnly: true; every model now carries testOnly). A test agent on them (voice: { provider: "mock", model: "mock-voice" }) is created and its AI_AGENT test calls run before your organization has any AI provider key. A live key never sees the mock and is refused it (422 MODEL_UNAVAILABLE); a live agent needs a real provider.
    • Usage for a subaccount. GET /v1/usage?subaccountId= gives a parent one of its subaccounts' day × channel × destination rows (the key also needs subaccounts:read; not your subaccount is 404). The answer's subaccountId names whose spend it is (null for your own).
    • contact.consent.updated, conversation.opened and conversation.resolved carry data.livemode (see Fixed).
    • GET /v1/numbers/available answers warnings[] (see Changed).
    • hangup.side value application, and hangup.reason values hangup_verb, instructions_ended, ai_ended, callback_requested, flow_failed and caller_hung_up (see Fixed).
    • An inbound call routed to a call flow or a voice application fills flow (source: call_flow with callFlowId, or source: application with applicationId); it read flow: null.
    • Named request examples for orderNumber (inventory, supplier stock), updateNumber (label, route to a flow, to a client, back to none), createSandboxInboundMessage (WhatsApp, SMS STOP, email), validateCallFlow and createCallFlowVersion (a menu flow) and updateSubaccount (rename, suspend).

    Changed

    • A supplier that cannot be searched no longer fails the number search. GET /v1/numbers/available answers the inventory and every carrier that answered, and names each one it could not search in warnings[] (code: NUMBER_SUPPLIER_UNAVAILABLE, supplier, orderable — whether you could have ordered its stock — retryAfterSeconds). It is 503 NUMBER_SUPPLIER_UNAVAILABLE only when nothing could be searched (every carrier asked failed and the inventory has nothing that matches).
    • **hangup.side reports only a recorded ending — a correction.** A completed call that nothing recorded an ending for read contact; it now reads unknown. The platform records its own endings first (your API hang-up and hangup frame as agent; a flow's or answer URL's own hang-up as application; the ceiling, a lost agent or a failed flow as platform; the caller leaving a running flow as contact), so what reads unknown is the carrier ending the call without saying who.
    • A voice DLT header names one of your own numbers — a security fix. POST /v1/dlt/headers (and the platform's verification) refuses a voice_140 or voice_160 header whose number is not one of your own numbers of that series, held (reserved) or assigned: 422 DLT_NUMBER_NOT_HELD. A header could otherwise claim a number another business uses. For a 140-series number: hold it (POST /v1/numbers — it stays reserved and pending says what is missing, the verified header last), record its header, then activate it (POST /v1/numbers/{numberId}/activate) once the platform verifies the header.
    • A subaccount key's mode takes TEST/LIVE (as GET /v1/me names a key's mode) as well as test/live.
    • A test call's transcript: only a test call an AI agent runs (mode: AI_AGENT) gets the sandbox's scripted conversation. A FLOW, BRIDGE or EXTERNAL_AGENT test call is not scripted — nothing spoke — and reads unavailable (a silent flow's test call used to "say" eight lines).
    • PATCH /v1/subaccounts/{subaccountId} checks its body (a name of 2–120 characters; something to change) before it looks the subaccount up.
    • Versioning, stated honestly: a security or safety fix may tighten a default inside v1 (as the home-market voice default did today), always announced here under Changed with the code you will meet — see the note at the top of this changelog and Versioning.

    Fixed

    • Test traffic reached live webhook endpoints. A test contact's contact.consent.updated (a test key's consent write, a sandbox message's STOP or opt-in) and a test thread's conversation.opened / conversation.resolved (a test contact's thread, or one on the platform's test sender) were delivered to your LIVE endpoints and never your TEST ones. Every event's mode is now its subject's — the message, call, verification or template it embeds, the contact whose consent moved, the thread — and events about what has no test side (the WhatsApp account, port-ins, DLT registrations and SMS senders, the balance, conferences) are live. These three events carry it as data.livemode.
    • Sandbox replies. A test key replying on the sandbox's thread by conversationId, or reacting to its messages with no recipient, was refused 409 NO_SENDER_AVAILABLE; the test sender now stands in as it does for a send by contact.
    • Every published request example is a body the API accepts — run through the validators and each service's own rules in CI. Six were refused: POST /v1/numbers (no provider), PATCH /v1/numbers/{id} (only version), POST /v1/sandbox/inbound-messages (no customer; a subject on WhatsApp), validateCallFlow and createCallFlowVersion (an empty definition), a consent write recording no decision, and PATCH /v1/subaccounts/{id} with nothing to change.
    • A flow's or answer URL's hangup verb read as the contact hanging up.
    • Docs: a flow's ai verb is built (the reference said it was refused); the voice quickstart explains the AI-call switch (off for a new organization: 409 AI_CALLS_DISABLED) before your first live EXTERNAL_AGENT call.
  21. A contract that describes itself: webhooks, docs links, every operation

    2026-11-06

    Added

    • The webhook catalog is in the contract. x-webhooks (OpenAPI 3.0 has no webhooks keyword; the shape is 3.1's) lists every event type as the signed POST it is — its Trovacast-Signature, Trovacast-Event-Id and Trovacast-Event-Type headers, the scopes that read it (x-required-scopes), x-opt-in for call.transcript.segment — and its delivery body as a component schema: WebhookEvent<Name> (the envelope; message.sent → WebhookEventMessageSent) with its data as WebhookEvent<Name>Data, embedding the same resource schemas the reads answer with. webhook.test is listed too.
    • Errors link to their docs. Every /v1 error envelope carries docUrl: the code's row on the developer site's errors page (https://trovacast.com/developers/errors#code-api-key-scope-missing; a META_<code> links to the family's row). The errors page gives every code what it means and what to do.
    • Every operation is described, ending with who may call it — the key kind and scope, and "Live keys only" where a test key is refused — also machine-readable as x-required-scope. Operations a test key is refused by their scope (recordings:*, contacts:export, whatsapp:manage, email:manage) say so too (x-live-only stays the flag of the routes that refuse it themselves).

    Changed

    • Call-flow validation names the problem. A verb written { "type": "say" } answers "unknown field type — a verb is named by verb (say, play, …)" instead of "Invalid input"; an unknown verb names the closest real one; a known verb's own problems are reported at their own paths with what was expected ("missing text (a string)", "expected one of completed, rejected, busy"); branch targets and connect.to name their forms. 422 CALL_FLOW_INVALID's message carries the first issue (The flow does not validate: definition.nodes.main.0: …); issues (path, message) is unchanged in shape.
    • Response documentation corrected: createAgent / updateAgent answer 409 AI_AGENT_NAME_TAKEN / AI_AGENT_VERSION_CONFLICT (not CONFLICT); hangupCall, markMessageRead and the conference participant and end operations declare the 422 TEST_MODE_UNSUPPORTED they answer; createOrganization declares 409 ORGANIZATION_ERASING; creating an application or a call flow never answers TEST_MODE_UNSUPPORTED.
    • Descriptions link to the developer site (https://trovacast.com/developers/…) instead of naming repository files.
  22. Client voice for your own app, honest test transcripts

    2026-11-06

    Added

    • Client voice: your own app — a web page or a native app — places and answers calls as one identity of your organization. POST /v1/voice/access-tokens (new scope voice:client, live keys) mints a short-lived, signed token for an identity; the app connects with it through the new @trovacast/sdk/voice (VoiceDevice): it places calls to numbers under every rule POST /v1/calls applies (the outgoing grant needs calls:write), is rung by a number routed to it or any flow's connect, answers, mutes, holds, sends DTMF and hangs up. The audio travels over the socket (PCM16, 8/16/24 kHz) — not WebRTC.
    • Number routes: route: { kind: "client", identity } rings every app connected as that identity (nobody answering in 30 s ends the call as busy). The route reads back with identity (null on every other kind).
    • Call flows: connect takes to: { client: "<identity>" }.

    Changed

    • A test-mode EXTERNAL_AGENT call no longer gets the scripted transcript (no segments, call.transcript.segment or call.transcript.ready): live never transcribes that mode. Every other mode keeps it. The docs now say which modes are transcribed, and that a person's call's live transcription is part of its manual per-minute rate.
    • POST /v1/conferences/:id/participants with to.callId stays refused (422 CONFERENCE_PARTICIPANT_UNSUPPORTED, reason: call); the docs now say why a live call cannot be merged into another's room safely, and what to do instead.
  23. Sender registration, MMS, and loose ends

    2026-11-06

    Added

    • DLT registrations over the API. GET /v1/dlt/entities, POST /v1/dlt/entities, GET/PATCH/DELETE /v1/dlt/entities/{id}, POST /v1/dlt/headers and GET/DELETE /v1/dlt/headers/{id} record India's DLT principal entity and its SMS and 140/160-series headers for the platform to verify — the records the console edits. New scopes dlt:read and dlt:write (live keys only); new events dlt.entity.updated and dlt.header.updated; codes DLT_ALREADY_REGISTERED, DLT_REGISTRATION_CLAIMED, DLT_REGISTRATION_LOCKED, DLT_VERSION_CONFLICT.
    • SMS senders are writable. POST /v1/sms/senders registers a DLT header or alphanumeric sender ID (pending until the platform activates it), GET /v1/sms/senders/{id} reads one and DELETE /v1/sms/senders/{id} removes one. New scope sms:manage (live keys only); new event sms.sender.updated (sms:read) for every status a sender reaches; codes SMS_SENDER_ALREADY_REGISTERED, SMS_SENDER_CLAIMED.
    • WhatsApp senders. GET /v1/whatsapp/senders and GET /v1/whatsapp/senders/{id} (whatsapp:read) list the account's numbers with their status, canSend, and Meta's name review, quality and tier.
    • MMS to the US and Canada. POST /v1/messages with channel: "sms", type: "mms" sends one JPEG or PNG (media.url or media.id, at most 5 MB) with optional text, from one of your registered US or Canadian numbers through the platform's Twilio route, priced once per message on the plan's new MMS cell (category: "mms", unit: "message" on GET /v1/pricing). Anywhere else is 422 SMS_MMS_UNSUPPORTED with country, before anything is created; the message reads type: "mms" with its media block. Test keys send to the SMS sandbox.
    • PDF statements. GET /v1/invoices/{period}.pdf, or GET /v1/invoices/{period} with Accept: application/pdf, answers the month's statement as a one-page PDF (JSON stays the default).

    Changed

    • Subaccounts follow their parent. A parent organization's suspension suspends its active subaccounts with it (suspendedBy: "with_parent", a new value) and its reactivation brings them back — not one the parent or the platform suspended on its own; a change of the parent's plan moves its subaccounts to the new rate card (still without a fee or allowance of their own). Each move is audited in the subaccount's own trail.
    • GET /v1/numbers/available fails with 503 NUMBER_SUPPLIER_UNAVAILABLE (suppliers, retryAfterSeconds) when a carrier whose live stock it includes cannot be searched, instead of answering without that stock — an empty list read as "nothing for sale". includeSupplierStock=false searches the platform's own stock alone; it is now read correctly from the query string (false was read as true).
    • GET /v1/pricing lists voice cells only for the channels this deployment runs, by their public names: a plan's cells for a carrier that is not enabled here (exotel on most deployments) and the internal sim channel are no longer listed. voice[].provider is one of the channels /v1/calls can name.
    • POST /v1/numbers/{id}/sms-sender registers a US or Canadian number as pending_verification (it was active at once): those countries' carriers register every sender (10DLC, toll-free verification), so the platform activates it, as when the number is registered in the console. Elsewhere a number is still active at once. sms.sender.updated reports both.
  24. Examples that work, every code published, paperwork for every number

    2026-11-06

    Added

    • GET /v1/models marks each model available: whether this deployment can run it. An agent whose voice, reasoning or transcription leg names a provider that is not available is refused when it is created or updated (422 MODEL_UNAVAILABLE, with provider, leg and model) instead of failing its first call.
    • The call-flow language is in the contract as JSON Schema: CallFlowDocument (a stored flow), CallFlowAnswerDocument (what an answer URL returns), CallFlowVerb and one CallFlowVerb<Name> per verb. The SDKs build and validate both documents against it.
    • Named request examples, one per variant, for createCall (each mode), createMessage (each channel and type), createBroadcast, createCallAction and createTemplate. Every request example in the contract now passes its operation's validation as published.
    • A path that exists answered with a method it does not take is 405 METHOD_NOT_ALLOWED, with the methods it does take in the Allow header and allow in the body (it was 404).
    • Codes the API already answered with are now in PublicApiErrorCode and the SDKs' lists: AUDIENCE_EMPTY, AUDIENCE_TOO_LARGE, BROADCAST_INVALID_STATE, ORGANIZATION_NOT_ACTIVE, VERIFICATION_INCOMPLETE, META_UNAVAILABLE, READ_RECEIPT_NOT_CONFIRMED, UPLOAD_SESSION_REFUSED, MEDIA_REDIRECT_REFUSED, WHATSAPP_SANDBOX_MIXED, WHATSAPP_SANDBOX_TARGET and WHATSAPP_SANDBOX_NOT_IMPLEMENTED — and the new MODEL_UNAVAILABLE.
    • Quickstarts: an AI agent with a tool your server answers, and inbound calls from a number to call.inbound.

    Changed

    • The request fields first published in upper case — a call's mode and purpose, consent source and a WhatsApp template's category — accept either case (ai_agent or AI_AGENT); the contract lists both spellings. Nothing you already send changes.
    • Generated request examples use well-formed sample ids instead of placeholders such as CONTACT_ID.

    Fixed

    • A toll-free, 140-series or 160-series number for an organization with no business verification (one an integration provisioned) was activated without its letter of authority. Every organization now needs an accepted NUMBER_LOA on file for those types (VERIFICATION_DOCUMENTS_REQUIRED).
    • A body that is not valid JSON is answered with a requestId like every other error.
    • A 429 says how long to wait (Too many requests — retry after 17 s).
    • A nested field's validation message names its path once (to.phone, not to.to.phone).
    • A template message naming neither template.id nor template.name is told one is required (it was told "not both").
    • Pausing the recording of a call nothing is recording answers recording: false; it no longer claims the carrier records the call.
    • Descriptions in the contract no longer carry internal build labels.
  25. Voice and AI depth

    2026-11-06

    Added

    • AI inside call flows: the ai verb, and connect with to: { ai: agentId }, now run: one of your AI agents takes the caller for a step of the flow (inbound or outbound) and ends the call, hands the caller back to the flow (its hand_back tool) or passes them to a person (transfer_to_person, offered when the step has onEscalate). The step's outcome is the ai variable (ended, handed_back, escalated, max_duration, failed); an agent that cannot run takes onEscalate (else the next verb), never hanging up on the caller. A call that ran an AI step is rated as an AI call. Flows using either are no longer refused with 422 CALL_FLOW_INVALID; an archived agent is.
    • Live transcripts: call.transcript.segment (opt-in; calls:read + transcripts:read) delivers each final segment of a live call as soon as it is stored, and GET /v1/calls/{callId}/transcript/stream serves the transcript as Server-Sent Events (resumable with Last-Event-ID, end once final, at most 20 open streams per project). Nothing said while a sensitive gather is open is transcribed. A test call's transcript is the sandbox's scripted conversation, with its events and call.transcript.ready.
    • Verify (one-time codes): POST /v1/verify (createVerify) sends a code by SMS, WhatsApp, voice call or email; POST /v1/verify/{verifyId}/check (checkVerify) and …/resend (resendVerify); GET /v1/verify/{verifyId} (getVerify); events verify.approved and verify.expired; scopes verify:read and verify:write. Expiry, five attempts, five sends 30 s apart, velocity limits per destination and project, premium-rate / high-risk / policy- blocked destinations refused; each send billed at the channel's message rate (a voice code is a call). Codes are never stored. Test keys send nothing; their code is 123456. New error codes VERIFY_*.
    • Lookup: GET /v1/lookup/{phone} (lookupPhoneNumber, new scope lookup:read) answers whether a number is valid (with invalidReason when it is not), its E.164 and national formats, country, calling code and type (mobile, fixed_line, toll_free, …), and for a +91 number its status on India's do-not-call registry (NCPR) as the platform operator loaded it. National numbers take ?country=. Free (it counts against the key's request budget), test keys included; carrier is in the shape but available: false — no carrier names without a vendor. The number in the path is never stored or logged. New error code PHONE_NUMBER_MALFORMED (400).
    • Call queues over the API: GET /v1/queues (listQueues), POST /v1/queues (createQueue), GET/PATCH/DELETE /v1/queues/{queueId} (getQueue, updateQueue, deleteQueue) and PUT /v1/queues/{queueId}/members (setQueueMembers), under the new scopes queues:read and queues:write — every setting of the console's queue form (strategy, ring timeout, maximum wait and size, wrap-up, service level, hours, hold prompts or audio, overflow, announcements, callback, skill routing, alert thresholds, transfer boost, on/off) and the members with their tier and skill, under the console's rules and a version compare-and-set. Writes are live-only. Error codes TEAM_NOT_FOUND, QUEUE_VERSION_CONFLICT, QUEUE_NAME_TAKEN and QUEUE_IN_USE are now published (QUEUE_NOT_FOUND answers an unknown queue here too).
    • Numbers on Twilio and Telnyx answer their inbound calls, as numbers on Plivo already did: a number routed with PATCH /v1/numbers/{numberId} to a call flow, a voice application, a queue, a person or an AI agent takes its calls on those carriers too, and call.inbound fires when the caller is on the line. A number routed to an AI agent runs each call as an AI call (mode: ai, direction: inbound, aiAgentId set) voiced by that agent. On those carriers a call to a number that routes nowhere is rejected without being answered, so nobody is billed for it. No request, response or event shape changed.

    Changed

    • The SMS docs now say plainly that MMS is not supported: an SMS send with media is 400 VALIDATION_FAILED, as it always was.
  26. Security fixes: voice reach defaults to the home market

    2026-11-06

    Changed

    • Calls reach the home market only by default — a changed default. A call placed to a contact (console, campaigns, sequences, POST /v1/calls in every mode, and a TEST key's sandboxed call alike) now reaches India (+91) and nothing else unless the platform opened another country for your organization: anything else is 422 DESTINATION_BLOCKED. Until now every country except +1 was dialled, at your plan's standard (home) rate. A country the platform opens for you must be priced on your plan with a rate of its own (422 DESTINATION_NOT_PRICED otherwise) — never the home rate. +1 keeps its rules (opened per organization, your TCPA acknowledgement, the TCPA calling window). Transfers, conference parties and BRIDGE numbers keep their own list (childLegPrefixes). Self-hosted deployments can widen the default with VOICE_DEFAULT_DESTINATION_COUNTRIES (never 1).
    • DESTINATION_BLOCKED carries no countryCallingCode when the number's country could not be read at all (it is refused, not guessed).

    Added

    • GET /v1/settings/destinations answers defaultCountryCodes — the home market every call to a contact may reach with nothing opened.

    Fixed

    • POST /v1/messages checks your API key (and your per-key rate limit) before it reads the request body: a request with no key or an unknown key is answered 401 without its body being read, and a body declared past 12 MB is a 413 before it is read. A connection whose request was refused before its body arrived is closed after the answer (send the body only with a valid key, or read the response before you finish sending). Bodies past each route's cap are refused at the edge with 413 (/v1/messages 13 MiB, /v1/media 17 MiB, KYC documents 11 MiB, every other /v1 route 1 MiB).
    • A number routes only to a live AI agent: PATCH /v1/numbers/{id} with route.kind: ai naming a test agent (one a TEST key created) is a 400, and an inbound call to a number whose route names one is answered with the apology and hung up — a test agent answers test calls only.
    • A test contact's opt-out now stops a live message sent to it: only the opt-ins a TEST key recorded are ignored for live sends (before, the whole consent row was, so an unsubscribe after a transactional message was queued did not stop it). Promoting a test contact to live (its first live write) writes a consent.test_opt_ins_cleared audit entry naming the channels whose opt-ins it cleared.
    • An SMS long code (one of your numbers registered as a sender) sends only while its number is assigned to you and SMS-capable: a number suspended (by the platform, or for non-payment) or with SMS turned off sends nothing — refused when you send, failed MESSAGING_SENDER_RESTRICTED if it was queued before — and its sender reads restricted until the number is reinstated. A STOP or START texted to a suspended number still updates the contact's SMS consent; any other text to it is dropped.
    • An idempotent replay never carries a secret: every secret-bearing field (secret, toolSigningSecret, any …Secret, at any depth) reads [redacted: a secret is shown once and never replayed] in a replayed response — an agent's create or update with the same Idempotency-Key used to replay its toolSigningSecret.
    • Inbound email through SES is held to the same sender check as SendGrid: a mail whose From: domain publishes no DMARC policy (SES's GRAY), or whose DMARC evaluation failed, joins a contact's thread only when SPF passed for an aligned envelope sender or DKIM passed for an aligned signing domain; otherwise it is kept as unverified, out of every thread.
    • The TCPA acknowledgement (console › Settings › Calling › Destinations) is given only by an administrator seated in the organization — never by a platform account with no seat there; refused attempts, and refused destination widenings, are audited.
    • Per-request status callbacks (statusCallback) are held to the rules webhook endpoints are: a callback to a host your organization has no live callback to spends the webhook URL budget (20 new hosts or endpoint URLs an hour; 429 RATE_LIMITED with Retry-After past it — send to a host you already use), your callbacks to one host share one circuit breaker, and every receiving host has an in-flight cap across the platform.
    • A free-text SMS with sms.category: transactional must carry its one-time code (4 to 10 digits), else 400.
    • The opt-out line a promotional SMS abroad gains is added unless its text already carries an opt-out instruction ("Reply STOP", "Text STOP", "STOP to opt out", …) — the word STOP alone ("Non-stop deals!") no longer counts as one.
    • An approved verification takes no document from a TEST key (422 TEST_MODE_UNSUPPORTED) and holds at most 5 documents waiting for review; the organization's administrators can remove one of those.
  27. Call outcomes name the organization's own wrap-up code

    2026-11-06

    Added

    • The call summary's outcome (GET /v1/calls/{callId}/summary and call.summary.ready) carries code and label: when the agent filed one of the organization's own wrap-up codes, its slug and the label they picked (a code renamed since still reads as filed); value stays the standard outcome the code counts as. Both are null for a standard outcome and for the AI's verdict.
  28. Try messaging before KYC

    2026-11-06

    Added

    • Messaging sandbox for test keys. A new project's test key sends WhatsApp, SMS and email on day one — no business verification, WhatsApp connection, SMS settings, DLT registration or verified email domain. With no sender of its own on a channel, a test send goes out from the platform's test sender (sandbox@test.trovacast.com for email). See Try messaging before KYC.
    • warnings on every message: for a test send, what a live send would still need, by code — WHATSAPP_NOT_CONNECTED, TEMPLATE_TEST_ONLY, SMS_NOT_CONFIGURED, SMS_SENDER_MISSING, SMS_TEMPLATE_REQUIRED, SMS_DLT_TEMPLATE_ID_MISSING, SMS_DLT_ENTITY_MISSING, SMS_HEADER_CATEGORY_MISMATCH, SMS_OUTSIDE_SEND_WINDOW, SMS_DESTINATION_NOT_ALLOWED, EMAIL_NOT_CONFIGURED, EMAIL_FROM_NOT_VERIFIED. Always empty on a live message.
    • Test templates: with a test key, POST /v1/templates creates a template (livemode: false — a new field on every template) under the same rules as a live one, reviewed by the sandbox instead of Meta or DLT (a WhatsApp name containing reject is rejected, pending stays pending, anything else is approved at once), announced as template.updated to test endpoints only. Only test sends and test broadcasts use them; a live key never sees one, and a test template may share a live one's name.
    • The sandbox mailbox: GET /v1/sandbox/emails (listSandboxEmails) and GET /v1/sandbox/emails/{messageId} (getSandboxEmail), scope messages:read — every email your test keys sent, with its rendered text and HTML; also in the console (Settings → Developers → Sandbox mailbox).
    • Simulated customer messages: POST /v1/sandbox/inbound-messages (createSandboxInboundMessage), scope messages:write, test keys only — a test contact "writes" on WhatsApp, SMS or email; message.received goes to test endpoints, a WhatsApp one opens the 24-hour window, an SMS STOP/START moves the test contact's SMS consent.
    • Test broadcasts: with a test key, POST /v1/broadcasts broadcasts to the project's test contacts through the sandboxes, unbilled.
    • Error code SANDBOX_TEST_KEY_REQUIRED (403): a live key asked for a sandbox-only operation.

    Changed

    • Test keys are no longer refused whole for templates:write and broadcasts:write: a live template is refused per record (422 TEST_MODE_UNSUPPORTED), a template sync (POST /v1/templates/sync, which reads Meta) per route, and broadcast pause/resume/cancel find broadcasts of the key's own mode only.
    • A test SMS to India is accepted as free text or without its DLT ids (as warnings) and is never held for the promotional window; a test email is accepted from an unverified from (as a warning).
    • A live broadcast's audience is the project's live contacts only (a test contact never receives a live broadcast).
  29. Subaccounts; top-ups over the API

    2026-11-06

    Added

    • Subaccounts (/v1/subaccounts, scopes subaccounts:read and subaccounts:write): your organization creates its own projects — each a separate organization with its own keys, wallet, members, data and audit trail — invites each one's owner, suspends and reactivates them, mints and revokes their keys, and reads their usage (calls, minutes, messages by channel, charges and balance — counts and money, never their data). One level only, up to 100. Writes are live-key only.
    • business: "same" | "separate" when you create one: a same-business subaccount shares your business verification (approved and revoked with yours); a separate business verifies on its own.
    • Credit transfers (POST /v1/subaccounts/:id/transfers): fund a subaccount's wallet from yours, or move its unspent credit back (direction: "to_parent"), in one transaction; never below zero. A subaccount is on your plan's rate card with no fee, included minutes or trial credit of its own. Statements gain transfer_in and transfer_out lines.
    • Top-ups over the API (POST /v1/balance/top-ups, GET /v1/balance/top-ups/:id, scope billing:manage, live keys): a hosted checkout link for a person to pay, with your own https return URLs; the wallet is credited when the payment gateway reports the payment, and a read of a pending top-up asks the gateway.
    • Error codes SUBACCOUNT_LIMIT_REACHED, SUBACCOUNT_NESTING_NOT_ALLOWED, SUBACCOUNTS_NOT_AVAILABLE, SUBACCOUNT_INSUFFICIENT_BALANCE, VERIFICATION_INHERITED_FROM_PARENT, and the top-up refusals BILLING_TOP_UP_BELOW_MINIMUM, BILLING_TOP_UP_ABOVE_MAXIMUM, BILLING_PAYMENTS_UNAVAILABLE; VERIFICATION_REQUIRED gains feature: "subaccounts".

    Changed

    • billing:manage now also starts top-ups (it still never moves credit by itself: the payment does).
  30. AI agents that do real work; onboarding without the console

    2026-11-06

    Added

    • AI agents (POST/PATCH /v1/agents) take firstMessage, firstSpeaker (agent or caller), language (BCP 47), endCallPhrases, maxTurns, tools and extraction, and every agent answers them (with toolSigningSecretLast4).
    • Tools: functions an agent calls mid-call, answered by your HTTPS endpoint — a signed agent.tool_call POST (the webhook signature scheme, the agent's own secret), 4-second deadline, 16 KB answer; the result is what the agent tells the caller. The first tool mints the secret, answered once as toolSigningSecret; POST /v1/agents/{agentId}/tool-secret (rotateAgentToolSecret) rotates it.
    • Post-call extraction: an agent's extraction.schema is applied to each finished call's transcript; the result is extraction on GET /v1/calls/{callId}/summary and in call.summary.ready.
    • KYC over the API: POST /v1/verifications (saveVerification), POST /v1/verifications/{verificationId}/documents (uploadVerificationDocument) and POST /v1/verifications/{verificationId}/submit (submitVerification), under the new scope verifications:write — available to test keys, since a pre-KYC organization holds only test keys. GET /v1/verifications answers the verification's id and version.
    • livemode on contacts: false for a contact a test key created.
    • Every operation in the contract carries a request example (when it takes a JSON body) and a response example.

    Changed

    • A test key records consent on the test contacts it created (consent:write is no longer refused whole for test keys); on a live contact it is still 422 TEST_MODE_UNSUPPORTED. Consent recorded on a test contact never authorizes a live send, and a live write to the contact makes it live, clearing the opt-ins recorded in test mode.
    • A test key's AI_AGENT or EXTERNAL_AGENT call is admitted while the organization's AI-call switch is off (a test call never reaches a carrier); a live one is still 409 AI_CALLS_DISABLED.
    • An error's path (and a message quoting a URL) keeps the query string, with only sensitive values replaced by [redacted].

    Fixed

    • record resume on a call its carrier records answers 409 RECORDING_NOT_CONTROLLABLE, as pause does.
    • call.queued always carries call.status: queued, also for a test call (it read initiating).
  31. SMS outside India, status callbacks, media uploads, scheduled sends, conversation triage, more WhatsApp message types

    2026-11-06

    Added

    • SMS outside India. To any country the platform has enabled (beyond India), POST /v1/messages with channel: "sms" takes free text — type: "text" with text and sms.category (transactional, service_implicit, service_explicit, promotional) — and templates go without their DLT ids. The sender follows the destination's rules: an alphanumeric sender ID, one of your numbers registered as an SMS sender (GET /v1/sms/senders lists it with kind: "number"), or the platform vendor's default where the country allows it (sms.header: null). A promotional SMS abroad gains the country's opt-out line when it has no "STOP". New error codes SMS_SENDER_NOT_ALLOWED and SMS_SENDER_REGISTRATION_REQUIRED (409, with country) — the United States and Canada take registered numbers only — and the same failure codes at send time.
    • Per-request status callbacks. statusCallback: { url, events? } on POST /v1/messages and POST /v1/calls POSTs that message's or call's status events to the URL, signed and retried like webhooks, in addition to your webhook endpoints. The signing secret is created and rotated with POST /v1/status-callback-secret (shown once) and read with GET /v1/status-callback-secret. New error code STATUS_CALLBACK_SECRET_MISSING (409).
    • Media uploads. POST /v1/media (multipart) uploads a file once; send it with media: { id } on a WhatsApp media message, any number of times for 7 days. GET and DELETE /v1/media/{id}.
    • Scheduled sends. sendAt on POST /v1/messages (a minute to 30 days ahead) queues a message for later; consent, billing and WhatsApp's 24-hour window are checked again when it goes. DELETE /v1/messages/{id} cancels it while it waits (failure.code: MESSAGE_CANCELED). Messages carry scheduledAt. New error code MESSAGE_NOT_CANCELABLE (409).
    • Conversation triage. POST /v1/conversations/{id}/assign (to a member by userId or email, or userId: null), …/resolve and …/reopen, with the new scope conversations:write and an optional version check. Conversations carry assignedUserId, assignedAt, resolvedAt and version; conversation.opened gains reason: "api". New error codes CONVERSATION_CHANGED (409) and ASSIGNEE_NOT_A_MEMBER (422).
    • WhatsApp message types. type: "location" (location), type: "contacts" (contacts), and interactive cta_url (a button that opens a link) and flow (a button that opens a WhatsApp Flow).

    Changed

    • sms.header on a message is nullable (an SMS the platform vendor sent from its default sender).
    • SMS_TEMPLATE_REQUIRED is now answered only for free text to an Indian number; a free-text SMS without sms.category is 400 VALIDATION_FAILED.
  32. Voice reach: per-organization destinations, +1 with TCPA

    2026-11-06

    Added

    • GET /v1/settings/destinations (settings:read): the country calling codes your calls may not reach (+1 by default), the ones the platform opened for your organization, the prefixes a leg dialled from a live call (transfer, conference party, BRIDGE number) may go to — each marked needsRate when it lies beyond the home market — and your TCPA acknowledgement with the window +1 calls are held to.
    • Error codes DESTINATION_ACKNOWLEDGEMENT_REQUIRED (422: +1 is opened but your organization has not acknowledged the TCPA statement in the console), DESTINATION_NOT_PRICED (422: a destination opened beyond the default has no rate of its own on your plan) and DESTINATION_CALLING_WINDOW_CLOSED (409, with nextAllowedAt: a +1 call outside 08:00–21:00 in the called party's local time — every time zone of their country — on every path, respectCallingWindow: false included).

    Changed

    • With respectCallingWindow, a call to a number outside India is held to the window in the called party's local time, not your organization's.
  33. Speech gather, agent-first click-to-call

    2026-11-06

    Added

    • gather (a POST /v1/calls/{callId}/actions action and a flow verb) takes input: dtmf (default), speech or dtmf_speech, with language, hints and speechTimeoutSec (speechTimeoutSeconds in a flow). What the caller said arrives as speech: { text, confidence } on call.gather.completed (beside input) and in an answer URL's result. A sensitive gather stays keys-only and never hears speech. A deployment without speech recognition answers 422 CALL_ACTION_UNSUPPORTED (reason: speech_recognition_unavailable).
    • bridge.ringFirst on POST /v1/calls (mode: BRIDGE): contact (default) or agent — click-to-call that rings the seat's own phone first and bridges the contact in once they answer, every dial rule asked of the contact before anything rings. GET /v1/calls/channels says which channels can (agentFirst); a seat with no phone on file is 422 AGENT_PHONE_REQUIRED. Calls read back with bridge.ringFirst.

    Changed

    • A flow gather may take speech only; it used to be refused.
  34. Numbers: read one, order carrier stock, port in, SMS long codes

    2026-11-06

    Added

    • GET /v1/numbers/{numberId} reads one number you hold.
    • Supplier stock you can order: GET /v1/numbers/available names each number's provider, and a carrier's stock is orderable (at your plan's number price) once the platform resells that carrier and your plan prices the number. Order it with POST /v1/numbers { number, provider }: it is held, bought from the carrier when it activates, and charged like any number. Error codes NUMBER_NOT_PRICED, NUMBER_SUPPLIER_ORDER_FAILED (nothing charged; retry or cancel the hold) and NUMBER_SUPPLIER_ORDER_IN_PROGRESS.
    • Port-in: POST /v1/numbers/port-requests (your numbers, their current carrier and a NUMBER_LOA document from your business verification), GET /v1/numbers/port-requests, GET /v1/numbers/port-requests/{id}, POST /v1/numbers/port-requests/{id}/cancel, and the number.port_request.updated event (numbers:read). Codes PORT_LOA_REQUIRED, PORT_NUMBER_ON_PLATFORM, PORT_REQUEST_DUPLICATE, PORT_REQUEST_INVALID_TRANSITION, PORT_NUMBERS_NOT_ASSIGNED, PORT_REQUEST_VERSION_CONFLICT.
    • SMS long codes: POST /v1/numbers/{numberId}/sms-sender makes one of your SMS-capable numbers outside India an SMS sender (NUMBER_SMS_UNSUPPORTED otherwise); GET /v1/numbers?capability=sms lists the candidates.

    Changed

    • POST /v1/numbers takes exactly one of numberId (with version) or number (with provider); numberId and version are no longer required on their own.
  35. Transfer a live call to a queue

    2026-11-06

    Added

    • transfer on POST /v1/calls/{callId}/actions takes to: { queueId }: the caller is handed to one of your call queues and waits there like any queued caller (hold audio, announcements, overflow; voicemail if nobody takes them), ahead of new callers while the queue's transfer boost is on. call.transferred carries transfer.target: queue and transfer.queueId.
    • Error codes QUEUE_NOT_FOUND (404) and QUEUE_CLOSED (409).

    Changed

    • A flow's connect to an agent rings only a seat with the desk grant on the call's team or across the organization (any desk agent for a call no team owns).
  36. Voice security: onward legs are dialled calls; caller IDs are your own

    2026-11-06

    Changed

    • A transfer to a number, a flow connect to a number and an answer-URL connect asking for mode: "release" now all run as bridge: the onward leg is its own call (legRole: "transfer_target"), passes every dial rule (destination policy, verification, balance, the onward-leg allow-list) and is priced and billed as a call. Nothing hands a call to the carrier to dial on its own.
    • A test-key call is held to every rule a live call would be (destination policy, dial admission, recording consent); only billing, the live-call cap and the carrier dial itself are skipped.

    Fixed

    • A caller ID (from on POST /v1/calls, callerId on connect and on a transfer) must be one of the organization's own assigned numbers on that channel, or a number of its own carrier account; any other is refused with 422 CALLER_ID_NOT_OWNED. A number known only from a shared platform account no longer counts.
    • A leg that answers after the platform gave up on it (ring timeout, a cancelled transfer, the caller gone) is hung up instead of joining the call; its seconds are still rated.
    • Twilio and Telnyx: a transfer to a number now connects (the onward leg was hung up on answer).
  37. Test mode: build configuration with a test key; test and live data kept apart

    2026-11-06

    Added

    • A test key creates call flows, voice applications and AI agents of its own: they read livemode: false, run on test calls only, and are the only configuration a test key may change. livemode on every call flow, application and agent.
    • mode (live | test) on webhook endpoints, and as an optional field on POST /v1/webhook-endpoints (a key may name only its own mode). A test endpoint receives the events of test traffic only, a live endpoint live events only.
    • x-live-only in the contract on the operations a test key may never call.

    Changed

    • Security: a test key no longer reads or changes live data. Calls, messages, broadcasts and events are listed and read in the key's own mode (a live key, likewise, no longer sees test traffic); a test key is refused (422 TEST_MODE_UNSUPPORTED) on recordings, contact exports, consent writes, PATCH/DELETE /v1/contacts/:id, an upsert that would change an existing contact, and changes to live call flows, applications and agents. Existing webhook endpoints are live. A live call naming a test flow, application or agent answers its usual not-found code.
  38. AI over the API: transcripts, summaries, AI inbound routes, the AI-call switch

    2026-11-06

    Added

    • GET /v1/calls/{callId}/transcript: the call's transcript, oldest first and paginated — final segments with their speaker (contact, agent, ai, …), offsets and text (spoken phone numbers masked to their last four digits) — with a status (pending, ready, unavailable).
    • GET /v1/calls/{callId}/summary: the AI's summary of a finished call, its disposition, sentiment, confidence and any followUpAt, and the call's outcome (the agent's wrap-up, else the AI's verdict).
    • Events call.transcript.ready (the call and a segment count — never the text) and call.summary.ready (the call and the summary).
    • route.kind: "ai" on PATCH /v1/numbers/{numberId}: an AI agent answers the number's inbound calls itself.
    • GET /v1/settings/calls and PATCH /v1/settings/calls: whether the organization allows AI calls (aiCallsEnabled), switched with a version compare-and-set and audited against the key.
    • Scopes transcripts:read, settings:read, settings:write; error codes SETTINGS_VERSION_CONFLICT and AI_AGENT_IN_USE (archiving an AI agent a number routes to).
  39. Voice: conferences, answering-machine detection, flow failures you can see, more reliable bridges

    2026-11-06

    Added

    • Conferences: POST /v1/conferences opens a live call to more parties; dial numbers in or offer it to an agent (POST /v1/conferences/{conferenceId}/participants), mute or remove a party, end it; events conference.participant.joined, conference.participant.left, conference.ended.
    • machineDetection on POST /v1/calls (detect, detect_and_hangup) on a channel whose machineDetection is true (Plivo, Twilio, Telnyx); 422 MACHINE_DETECTION_UNSUPPORTED elsewhere. The call carries machineDetection: { mode, result, detectedAt }, and the verdict (human, machine, unknown) arrives as the new call.machine_detected event.
    • call.flow.failed ({ call, flow: { runId, code, step, verb, cause } }) when a call's flow fails; the call's failure carries a documented FLOW_* code whatever its status. Every call failure code is listed under Calls → "Call failure codes".
    • /v1/agents takes enum values in either case (openai or OPENAI, auto or AUTO); lower case — what responses and /v1/models answer — is canonical.

    Changed

    • A FLOW or BRIDGE call starts its flow once the contact has answered; on Airtel a connect that is the first verb was refused (the call ended at once) and now dials and bridges.
    • A stored flow, an inline definition or a BRIDGE prompt / whisper / noAnswerMessage that speaks text is refused when it is saved or placed on a deployment with no speech synthesis (CALL_FLOW_INVALID with the places, or 503 TTS_UNAVAILABLE for a bridge), instead of failing once the contact answered.

    Fixed

    • A carrier's terminal status could be lost when another event was written to the call at the same moment, leaving the call in_progress (and holding a live-call slot) for hours; an answered call on a carrier that cannot be polled is now also closed 375 s past its own maxDurationSec.
  40. Two-way SMS, email tracking and inbound email, invoices, balance alerts, key rotation

    2026-11-06

    Added

    • Inbound SMS: a text to one of your SMS-capable numbers arrives as message.received (channel: "sms") on the contact's SMS conversation, with sms.keyword (stop, start, help); STOP opts the contact out of SMS, START lifts their own opt-out for service messages.
    • SMS is routed by destination: Indian numbers through the DLT route, others through the platform's international route.
    • Email open and click tracking, opt-in per sending domain (PATCH /v1/email/domains/{domain} tracking), email.tracking on the message, and the events email.opened and email.clicked.
    • Inbound email: replies to a verified sending domain arrive as message.received (channel: "email") on the thread they answer.
    • GET /v1/invoices, GET /v1/invoices/{period} and GET /v1/invoices/{period}/csv: monthly statements of the prepaid balance.
    • PATCH /v1/balance sets the low-balance threshold (scope billing:manage), and the balance.low event.
    • charge on calls and messages once rated.
    • POST /v1/me/rotate: a key rotates itself, the old secret valid for an overlap.
  41. Voice: call flows, AI agents, click-to-call, live-call actions, numbers and usage

    2026-11-06

    Added

    • POST /v1/calls runs a call four ways (mode): your own stream (EXTERNAL_AGENT, unchanged), a call flow (FLOW — an inline document, a stored flow or a voice application's answer URL), one of your AI agents (AI_AGENT), or connected to a number or an agent's softphone (BRIDGE, the contact dialled first). purpose (SERVICE, TRANSACTIONAL, PROMOTIONAL) on every mode; from takes your own numbers from the inventory first.
    • The call graph on every call: parentCallId, rootCallId, legRole, and purpose, aiAgentId, flow, bridge; GET /v1/calls?include=legs and ?rootCallId=. GET /v1/calls/channels reports flows.
    • POST /v1/calls/{callId}/actions: speak, play, gather (DTMF), send DTMF, hold, resume, mute your own leg, transfer (to a number, a call flow or a voice application), pause or resume the recording, hang up.
    • Events call.inbound, call.held, call.resumed, call.transferred, call.gather.completed.
    • Voice applications (/v1/applications, signing secret shown once, rotate), call flows (/v1/call-flows with versions, validate and publish), AI agents (/v1/agents) and the model catalog (/v1/models).
    • Phone numbers (/v1/numbers: list, search, order, activate, route, label, release), balance, usage and pricing (/v1/balance, /v1/usage, /v1/pricing) and the business verification (/v1/verifications).
    • Scopes numbers:read, numbers:write, applications:read, applications:write, call-flows:read, call-flows:write, agents:read, agents:write, billing:read, verifications:read, and the error codes for each.
    • Legs dialled from a live call (transfers, conferences — new in this release) are calls of their own: GET /v1/calls keeps listing the calls you placed, and lists the legs with include=legs (or rootCallId).

    Changed

    • agent on POST /v1/calls is required with mode: EXTERNAL_AGENT only (it was required always; a relaxation).
  42. Email, SMS, broadcasts and webhook recovery

    2026-10-28

    Added

    • Email through POST /v1/messages (channel: "email"): templates or text, cc/bcc and attachments on transactional email, sending domains (/v1/email/domains) and the suppression list (/v1/email/suppressions), with the message.complained event.
    • SMS through POST /v1/messages (channel: "sms") on India's DLT: SMS templates on /v1/templates (channel: "sms"), DLT headers on GET /v1/sms/senders, the promotional sending window and an sms block on the message.
    • Consent on every channel: GET and PUT /v1/contacts/{contactId}/consent/{channel} for WhatsApp, email and SMS.
    • Broadcasts: POST /v1/broadcasts sends an approved WhatsApp template to an audience by contact ids, tags or custom attributes, now or at a set time, with pause, resume and cancel.
    • PATCH /v1/templates/{templateId} edits a template; email templates on /v1/templates.
    • WhatsApp: reply on any conversation (conversationId, senderId), media by link, reply buttons and lists, quoted replies, reactions, GET /v1/messages/{messageId}/media, and inbound reactions, locations, contact cards and orders.
    • Webhook recovery: GET /v1/events and GET /v1/events/{eventId} read the stored events back for 30 days, and failed deliveries resend in bulk. Events keep being recorded while an endpoint is disabled.
    • GET /v1/contacts?updatedAfter= returns every contact whose record or consent changed since a moment, with its consent on every channel.
    • GET /v1/me/requests lists what a key did in the last seven days.
    • Calls: GET /v1/calls (the list), GET /v1/calls/channels, GET /v1/calls/{callId}/recording and DELETE /v1/calls/{callId}/recording, and a caller ID (from) on POST /v1/calls.
    • The conversation.opened, conversation.resolved, message.media.ready and message.media.failed events.
    • Every error code the API answers with is published as PublicApiErrorCode in the contract, and the standard X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers report the key's budget.

    Changed

    • Subscribing an endpoint to an event needs the scope that reads what the event carries (messages:read for message.*, calls:read for call.*, and so on); webhooks:manage alone no longer reads any event.
    • A 5xx on a write that may already have acted is stored against its Idempotency-Key and replayed (Idempotent-Replayed: true); retrying with the same key returns the same error. Endpoints that are safe to run again are marked x-idempotent-rerun in the contract.
    • The X-RateLimit-*-apiKey headers are deprecated in favour of the unsuffixed ones.
  43. Calls

    2026-10-12

    Added

    • POST /v1/calls places a call and streams its audio to your own agent over a WebSocket; GET /v1/calls/{callId} and POST /v1/calls/{callId}/hangup.
    • The call.queued, call.ringing, call.answered, call.completed, call.failed, call.no_answer, call.busy and call.recording.ready events.
  44. The v1 API

    2026-10-06

    Added

    • API keys as bearer tokens, with per-key scopes, per-key rate limits, Idempotency-Key on every write, cursor pagination and the OpenAPI contract at GET /v1/openapi.json.
    • Contacts, WhatsApp consent, templates, messages and conversations.
    • Signed webhooks for message, consent, template and WhatsApp-account events, with retries and resends.
    • Hosted WhatsApp connect sessions (/v1/whatsapp/connect-sessions) and the WhatsApp account read.
    • Integration keys: provision and look up organizations, mint their keys, suspend, reactivate and erase them.
    • Contact export and erasure.

Node.js SDK

  1. Unreleased

    Unreleased

    Added

    • Call settings. Regenerated from the contract: updateCallSettings takes recordingRequired beside aiCallsEnabled (either or both; neither is required on its own any more), so an organization's "Record every call" policy can be set with a key. A test key may set a test organization's call settings.
  2. 0.4.0

    2026-11-17

    A package build for consumers outside this repository (still not on npm): everything the API's integration work added since 0.3.0 — an integration key acting for the organizations it provisioned, test integration keys and test organizations, one webhook feed for an integration, the integrator paying for its organizations, country-aware verification and SMS registration, India in the sandbox, staff-first click-to-call to your own phones and a call flow's keys. What a client meets at run time is in the API changelog's Unreleased entries.

    Added

    • A call flow's keys. Regenerated from the contract: a flow document takes events: { dtmf: true } (the published flow schema the SDK checks documents against), after which every key the caller presses during the flow is told as the opt-in call.dtmf.
    • Staff-first click-to-call to your own phones. Regenerated from the contract: bridge.to.phoneId on createCall (one of the organization's own phones, /v1/phones, rung first with ringFirst: "agent" or connected to the contact otherwise), and phoneId with target: "phone" on a call's bridge.
    • Country-aware verification and SMS registration. Regenerated from the contract: getVerificationRequirements (GET /v1/verifications/requirements: what a business must give in a country, by profile — in, us, gb, eu, international), identifiers and jurisdiction on saveVerification, business.jurisdiction, identifiers.last4ByKind and requirements.profile / requirements.identifiers on the verification, the tax_registration document type; reviewSandboxVerification (POST /v1/sandbox/verifications/review: test keys decide a test organization's verification); getSmsRegistration (GET /v1/sms/registration: the SMS registration regime of the organization's country and where it stands under it).
    • The integrator pays. Regenerated from the contract: getOrganizationUsage (GET /v1/organizations/{organizationId}/usage, integration keys); billing (payer, spendCap) on createOrganization and updateOrganization and (payer, spendCap, spend) on the organization and on getBalance; breakdown on listUsage and organizationId on its rows; paidFor on invoices; the error codes BILLING_SPEND_CAP_REACHED, BILLING_PAYER_NOT_CONFIGURED and BILLING_PAID_BY_INTEGRATION.
    • One webhook feed for an integration. Regenerated from the contract: listIntegrationWebhookEndpoints, createIntegrationWebhookEndpoint, getIntegrationWebhookEndpoint, updateIntegrationWebhookEndpoint, deleteIntegrationWebhookEndpoint, rotateIntegrationWebhookEndpointSecret, testIntegrationWebhookEndpoint, listIntegrationWebhookDeliveries, resendIntegrationWebhookDeliveries, resendIntegrationWebhookDelivery (/v1/integration/webhook-endpoints) and listIntegrationEvents, getIntegrationEvent (/v1/integration/events), integration keys with the scope organizations:events; externalReference on stored events. TrovacastEventEnvelope gains externalReference (an integration's organization) and integrationId (a webhook.test to an integration's endpoint).
    • Acting for an organization. organization on the client options and on each call's options (null for none) sends Trovacast-Organization: an integration key holding organizations:act then acts for that organization with the scopes the platform delegated to its integration. ACTING_ORGANIZATION_HEADER is exported. Regenerated from the contract: actingFor and integration.delegatedScopes on getMe, livemode on the organization, the scope organizations:act.
    • Regenerated from the contract: updateOrganization (PATCH /v1/organizations/{organizationId}, integration keys) — rename an organization you provisioned, switch its product lines or move its plan, within your integration's terms; entitlements, planId and country on createOrganization; planId and country on the organization; the error codes PRODUCT_LINE_NOT_OFFERED and PLAN_NOT_OFFERED.
  3. 0.3.0

    2026-11-16

    A package build for consumers outside this repository (the package is still not on npm): pnpm pack produces a working, versioned tarball. Everything the API's feat/global-cpaas work added is here; what a client meets at run time is in the API changelog's Unreleased entries.

    Added

    • Regenerated from the contract: reviewSandboxSmsRegistration (POST /v1/sandbox/sms-registrations/review, test keys) — approve or reject a test key's sandbox 10DLC brand, campaign or number assignment; livemode on brands, campaigns, number assignments and sms.registration.updated's registration; media on createSandboxInboundMessage (a test MMS) and reply on its result (the HELP answer).
    • Regenerated from the contract: sandbox on createCall (test keys): the script a test call's other side plays once answered, and machine, its answering-machine verdict.
    • Regenerated from the contract: createSandboxInboundCall (POST /v1/sandbox/inbound-calls, test keys) — a scripted caller rings a sandbox number and its route runs on the platform's real call logic — and the error code SANDBOX_NUMBER_NOT_ROUTED. getCallRecording and deleteCallRecording take a test key, for its own test calls.
    • Regenerated from the contract: a number's livemode (false for a test key's sandbox number — T8: a test key searches, orders, routes and releases fictional sandbox numbers with the same methods).
    • Package builds. pnpm pack builds and smoke-tests dist/ first (prepack), and pnpm pack:check proves the tarball installs offline and imports every entry point from an empty project outside the repository. README: how to depend on a tarball (file:vendor/trovacast-sdk-0.3.0.tgz), ES module and TypeScript resolution notes.
    • Regenerated from the contract: acknowledgeTcpa and withdrawTcpa (POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key — tcpa.statement on the destination settings, and the error code DESTINATION_STATEMENT_OUTDATED.
    • Regenerated from the contract: fallbackFlowId on a voice application (createApplication, updateApplication) — the call flow run when its answer URL is down — and the call timeline's application.fallback entry (applicationId, flowId).
    • Regenerated from the contract: liveCallLimits (perOrganization, perKey) on the call settings — the live-call caps the organization is held to, the deployment's or its own.
    • Regenerated from the contract: port-out — unlockNumberPortOut (answers the account number and the transfer PIN, once), cancelNumberPortOut, listPortOuts, getPortOut — the number.port_out.updated webhook event and the error codes PORT_OUT_NUMBER_NOT_PORTABLE, PORT_OUT_NOT_OPEN, PORT_OUT_INVALID_TRANSITION and PORT_OUT_VERSION_CONFLICT; a port request's rejection and completedNumbers, and previousStatus on number.port_request.updated.
    • Regenerated from the contract: orderNumber orders by place — country with areaCode or prefix, type, sms — and takes reference, metadata and orderId (the order's own id, for good; answered as orderId); a number carries reference and pendingCompliance, updateNumber takes reference and listNumbers filters by it; the number.updated webhook event (a carrier's compliance review settled); the error codes NO_NUMBERS_AVAILABLE, NUMBER_PENDING_COMPLIANCE, NUMBER_ORDER_CONFLICT and NUMBER_ORDER_IN_PROGRESS.
    • Regenerated from the contract: US 10DLC registration — createSmsBrand, listSmsBrands, getSmsBrand, createSmsCampaign, listSmsCampaigns, getSmsCampaign, assignSmsCampaignNumber, listSmsCampaignNumbers, getSmsCampaignNumber, removeSmsCampaignNumber — the sms.registration.updated webhook event, and the error codes SMS_REGISTRATION_REFERENCE_CONFLICT, SMS_REGISTRATION_CLOSED, SMS_NUMBER_NOT_ELIGIBLE and SMS_NUMBER_ALREADY_ASSIGNED.
    • Regenerated from the contract: getSmsSettings and updateSmsSettings (GET/PATCH /v1/settings/sms) — the SMS HELP auto-reply (helpReply).
    • Regenerated from the contract: a message's mediaItems (every file it carries — up to ten on an incoming MMS — each with its index, also on media), and getMessageMedia takes index.
    • Regenerated from the contract: cancelCalls (POST /v1/calls/cancel), notAfter on createCall, onMachine on aiAgent, and the error code CALL_NOT_AFTER_PASSED.
    • Regenerated from the contract: optOut on aiAgent, a number's ai route and a flow's ai verb (the built-in opt-out), and the call.ai.opt_out and opt-in call.dtmf webhook events.
    • Regenerated from the contract: transfer on aiAgent and a number's ai route (a hand-off to a person), and the call.ai.transfer webhook event (WebhookEventCallAiTransfer).
    • Regenerated from the contract: createCall's aiAgent takes firstMessage, instructions, tools and session (the session webhook asked when the conversation starts), and the call takes reference (read back as reference); a number's ai route takes ai; a call flow's ai verb takes firstMessage, instructions, tools, session and onUnavailable; the error code AGENT_TOOL_SECRET_REQUIRED.
    • Regenerated from the contract: replaceNumberRoute (PUT /v1/numbers/{numberId}/route) — a number's whole routing as one call-flow document under your own rising version.
    • Regenerated from the contract: metadata on a number (updateNumber sets it) and the metadata filter on listCalls.
    • Regenerated from the contract: ringing on call.ringing and answeredBy on call.answered: who an inbound call's route rang and who took it; null on an outbound call's own events.
    • Regenerated from the contract: the call.voicemail.ready webhook event (WebhookEventCallVoicemailReady, calls:read and transcripts:read) — a caller's message with its recordingId, key and transcript; and key on call.missed's missed.voicemail.
    • verbs.connect (and a builder's .connect) takes a list of targets in place of to — ConnectTarget: exactly one of number, agent or client, with its own timeoutSeconds, skip windows and reference — rung by strategy (sequential or simultaneous) within totalTimeoutSeconds, with confirm and notice. Regenerated from the contract: notice on record; notice, keys and reply on voicemail; purpose and noticePlayed on a call's recording; recordingId on getCallRecording. Behaviour a client meets is in the API changelog's Unreleased entries.
    • Regenerated from the contract: the call.missed webhook event (calls:read, data WebhookEventCallMissedData) — an inbound caller reached nobody, with the voicemail they left.
    • verbs.hours (and a builder's .hours) takes the schedule itself — an inline schedule (timezone, weekly, holidays, overrides, closures) — as well as a stored schedule's id; the flow validators check it.
    • Regenerated from the contract: the organization's own phones — registerPhone, listPhones, getPhone, removePhone (/v1/phones, settings:read / settings:write) — and the error codes OWN_PHONE_IS_CARRIER_NUMBER and OWN_PHONE_LIMIT_REACHED.
    • Regenerated from the contract: calledPartyTimeZone on createCall — the called party's own zone, which a +1 call's calling window is judged in.

    Fixed

    • The package's own tests typecheck against the contract again (fixtures missing fields the contract had added: a number's ai route options, metadata, reference, pendingCompliance and warnings, a summary's mock, a transcript's gaps and unavailableReason, an application's payloadVersion and fallbackFlowId, the call settings' liveCallLimits).
  4. 0.2.0

    Unreleased

    Added

    • (2026-11-07, Round 13) Regenerated from the contract: deleteAgent resolves to the archived agent with its warnings (PublicAgentDto; it resolved to undefined — the API answered 204); updateCallSettings answers warnings (PublicAgentNumberWarningDto[], while AI calls are off); and on PublicAgentNumberWarningDto, flowId and detail. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 13) Regenerated from the contract: the call.rated webhook event (WebhookEventCallRated, calls:read) — the call with its charge once it is rated. A call is rated after its final call.* event, which carries charge: null. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 12) Regenerated from the contract: rule (STALL_SILENT, STALL_PAST_CEILING, AI_VOICE_NEVER_STARTED, TALK_TIME_UNKNOWN, or null) and reason on a call's charge (PublicCallChargeDto, also the timeline's rated entry); the warning code AI_AGENT_UNAVAILABLE and the reasons AI_CALLS_DISABLED, AGENT_INACTIVE, TEST_AGENT on PublicNumberWarningDto; and warnings (PublicAgentNumberWarningDto: the number's warning plus numberId) on the agent updateAgent answers with. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 12) entry.
    • (2026-11-07, Round 11) Regenerated from the contract: listCallEvents (GET /v1/calls/{callId}/events, calls:read) — a call's timeline, oldest first (schemas PublicCallTimelineEventDto, PublicCallTimelineDataDto, PublicCallTimelinePageDto; page it with client.paginate('listCallEvents', { path: { callId } })); and on the phone number's warnings, the code AI_PROVIDER_UNAVAILABLE beside BILLING_RATE_UNAVAILABLE and the fields agentId, reason and step (PublicNumberWarningStepDto: node, index). Behaviour a client meets — an unrated call is re-rated only within 7 days of its end; the shadow-billing warning's words — is in the API changelog for 2026-11-07.
    • (2026-11-07, Round 10) Regenerated from the contract: warnings on the phone number (schema PublicNumberWarningDto: code: BILLING_RATE_UNAVAILABLE, direction, provider, callType, message — a route your plan does not price, saved all the same), and AI_PROVIDER_UNAVAILABLE among the 422s of createCallAction (a transfer to a call flow whose AI agent cannot speak here; agentId names it). Behaviour a client meets: a refused inbound call is a failed call with a BILLING_* or AI_AGENT_UNAVAILABLE failure.code and fires call.failed; a call with no from presents your number in the contact's country first — see the API changelog for 2026-11-07.
    • (2026-11-06, Round 9) Regenerated from the contract: the AI_PROVIDER_UNAVAILABLE error code (TrovacastErrorCode; an AI_AGENT call whose agent cannot speak here, refused before anything is written — reason, provider, leg), availability: { runnable, reason } on agents, fromSource on calls (where an outbound call's from came from), payloadVersion on voice applications (answer-URL payload 2; payload 1 is deprecated), and unavailableReason and gaps on call transcripts. Behaviour a client meets: a call with no from presents your own number on the channel; a call of the other mode is a 404 on every /v1/calls/{callId}/… route — see the API changelog for 2026-11-06.
    • (2026-11-06, Round 8) Regenerated from the contract: a top-level livemode on every webhook envelope (TrovacastEventEnvelope.livemode, required by parseWebhookEvent / constructWebhookEvent), mock on the call summary and its extraction, speechUnavailable on call.gather.completed's gather, from and numberId on outbound calls, testCalls on the sandbox's concurrency refusal; whole-number fields are typed integer in the bundled contract (a number in TypeScript either way), and each call-flow definition names its document (x-document: CallFlowDocument).
    • (2026-11-06) Regenerated from the contract: listTeams and listMembers (GET /v1/teams, GET /v1/members) with their Team / Member types; livemode on every conversation; to and numberId on every call (an inbound call's from is now the caller, masked); the new teams:read and members:read scopes. Additive.
    • (2026-11-06, Round-7 security fixes) Regenerated from the contract: the dlt.contest.updated and sms.sender_contest.updated event types (a claim's outcome: opened, holder_gone, awarded, dismissed); the error codes DLT_REGISTRATION_CONTESTED, DLT_REGISTRATION_REJECTED, SMS_SENDER_CONTESTED and SMS_SENDER_REJECTED; purpose and callerIds on createVoiceAccessToken (request and grants). The voice client's ready event carries the token's purpose and callerIds.
    • (2026-11-06) Regenerated from the contract: sensitiveGather on every listCallChannels item (whether a sensitive gather can run on the channel's recorded calls), and RECORDING_PAUSE_FAILED in TROVACAST_ERROR_CODES (a sensitive gather whose carrier did not confirm it paused its recording).
    • (2026-11-06) Regenerated from the contract: livemode on the contact.consent.updated, conversation.opened and conversation.resolved event data; warnings on the searchAvailableNumbers answer (NUMBER_SUPPLIER_UNAVAILABLE, per supplier); testOnly on every listModels item and the mock provider for test agents; subaccountId on listUsage (query and answer); the application hang-up side; a subaccount key's mode in either case; named request examples for orderNumber, updateNumber, createSandboxInboundMessage, validateCallFlow, createCallFlowVersion and updateSubaccount. Additive: a switch over hangup.side needs the new member (or its default branch).
    • (2026-11-06) Webhook event types from the contract. WebhookEventDataMap — and so TrovacastEvent's data per type — is generated from the contract's webhook catalog (x-webhooks), as are WEBHOOK_EVENT_TYPES and the new WEBHOOK_EVENT_SCOPES (the scopes each type needs) and OPT_IN_WEBHOOK_EVENT_TYPES; every delivery body is also a named schema (Schemas['WebhookEventMessageSent'], its data Schemas['WebhookEventMessageSentData']). The readable aliases (CallTransferInfo, ConsentUpdateSource, …) are kept, now derived from it.
    • (2026-11-06) TrovacastApiError.docUrl: where the error's code is documented on the developer site (null for an SDK code or an answer without one).
    • (2026-11-06) Every operation's doc comment describes it and says who may call it.
    • (2026-11-06) **@trovacast/sdk/voice** — client voice for your own app: VoiceDevice connects with a client-voice access token (createVoiceAccessToken, new), places calls (device.call), is rung (incoming), and each VoiceCall answers, rejects, mutes, holds, sends DTMF and hangs up; browserAudio() is the default audio in a browser. No dependencies. The contract gains the voice:client scope, number routes of kind client (route.identity) and flows' connect.to.client.
    • (2026-11-06) Sender registration, MMS, PDF statements. DLT registrations (listDltEntities, createDltEntity, getDltEntity, updateDltEntity, deleteDltEntity, createDltHeader, getDltHeader, deleteDltHeader), writable SMS senders (createSmsSender, getSmsSender, deleteSmsSender) and WhatsApp senders (listWhatsAppSenders, getWhatsAppSender); the dlt.entity.updated, dlt.header.updated and sms.sender.updated events; type: "mms" on SMS sends; the codes DLT_ALREADY_REGISTERED, DLT_REGISTRATION_CLAIMED, DLT_REGISTRATION_LOCKED, DLT_VERSION_CONFLICT, SMS_SENDER_ALREADY_REGISTERED, SMS_SENDER_CLAIMED and SMS_MMS_UNSUPPORTED; subaccounts' suspendedBy: "with_parent". Statement PDFs are fetched outside the typed client (/v1/invoices/{period}.pdf).
    • (2026-11-06) The error-code list names the codes the API already answered with (AUDIENCE_EMPTY, AUDIENCE_TOO_LARGE, BROADCAST_INVALID_STATE, ORGANIZATION_NOT_ACTIVE, VERIFICATION_INCOMPLETE, META_UNAVAILABLE, READ_RECEIPT_NOT_CONFIRMED, UPLOAD_SESSION_REFUSED, MEDIA_REDIRECT_REFUSED, WHATSAPP_SANDBOX_*) and MODEL_UNAVAILABLE; models carry available; the call-flow schemas (CallFlowDocument, CallFlowAnswerDocument, CallFlowVerb*) are typed; request bodies take mode, purpose, consent source and template category in either case.
    • (2026-11-06) Call-flow builders. callFlow() and answer() (also exported by @trovacast/sdk/flows) build stored flows and answer documents with one chained method per verb, options typed from the contract and branches typed by document (node() / url()); toJSON() validates and throws CallFlowValidationError with every issue's path. validateCallFlow / validateAnswerDocument check any document against the contract's CallFlow* JSON Schemas (CALL_FLOW_SCHEMAS, generated) and the API's rules for branches, goto, redirect, sensitive gathers and size; verbs.* builds one verb.
    • Verify (2026-11-06): createVerify, getVerify, checkVerify, resendVerify (friendly types Verify, VerifyCheck); events verify.approved, verify.expired and the opt-in call.transcript.segment; scopes verify:read, verify:write; error codes VERIFY_*. The live transcript stream (GET /v1/calls/{callId}/transcript/stream, Server-Sent Events) is not a typed method — read it with any SSE client.
    • Lookup and call queues (2026-11-06): lookupPhoneNumber (validity, formats, country, type and India's NCPR status — friendly type PhoneNumberLookup); listQueues, createQueue, getQueue, updateQueue, setQueueMembers, deleteQueue (friendly types Queue, QueueMember); scopes lookup:read, queues:read, queues:write; error codes PHONE_NUMBER_MALFORMED, TEAM_NOT_FOUND, QUEUE_VERSION_CONFLICT, QUEUE_NAME_TAKEN, QUEUE_IN_USE.
    • (2026-11-06) The call summary's outcome.code / outcome.label: the organization's own wrap-up code the agent filed, as they picked it (null for a standard outcome and the AI's verdict).
    • Messaging sandbox (2026-11-06): listSandboxEmails, getSandboxEmail, createSandboxInboundMessage; warnings on every message, livemode on every template; the SANDBOX_TEST_KEY_REQUIRED error code.
    • (2026-11-06) Subaccounts: createSubaccount, listSubaccounts, getSubaccount, updateSubaccount, getSubaccountUsage, createSubaccountTransfer, createSubaccountApiKey, revokeSubaccountApiKey, the subaccounts:read / subaccounts:write scopes; top-ups createTopUp / getTopUp; statement lines transfer_in / transfer_out; the new error codes.
    • Voice reach and numbers (2026-11-06): getDestinationSettings; gather input (dtmf | speech | dtmf_speech) with language, hints and speechTimeoutSec, and speech: { text, confidence } on call.gather.completed; bridge.ringFirst (agent-first click-to-call); getNumber, ordering supplier stock (number + provider), registerNumberSmsSender, the port-in operations (createPortRequest, listPortRequests, getPortRequest, cancelPortRequest) and the number.port_request.updated event; the new error codes.
    • **trovacast listen** (the package's bin; npx @trovacast/sdk listen --forward-to <url>): forwards the organization's webhook events to a local handler by polling GET /v1/events, oldest first and once each, re-signed with a local whsec_listen_… secret. @trovacast/sdk/listen exports the same forwarder (Listener, parseListenArgs).
    • A release workflow and a release check, which refuses to publish while the package is private or unlicensed or its versions disagree.
    • transfer action to.queueId (a transfer to a call queue), the call.transferred transfer.queueId field, and the error codes QUEUE_NOT_FOUND and QUEUE_CLOSED.
    • (2026-11-06) AI agents that do real work: createAgent / updateAgent take firstMessage, firstSpeaker, language, endCallPhrases, maxTurns, tools and extraction; rotateAgentToolSecret; the call summary's extraction. Verify a tool call with verifyWebhookSignature and the agent's tool-signing secret (the same scheme as a webhook).
    • (2026-11-06) KYC over the API: saveVerification, uploadVerificationDocument (send a FormData body) and submitVerification, the verifications:write scope, and id / version on the verification; livemode on contacts.
    • README: how to run trovacast listen before the package is on npm.

    Changed

    • (2026-11-07, Round 13) PublicAgentNumberWarningDto.provider (the warnings updateAgent, deleteAgent and updateCallSettings answer) is PublicCallProvider | null: a key without numbers:read is told only numberId, code and reason (detail: false), the rest null. Check detail (or provider !== null) before reading the number's channel, agent, step or flow.
    • (2026-11-06, Round-7 security fixes) The voice client sends no call policy. PlaceCallOptions no longer has respectCallingWindow or purpose: a client call always keeps to the organization's calling window, and its purpose is bound into the access token by your server (purpose on createVoiceAccessToken). An older client that still sends either is refused VALIDATION_FAILED. from must be one of the token's callerIds when it binds any (VOICE_CALLER_ID_NOT_ALLOWED). A new connection may be refused service_unavailable (retry with backoff).
    • (2026-11-06) Event data types follow the contract, which corrects two that had drifted from what the API sends: CallTransferInfo.target may be 'queue' (with queueId), and ConversationOpenedReason may be 'api'. A switch over either needs the new member (or its default branch).
    • An error the API replayed from its idempotency store is final. The API now stores a 5xx outcome against the Idempotency-Key when the endpoint may already have acted (every write except POST /v1/messages, POST /v1/messages/{messageId}/read, DELETE /v1/contacts/{contactId} and DELETE /v1/organizations/{organizationId}, which are safe to re-run, and except the errors that provably changed nothing — 503 MESSAGING_TRANSPORT, 503 WHATSAPP_CONNECT_UNAVAILABLE) and answers every retry with that key with the same error and Idempotent-Replayed: true. The client no longer retries such an error — it is thrown after the attempt that received it, with retryable: false — because a retry with the same key can only receive it again. A plain 5xx (not replayed) is still retried with the same key, as before. What to do: when error.idempotentReplayed is true, read the resource to find out whether the first attempt took effect, and send the write again with a new key only if it did not.
    • Each webhook event needs the scope that reads what it embeds. With an API key, createWebhookEndpoint, and updateWebhookEndpoint when it changes the URL or the events, answer 403 API_KEY_SCOPE_MISSING unless the key holds, for every event the endpoint will carry: messages:read for message.* (message.received also contacts:read), contacts:read for contact.consent.updated, templates:read for template.updated, whatsapp:read for whatsapp.account.updated, calls:read for call.* (call.recording.ready also recordings:read, as before). listEvents/getEvent withhold the events the key cannot read the same way (a type filter on one is a 403). webhooks:manage alone no longer reads any event. Endpoints already subscribed keep receiving; the rule applies from their next URL or events change. What to do: mint the key with the read scopes of the events it manages.
    • **message.sms.senderId is now message.sms.header** (the DLT header text). The request's senderId stays the sender's id; list them with listSmsSenders. SMS shipped unreleased, so no integration should depend on the old name.
    • **The external-agent start frame's to is an object** — { phone, last4 }; phone is the full number only when the call was placed with to.phone, null for a call placed by contactId.
    • A webhook URL must use port 443, 80 or an ordinary high port — not a privileged port or one of a well-known non-HTTP service (400 WEBHOOK_URL_INVALID, reason: "PORT_NOT_ALLOWED"); an organization may set at most 20 endpoint URLs an hour (429 RATE_LIMITED); and changing an endpoint's URL or re-enabling it no longer resets its circuit breaker (only a delivery that succeeds does).

    Added

    • Messaging. uploadMedia (send a FormData with the file in file; the client sends it as multipart/form-data), getMedia, deleteMedia; cancelMessage for a message scheduled with sendAt; assignConversation, resolveConversation, reopenConversation; getStatusCallbackSecret, rotateStatusCallbackSecret and statusCallback on createMessage / createCall; free-text SMS outside India (sms.category), WhatsApp location, contacts and interactive cta_url / flow. The new error codes are in TROVACAST_ERROR_CODES.
    • Conferences (voice). createConference, getConference, addConferenceParticipant, updateConferenceParticipant, removeConferenceParticipant, endConference, the Conference, ConferenceParticipant and ConferenceParticipantAdded types, and the conference.participant.joined|left and conference.ended events.
    • Answering-machine detection and failed flows (voice). createCall takes machineDetection ('detect', 'detect_and_hangup'); the call carries machineDetection { mode, result, detectedAt }; the events call.machine_detected and call.flow.failed (with the exported CallFlowFailure) are in WEBHOOK_EVENT_TYPES and narrow by type; MACHINE_DETECTION_UNSUPPORTED is in TROVACAST_ERROR_CODES. Agent enums accept either case ('openai' or 'OPENAI').
    • Voice: createCall takes mode FLOW (a call flow, inline or stored, or a voice application's answer URL), AI_AGENT (aiAgent.agentId) and BRIDGE (click-to-call, the contact dialled first) beside EXTERNAL_AGENT, and purpose; calls carry parentCallId, rootCallId, legRole, aiAgentId, flow and bridge, and listCalls takes include: 'legs' and rootCallId. createCallAction (speak, play, gather, send_dtmf, hold, resume, mute, unmute, transfer, record, hangup); the applications (createApplication, rotateApplicationSecret, …), call flows (createCallFlow, validateCallFlow, createCallFlowVersion, publishCallFlowVersion, archiveCallFlow, …), agents (createAgent, …) and listModels operations; the events call.inbound, call.held, call.resumed, call.transferred and call.gather.completed (CallTransferInfo, CallGatherResult); friendly types CallAction, CallActionResult, Application, ApplicationWithSecret, CallFlow, CallFlowVersion, CallFlowValidation, Agent, AgentWithInstructions, Model; and the voice error codes.
    • Numbers, billing and business verification: listNumbers, searchAvailableNumbers (inventory priced, supplier stock null-priced and not orderable), orderNumber (a number_order: activated, or held with the refusal it met in pending), activateNumber, updateNumber (label, inbound route, voice DLT header — one version), releaseNumber; getBalance, listUsage (per UTC day × channel × destination, at most 90 days), getPricing (the plan's cells as stored) and getVerification (identifiers to their last four). Friendly types PhoneNumber, AvailableNumber, NumberOrder, Balance, Usage, UsageRow, Pricing, Verification; error codes NUMBER_VERSION_CONFLICT and NUMBER_NOT_ASSIGNED.
    • AI over the API: getCallTranscript (paginated: paginate walks its segments), getCallSummary, getCallSettings and updateCallSettings (the AI-call switch, a version compare-and-set); updateNumber takes route.kind: 'ai'; the events call.transcript.ready (CallTranscriptReady: a count, never the text) and call.summary.ready; friendly types CallTranscript, TranscriptSegment, CallSummary, CallSettings; error codes SETTINGS_VERSION_CONFLICT and AI_AGENT_IN_USE. New scopes transcripts:read, settings:read, settings:write.
    • Regenerated from the v1 contract as of this release: email and SMS on createMessage (channel, to.email, email, sms), WhatsApp media, interactive messages, replies (conversationId, replyToMessageId) and getMessageMedia; per-channel consent (getChannelConsent, setChannelConsent); email domains and suppressions; listCalls, listCallChannels and getCallRecording; listEvents, getEvent, resendWebhookDeliveries and listApiKeyRequests; and, later in the round, updateTemplate (PATCH /v1/templates/{templateId}), email templates, cc/bcc/attachments on email, the broadcasts operations, reactions, SMS senders, deleteCallRecording, caller-ID from on createCall, the integration data-subject operations, and GET /v1/contacts?updatedAfter=.
    • The message.complained event, start_keyword as a consent source, and contact.consent.updated typed as the channel consent (PublicChannelConsentDto, consent.object naming the channel).
    • The conversation.opened (with its ConversationOpenedReason: first_message, customer_reply, agent) and conversation.resolved events, each carrying the PublicConversationDto.
    • A message's reaction, location, contacts and order blocks (inbound reactions, shared locations, shared contact cards and catalog orders; a reaction's target is its context).
    • A message's media block (kind, mimeType, fileName, sizeBytes, status — pending, ready, failed, rejected — and failureCode; never a link), and the message.media.ready / message.media.failed events that say when a received file settled.
    • Sending a WhatsApp reaction (type: "reaction"), filtering listMessages by metadata (key:value, repeatable) and listConversations by channel; createMessage 404s name what is missing (CONTACT_NOT_FOUND, TEMPLATE_NOT_FOUND, …) and its refusals are typed (PublicSendRefusalDto).
    • A WhatsApp message that failed as SUBMISSION_UNKNOWN can later turn sent / delivered / read when Meta's statuses show it was accepted (its message.sent follows the message.failed).
    • TrovacastApiError.idempotentReplayed — true when the error came from the API's idempotency store.
    • listContacts({ updatedAfter }) — the contacts reconciliation read: every contact whose record or consent changed since, oldest change first, with changedAt and its consent on every channel, so an opt-out a webhook missed is found by one read.
    • Events keep being recorded for a webhook endpoint while it is disabled (by its owner, or by the platform after three days of failures), so listEvents and a bulk resend catch up on an outage of any length up to the 30-day retention.
    • The API's error codes by name: TROVACAST_ERROR_CODES (the contract's new PublicApiErrorCode enum), KnownTrovacastErrorCode, TROVACAST_ERROR_CODE_FAMILIES (META_) and isKnownErrorCode(code). TrovacastApiError.code is now typed TrovacastErrorCode — a known API code, an SDK code (SdkErrorCode) or any other string — so known codes autocomplete while a code the API adds later still type-checks. Not a narrowing: every string is still accepted, and reading code as a string works as before.
    • ApiResponse.rateLimit ({ limit, remaining, resetSeconds } or null), read from the standard X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers the API now sends, and the rateLimitOf(headers) helper and RateLimitInfo type behind it. The suffixed X-RateLimit-*-apiKey headers are deprecated by the API and not read.
    • Package metadata for publishing (repository, homepage, bugs, keywords, publishConfig), this changelog in the published files, and a prepublishOnly build. The package stays private until it is released (see CONTRIBUTING.md → Releasing).
  5. 0.1.0

    2026-10-06

    Added

    • The first version, consumed inside the monorepo (workspace:*): one typed method per operation of the v1 contract, withResponse, paginate and pages; an Idempotency-Key on every write; retries with jittered exponential backoff that honour Retry-After; TrovacastApiError; webhook signature verification (verifyWebhookSignature, constructWebhookEvent) and typed events.

Python SDK

  1. 0.1.0

    Unreleased

    Added

    • Call settings. Regenerated from the contract: update_call_settings takes recordingRequired beside aiCallsEnabled (either or both), the organization's "Record every call" policy. A test key may set a test organization's call settings.
    • A call flow's keys. Regenerated from the contract: a flow document takes events: { dtmf: true }, after which every key the caller presses during the flow is told as the opt-in call.dtmf.
    • Staff-first click-to-call to your own phones. Regenerated from the contract: bridge.to.phoneId on create_call (one of the organization's own phones, /v1/phones, rung first with ringFirst: "agent" or connected to the contact otherwise), and phoneId with target: "phone" on a call's bridge.
    • Country-aware verification and SMS registration. Regenerated from the contract: get_verification_requirements (what a business must give in a country, by profile — in, us, gb, eu, international), identifiers and jurisdiction on save_verification, business.jurisdiction, identifiers.last4ByKind and requirements.profile / requirements.identifiers on the verification, the tax_registration document type; review_sandbox_verification (test keys decide a test organization's verification); get_sms_registration (the SMS registration regime of the organization's country and where it stands under it).
    • The integrator pays. Regenerated from the contract: get_organization_usage; billing on create_organization, update_organization, the organization and the balance; breakdown on list_usage; paidFor on invoices; the error codes BILLING_SPEND_CAP_REACHED, BILLING_PAYER_NOT_CONFIGURED and BILLING_PAID_BY_INTEGRATION.
    • One webhook feed for an integration. Regenerated from the contract: list_integration_webhook_endpoints, create_integration_webhook_endpoint and the rest of /v1/integration/webhook-endpoints, and list_integration_events / get_integration_event (/v1/integration/events) — integration keys with the scope organizations:events; externalReference on stored events. The WebhookEvent typed dict gains externalReference and integrationId (both optional).
    • Acting for an organization. organization= on Trovacast and AsyncTrovacast sends Trovacast-Organization on every request: an integration key holding organizations:act then acts for that organization with the scopes the platform delegated to its integration. ACTING_ORGANIZATION_HEADER is exported. Regenerated from the contract: actingFor and integration.delegatedScopes on get_me, livemode on the organization, the scope organizations:act.
    • Regenerated from the contract: update_organization (PATCH /v1/organizations/{organizationId}, integration keys) — rename an organization you provisioned, switch its product lines or move its plan, within your integration's terms; entitlements, planId and country on create_organization's body; planId and country on the organization; the error codes PRODUCT_LINE_NOT_OFFERED and PLAN_NOT_OFFERED.
    • Regenerated from the contract: review_sandbox_sms_registration (POST /v1/sandbox/sms-registrations/review, test keys) — approve or reject a test key's sandbox 10DLC brand, campaign or number assignment; livemode on brands, campaigns, number assignments and sms.registration.updated's registration; media on create_sandbox_inbound_message (a test MMS) and reply on its result.
    • Regenerated from the contract: sandbox on create_call (test keys): the script a test call's other side plays once answered, and machine, its answering-machine verdict.
    • Regenerated from the contract: create_sandbox_inbound_call (POST /v1/sandbox/inbound-calls, test keys) — a scripted caller rings a sandbox number and its route runs on the platform's real call logic — and the error code SANDBOX_NUMBER_NOT_ROUTED. get_call_recording and delete_call_recording take a test key, for its own test calls.
    • Regenerated from the contract: a number's livemode (false for a test key's sandbox number — T8: a test key searches, orders, routes and releases fictional sandbox numbers with the same methods).
    • Regenerated from the contract: acknowledge_tcpa and withdraw_tcpa (POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key — tcpa.statement on the destination settings, and the error code DESTINATION_STATEMENT_OUTDATED.
    • Regenerated from the contract: fallbackFlowId on a voice application (create_application, update_application) — the call flow run when its answer URL is down — and the call timeline's application.fallback entry (applicationId, flowId).
    • Regenerated from the contract: liveCallLimits (perOrganization, perKey) on the call settings — the live-call caps the organization is held to, the deployment's or its own.
    • Regenerated from the contract: port-out — unlock_number_port_out (answers the account number and the transfer PIN, once), cancel_number_port_out, list_port_outs, get_port_out — the number.port_out.updated webhook event and the error codes PORT_OUT_NUMBER_NOT_PORTABLE, PORT_OUT_NOT_OPEN, PORT_OUT_INVALID_TRANSITION and PORT_OUT_VERSION_CONFLICT; a port request's rejection and completedNumbers, and previousStatus on number.port_request.updated.
    • Regenerated from the contract: order_number orders by place — country with areaCode or prefix, type, sms — and takes reference, metadata and orderId (the order's own id, for good; answered as orderId); a number carries reference and pendingCompliance, update_number takes reference and list_numbers filters by it; the number.updated webhook event (a carrier's compliance review settled); the error codes NO_NUMBERS_AVAILABLE, NUMBER_PENDING_COMPLIANCE, NUMBER_ORDER_CONFLICT and NUMBER_ORDER_IN_PROGRESS.
    • Regenerated from the contract: US 10DLC registration — create_sms_brand, list_sms_brands, get_sms_brand, create_sms_campaign, list_sms_campaigns, get_sms_campaign, assign_sms_campaign_number, list_sms_campaign_numbers, get_sms_campaign_number, remove_sms_campaign_number — and the sms.registration.updated webhook event.
    • Regenerated from the contract: get_sms_settings and update_sms_settings (GET/PATCH /v1/settings/sms) — the SMS HELP auto-reply (helpReply).
    • Regenerated from the contract: a message's mediaItems (every file it carries — up to ten on an incoming MMS — each with its index, also on media), and get_message_media takes index.
    • Regenerated from the contract: cancel_calls (POST /v1/calls/cancel), notAfter on create_call, onMachine on aiAgent, and the error code CALL_NOT_AFTER_PASSED.
    • flows.ai takes opt_out. Regenerated from the contract: optOut on aiAgent and a number's ai route, and the call.ai.opt_out and opt-in call.dtmf webhook events.
    • Regenerated from the contract: transfer on aiAgent and a number's ai route (a hand-off to a person), and the call.ai.transfer webhook event.
    • flows.ai takes first_message, instructions, tools, session and on_unavailable: a step's own configuration and the session webhook. Regenerated from the contract: create_call's aiAgent takes firstMessage, instructions, tools and session, and the call takes reference (read back as reference); a number's ai route takes ai; the error code AGENT_TOOL_SECRET_REQUIRED.
    • Regenerated from the contract: replace_number_route (PUT /v1/numbers/{numberId}/route) — a number's whole routing as one call-flow document under your own rising version.
    • Regenerated from the contract: metadata on a number (update_number sets it) and the metadata filter on list_calls.
    • Regenerated from the contract: ringing on call.ringing and answeredBy on call.answered: who an inbound call's route rang and who took it; None on an outbound call's own events.
    • Regenerated from the contract: the call.voicemail.ready webhook event (calls:read, transcripts:read) — a caller's message with its recordingId, key and transcript; and key on call.missed's missed.voicemail.
    • flows.connect takes targets (several parties, each exactly one of number, agent or client with its own timeoutSeconds, skip windows and reference), strategy, total_timeout_seconds, confirm and notice; to is optional (exactly one of the two). flows.record takes notice; flows.voicemail takes notice, keys and reply. A call's recording carries purpose and noticePlayed, and get_call_recording takes recording_id. Behaviour a client meets is in the API changelog's Unreleased entries.
    • (2026-11-07, Round 13) Regenerated from the contract: delete_agent returns the archived agent with its warnings (Agent; it returned None — the API answered 204); update_call_settings answers warnings (AgentNumberWarning, while AI calls are off); and on AgentNumberWarning, flowId and detail, with provider now None for a key without numbers:read (only numberId, code and reason are told then, detail: False). Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 13) Regenerated from the contract: the call.rated webhook event (WebhookEventCallRated, calls:read) — the call with its charge once it is rated. A call is rated after its final call.* event, which carries charge: None. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 12) Regenerated from the contract: rule (STALL_SILENT, STALL_PAST_CEILING, AI_VOICE_NEVER_STARTED, TALK_TIME_UNKNOWN, or None) and reason on a call's charge (CallCharge, also the timeline's rated entry); the warning code AI_AGENT_UNAVAILABLE and the reasons AI_CALLS_DISABLED, AGENT_INACTIVE, TEST_AGENT on NumberWarning; and warnings (AgentNumberWarning: the number's warning plus numberId) on the agent update_agent returns. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 12) entry.
    • (2026-11-07, Round 11) Regenerated from the contract: list_call_events (GET /v1/calls/{callId}/events, calls:read) — a call's timeline, oldest first (CallTimelineEvent, CallTimelineData, CallTimelinePage; paginate pages it like every list); and on the phone number's warnings (NumberWarning), the code AI_PROVIDER_UNAVAILABLE beside BILLING_RATE_UNAVAILABLE and the fields agentId, reason and step (NumberWarningStep: node, index). Behaviour a client meets is in the API changelog for 2026-11-07.
    • (2026-11-07, Round 10) Regenerated from the contract: warnings on the phone number (NumberWarning: code: BILLING_RATE_UNAVAILABLE, direction, provider, callType, message — a route your plan does not price, saved all the same), and AI_PROVIDER_UNAVAILABLE among the 422s of create_call_action (a transfer to a call flow whose AI agent cannot speak here). Behaviour a client meets is in the API changelog for 2026-11-07.
    • (2026-11-06, Round 9) Regenerated from the contract: the AI_PROVIDER_UNAVAILABLE error code, availability on agents, fromSource on calls, payloadVersion on voice applications (answer-URL payload 2; payload 1 is deprecated), and unavailableReason and gaps on call transcripts — see the API changelog for 2026-11-06 for the behaviour behind them.
    • (2026-11-06, Round 8) Regenerated from the contract: a top-level livemode on every webhook envelope (WebhookEvent["livemode"], required by parse_webhook_event), mock on the call summary and its extraction, speechUnavailable on call.gather.completed, from and numberId on outbound calls; whole-number fields are int in the generated types (limits, durations, counts, versions, minor units).
    • (2026-11-06) Regenerated from the contract: list_teams and list_members (GET /v1/teams, GET /v1/members), livemode on every conversation, to and numberId on every call (an inbound call's from is now the caller, masked), and the teams:read / members:read scopes.
    • (2026-11-06) Regenerated from the contract: sensitiveGather on every call channel (whether a sensitive gather can run on the channel's recorded calls), and the RECORDING_PAUSE_FAILED error code.
    • (2026-11-06) Regenerated from the contract: livemode on the contact.consent.updated, conversation.opened and conversation.resolved event data, warnings on the number search, testOnly on models (and the test-mode mock provider), subaccount_id on list_usage, the application hang-up side, and the new named request examples.
    • (2026-11-06) TrovacastApiError.doc_url: where the error's code is documented on the developer site (None for an SDK code or an answer without one).
    • (2026-11-06) WEBHOOK_EVENT_SCOPES (the scopes each event type needs) and OPT_IN_WEBHOOK_EVENT_TYPES, from the contract's webhook catalog (x-webhooks); every delivery body is a TypedDict in trovacast.types (WebhookEventMessageSent, its data WebhookEventMessageSentData, …).
    • (2026-11-06) Every method's docstring describes the operation and says who may call it.
    • (2026-11-06) create_voice_access_token (POST /v1/voice/access-tokens, scope voice:client): mint a client-voice token for your own app, which places and answers calls with @trovacast/sdk/voice (the browser client is JavaScript only). Number routes take kind: "client" with identity; flows' connect takes to: {"client": "<identity>"}.
    • (2026-11-06) Sender registration, MMS, PDF statements. DLT registrations (list_dlt_entities, create_dlt_entity, get_dlt_entity, update_dlt_entity, delete_dlt_entity, create_dlt_header, get_dlt_header, delete_dlt_header), writable SMS senders (create_sms_sender, get_sms_sender, delete_sms_sender) and WhatsApp senders (list_whatsapp_senders, get_whatsapp_sender); the dlt.entity.updated, dlt.header.updated and sms.sender.updated events; type: "mms" on SMS sends; the codes DLT_ALREADY_REGISTERED, DLT_REGISTRATION_CLAIMED, DLT_REGISTRATION_LOCKED, DLT_VERSION_CONFLICT, SMS_SENDER_ALREADY_REGISTERED, SMS_SENDER_CLAIMED and SMS_MMS_UNSUPPORTED; subaccounts' suspendedBy: "with_parent". Statement PDFs are fetched outside the typed client — any HTTP client with the key (/v1/invoices/{period}.pdf).
    • (2026-11-06) The error-code list names the codes the API already answered with (AUDIENCE_EMPTY, AUDIENCE_TOO_LARGE, BROADCAST_INVALID_STATE, ORGANIZATION_NOT_ACTIVE, VERIFICATION_INCOMPLETE, META_UNAVAILABLE, READ_RECEIPT_NOT_CONFIRMED, UPLOAD_SESSION_REFUSED, MEDIA_REDIRECT_REFUSED, WHATSAPP_SANDBOX_*) and MODEL_UNAVAILABLE; models carry available; the call-flow schemas (CallFlowDocument, CallFlowAnswerDocument, CallFlowVerb*) are TypedDicts; request bodies take mode, purpose, consent source and template category in either case.
    • (2026-11-06) Call-flow builders. trovacast.flows: CallFlowBuilder and AnswerBuilder build stored flows and answer documents with one chained method per verb (snake_case keyword arguments for the API's camelCase fields; set_ and switch_), a function per verb, and the branch helpers node() / url(); to_dict() validates and raises CallFlowValidationError (a ValueError) with every issue's path. validate_call_flow / validate_answer_document check any document against the contract's CallFlow* JSON Schemas (CALL_FLOW_SCHEMAS, generated) and the API's rules for branches, goto, redirect, sensitive gathers and size.
    • (2026-11-06) Verify. create_verify, get_verify, check_verify, resend_verify; events verify.approved, verify.expired and the opt-in call.transcript.segment; error codes VERIFY_*. The live transcript stream (Server-Sent Events) is not a typed method.
    • (2026-11-06) Lookup and call queues. lookup_phone_number (validity, formats, country, type and India's NCPR status); list_queues, create_queue, get_queue, update_queue, set_queue_members, delete_queue; error codes PHONE_NUMBER_MALFORMED, TEAM_NOT_FOUND, QUEUE_VERSION_CONFLICT, QUEUE_NAME_TAKEN, QUEUE_IN_USE.
    • (2026-11-06) The call summary's outcome.code / outcome.label: the organization's own wrap-up code the agent filed, as they picked it (None for a standard outcome and the AI's verdict).
    • (2026-11-06) Messaging sandbox. list_sandbox_emails, get_sandbox_email, create_sandbox_inbound_message; warnings on every message, livemode on every template; SANDBOX_TEST_KEY_REQUIRED.
    • (2026-11-06) Subaccounts and top-ups. create_subaccount, list_subaccounts, get_subaccount, update_subaccount, get_subaccount_usage, create_subaccount_transfer, create_subaccount_api_key, revoke_subaccount_api_key, create_top_up and get_top_up; the subaccounts:read / subaccounts:write scopes, the transfer_in / transfer_out statement lines and the new error codes.
    • (2026-11-06) AI agents that do real work. create_agent / update_agent take firstMessage, firstSpeaker, language, endCallPhrases, maxTurns, tools and extraction; rotate_agent_tool_secret; the call summary's extraction. A tool call is signed like a webhook: verify it with trovacast.webhooks.verify_webhook_signature and the agent's tool-signing secret.
    • (2026-11-06) KYC over the API. save_verification, upload_verification_document and submit_verification, the verifications:write scope, and id / version on the verification; livemode on contacts.
    • Messaging. upload_media(body=FileUpload(content, file_name, content_type)) — the exported FileUpload is sent as multipart/form-data — get_media, delete_media; cancel_message for a message scheduled with sendAt; assign_conversation, resolve_conversation, reopen_conversation; get_status_callback_secret, rotate_status_callback_secret and statusCallback on create_message / create_call; free-text SMS outside India, WhatsApp location, contacts and interactive cta_url / flow. The new error codes are in TROVACAST_ERROR_CODES.
    • Voice reach and numbers (2026-11-06): get_destination_settings; gather input (dtmf | speech | dtmf_speech) with language, hints and speechTimeoutSec, and speech: { text, confidence } on call.gather.completed; bridge.ringFirst (agent-first click-to-call); get_number, ordering supplier stock (number + provider), register_number_sms_sender, the port-in operations (create_port_request, list_port_requests, get_port_request, cancel_port_request) and the number.port_request.updated event; the new error codes.
    • Conferences (voice). create_conference, get_conference, add_conference_participant, update_conference_participant, remove_conference_participant, end_conference, the Conference types, and the conference.* events.
    • Answering-machine detection and failed flows (voice). create_call takes machineDetection ("detect", "detect_and_hangup"); the call carries machineDetection; call.machine_detected and call.flow.failed are in WEBHOOK_EVENT_TYPES; MACHINE_DETECTION_UNSUPPORTED is in TROVACAST_ERROR_CODES.
    • The first version, generated from the v1 contract the Node SDK 0.2.0 is built from (112 operations: numbers, balance, usage, pricing and verification — list_numbers, search_available_numbers, order_number, activate_number, update_number, release_number, get_balance, list_usage (from_=), get_pricing, get_verification — and voice: create_call with FLOW, AI_AGENT and BRIDGE, create_call_action, the applications, call-flows, agents and list_models methods — and AI over the API: get_call_transcript (walk it with paginate), get_call_summary, get_call_settings, update_call_settings, route.kind: "ai" on update_number, and the call.transcript.ready / call.summary.ready events): Trovacast and AsyncTrovacast, one keyword-only method per operationId (snake_case, e.g. create_message, get_whatsapp_consent), with_response (ApiResponse with status, headers, request_id, idempotency_key, idempotent_replayed, rate_limit), paginate and pages.
    • The Node SDK's transport rules: an Idempotency-Key on every write (a fresh UUID per call, reused by its retries; idempotency_key=False sends none and disables retries); retries of timeouts, network errors, 429, 500/502/503/504 and 409 IDEMPOTENCY_KEY_IN_FLIGHT with equal-jitter exponential backoff that honours Retry-After, only when repeating is safe, never for an error replayed from the idempotency store; redirects never followed.
    • TrovacastApiError (status, code, message, request_id, retryable, retry_after, body, idempotency_key, idempotent_replayed, is_not_found), TROVACAST_ERROR_CODES, TROVACAST_ERROR_CODE_FAMILIES, SDK_ERROR_CODES and is_known_error_code.
    • TypedDicts for every component schema (trovacast.types), and WEBHOOK_EVENT_TYPES.
    • trovacast.webhooks: verify_webhook_signature, construct_webhook_event, parse_webhook_event, create_webhook_signature_header and TrovacastWebhookError, checked against the documented signature vector.
    • A generator (with --check) that regenerates the typed surface from openapi.json.

Go SDK

  1. 0.1.0

    Unreleased

    Changed

    • GetMessageMedia takes a *GetMessageMediaParams before its options: an incoming MMS may carry several files, and Index picks one. Pass nil for the first file (what it fetched before): c.GetMessageMedia(ctx, id, nil). Regenerated from the contract with MediaItems and Media.Index on a message.
    • CallFlowVerbConnect.To is a *CallFlowVerbConnectTo: a connect now takes exactly one of To or Targets (several parties, rung by Strategy), so To is nil on a connect that rings Targets. Write To: &trovacast.CallFlowVerbConnectTo{…} where you wrote the value, and check it for nil when reading a document. Regenerated from the contract with Targets, Strategy, TotalTimeoutSeconds, Confirm and Notice on connect, Notice on record, Notice, Keys and Reply on voicemail, and Purpose and NoticePlayed on a call's recording.
    • (2026-11-07, Round 13) DeleteAgent returns (*Agent, error) instead of error: the API answers the archived agent with its Warnings (it answered 204). Replace err := c.DeleteAgent(ctx, id) with _, err := c.DeleteAgent(ctx, id), or read the warnings.
    • (2026-11-07, Round 13) AgentNumberWarning.Provider is a *AgentNumberWarningProvider: nil for a key without numbers:read, which is told only NumberID, Code and Reason (Detail false). Check Detail before dereferencing it.
    • (2026-11-07, Round 11) NumberWarning.Code is a NumberWarningCode instead of a string: the contract now names two codes (NumberWarningCodeBillingRateUnavailable, NumberWarningCodeAIProviderUnavailable) and v1 may add more, so switch on the constants with a default branch. Code that compared it to a string literal compiles unchanged (an untyped constant converts); assigning it to a string variable needs string(w.Code).
    • (2026-11-06, Round 9) WebhookVerifier.Secrets is a WebhookSecrets, built with trovacast.WebhookSecretsOf(current, previous) instead of a []string literal: the secrets are held in a closure, so a verifier — or a struct, slice, map or error holding one — never prints a signing secret under any fmt verb (%v did; %p and verbs fmt does not know print a struct's fields without calling its methods), in slog or in encoding/json. A verifier prints as its count of secrets and tolerance. Replace Secrets: []string{a, b} with Secrets: trovacast.WebhookSecretsOf(a, b).

    Added

    • Call settings. Regenerated from the contract: UpdateCallSettings takes RecordingRequired beside AICallsEnabled (either or both), the organization's "Record every call" policy; both are *bool now (each is optional), so AICallsEnabled: true becomes a pointer to it. A test key may set a test organization's call settings.
    • A call flow's keys. Regenerated from the contract: a flow document takes Events (dtmf: true), after which every key the caller presses during the flow is told as the opt-in call.dtmf.
    • Staff-first click-to-call to your own phones. Regenerated from the contract: PhoneID on the call's bridge target (createCall's bridge.to: one of the organization's own phones, /v1/phones, rung first with ringFirst: "agent" or connected to the contact otherwise), and PhoneID with target phone on a call's bridge.
    • Country-aware verification and SMS registration. Regenerated from the contract: GetVerificationRequirements (what a business must give in a country, by profile — in, us, gb, eu, international), Identifiers and Jurisdiction on SaveVerification, Business.Jurisdiction, Identifiers.Last4ByKind and Requirements.Profile / Requirements.Identifiers on the verification, the tax_registration document type; ReviewSandboxVerification (test keys decide a test organization's verification); GetSmsRegistration (the SMS registration regime of the organization's country and where it stands under it).
    • The integrator pays. Regenerated from the contract: GetOrganizationUsage; Billing on CreateOrganization, UpdateOrganization, the organization and the balance; Breakdown on ListUsage; PaidFor on invoices; the error codes BILLING_SPEND_CAP_REACHED, BILLING_PAYER_NOT_CONFIGURED and BILLING_PAID_BY_INTEGRATION.
    • One webhook feed for an integration. Regenerated from the contract: ListIntegrationWebhookEndpoints, CreateIntegrationWebhookEndpoint and the rest of /v1/integration/webhook-endpoints, and ListIntegrationEvents / GetIntegrationEvent (/v1/integration/events) — integration keys with the scope organizations:events; ExternalReference on stored events. WebhookEvent gains ExternalReference (an integration's organization) and IntegrationID (a webhook.test to an integration's endpoint).
    • Acting for an organization. WithOrganization (client) and ForOrganization (per call; "" for none) send Trovacast-Organization: an integration key holding organizations:act then acts for that organization with the scopes the platform delegated to its integration. ActingOrganizationHeader names the header. Regenerated from the contract: ActingFor and Integration.DelegatedScopes on GetMe, Livemode on the organization, the scope organizations:act.
    • Regenerated from the contract: UpdateOrganization (PATCH /v1/organizations/{organizationId}, integration keys) — rename an organization you provisioned, switch its product lines or move its plan, within your integration's terms; Entitlements, PlanID and Country on CreateOrganization; PlanID and Country on the organization; the error codes PRODUCT_LINE_NOT_OFFERED and PLAN_NOT_OFFERED.
    • Regenerated from the contract: ReviewSandboxSMSRegistration (POST /v1/sandbox/sms-registrations/review, test keys) — approve or reject a test key's sandbox 10DLC brand, campaign or number assignment; Livemode on brands, campaigns, number assignments and sms.registration.updated's Registration; Media on CreateSandboxInboundMessage (a test MMS) and Reply on its result.
    • Regenerated from the contract: Sandbox on CreateCall's body (test keys): the script a test call's other side plays once answered, and Machine, its answering-machine verdict.
    • Regenerated from the contract: CreateSandboxInboundCall (POST /v1/sandbox/inbound-calls, test keys) — a scripted caller rings a sandbox number and its route runs on the platform's real call logic — and the error code SANDBOX_NUMBER_NOT_ROUTED. GetCallRecording and DeleteCallRecording take a test key, for its own test calls.
    • Regenerated from the contract: PhoneNumber.Livemode (false for a test key's sandbox number — T8: a test key searches, orders, routes and releases fictional sandbox numbers with the same methods).
    • Regenerated from the contract: AcknowledgeTCPA and WithdrawTCPA (POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key — TCPA.Statement on the destination settings, and ErrorCodeDestinationStatementOutdated.
    • Regenerated from the contract: FallbackFlowID on a voice application (CreateApplication, UpdateApplication) — the call flow run when its answer URL is down — and the call timeline's application.fallback entry (applicationId, flowId).
    • Regenerated from the contract: CallSettings.LiveCallLimits (PerOrganization, PerKey) on the call settings — the live-call caps the organization is held to, the deployment's or its own.
    • Regenerated from the contract: port-out — UnlockNumberPortOut (answers NumberPortOutUnlock with the account number and the transfer PIN, once), CancelNumberPortOut, ListPortOuts (and ListPortOutsIter), GetPortOut — the number.port_out.updated webhook event (WebhookEventNumberPortOutUpdated) and the ErrorCodePortOut… codes; a port request's Rejection and CompletedNumbers, and PreviousStatus on number.port_request.updated.
    • Regenerated from the contract: OrderNumber orders by place — OrderNumber.Country with AreaCode or Prefix, Type, SMS — and takes Reference, Metadata and OrderID (the order's own id, for good; answered as NumberOrder.OrderID); a number carries Reference and PendingCompliance, UpdateNumber takes Reference and ListNumbers filters by it; the number.updated webhook event (WebhookEventNumberUpdated); the error codes ErrorCodeNoNumbersAvailable, ErrorCodeNumberPendingCompliance, ErrorCodeNumberOrderConflict and ErrorCodeNumberOrderInProgress.
    • Regenerated from the contract: US 10DLC registration — CreateSMSBrand, ListSMSBrands, GetSMSBrand, CreateSMSCampaign, ListSMSCampaigns, GetSMSCampaign, AssignSMSCampaignNumber, ListSMSCampaignNumbers, GetSMSCampaignNumber, RemoveSMSCampaignNumber — and the sms.registration.updated webhook event.
    • Regenerated from the contract: GetSMSSettings and UpdateSMSSettings (GET/PATCH /v1/settings/sms) — the SMS HELP auto-reply (helpReply).
    • Regenerated from the contract: CancelCalls (POST /v1/calls/cancel), NotAfter on CreateCall, OnMachine on aiAgent, and the error code CALL_NOT_AFTER_PASSED.
    • Regenerated from the contract: OptOut on aiAgent, a number's ai route and a flow's ai verb, and the call.ai.opt_out and opt-in call.dtmf webhook events.
    • Regenerated from the contract: Transfer on aiAgent and a number's ai route (a hand-off to a person), and the call.ai.transfer webhook event.
    • Regenerated from the contract: aiAgent on CreateCall takes FirstMessage, Instructions, Tools and Session (the session webhook asked when the conversation starts), and the call takes Reference (read back as Reference); a number's ai route takes Ai; a call flow's ai verb takes FirstMessage, Instructions, Tools, Session and OnUnavailable; the error code AGENT_TOOL_SECRET_REQUIRED.
    • Regenerated from the contract: ReplaceNumberRoute (PUT /v1/numbers/{numberId}/route) — a number's whole routing as one call-flow document under your own rising version.
    • Regenerated from the contract: Metadata on a number (UpdateNumber sets it) and the Metadata filter on ListCalls.
    • Regenerated from the contract: Ringing on call.ringing and AnsweredBy on call.answered: who an inbound call's route rang and who took it; nil on an outbound call's own events.
    • Regenerated from the contract: the call.voicemail.ready webhook event (calls:read, transcripts:read) — a caller's message with its RecordingID, Key and Transcript; and Key on call.missed's voicemail.
    • (2026-11-07, Round 13) Regenerated from the contract: Warnings on the CallSettings UpdateCallSettings returns (while AI calls are off), and FlowID and Detail on AgentNumberWarning. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 13) Regenerated from the contract: the call.rated webhook event (WebhookEventTypeCallRated, calls:read) — the call with its Charge once it is rated. A call is rated after its final call.* event, which carries a nil Charge. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 13) entries.
    • (2026-11-07, Round 12) Regenerated from the contract: Rule (*CallChargeRule: CallChargeRuleStallSilent, CallChargeRuleStallPastCeiling, CallChargeRuleAIVoiceNeverStarted, CallChargeRuleTalkTimeUnknown) and Reason on a call's charge (also the timeline's rated entry); NumberWarningCodeAIAgentUnavailable and the reasons NumberWarningReasonAICallsDisabled, NumberWarningReasonAgentInactive, NumberWarningReasonTestAgent; and Warnings ([]AgentNumberWarning: the number's warning plus NumberID) on the Agent UpdateAgent returns. Behaviour a client meets is in the API changelog's 2026-11-07 (Round 12) entry.
    • (2026-11-07, Round 11) Regenerated from the contract: Client.ListCallEvents and ListCallEventsIter (GET /v1/calls/{callId}/events, calls:read) — a call's timeline, oldest first (CallTimelineEvent, CallTimelineEventType, CallTimelineData, CallTimelinePage); and on NumberWarning, AgentID, Reason (NumberWarningReason) and Step (*NumberWarningStep: Node, Index), with the code AI_PROVIDER_UNAVAILABLE (see Changed). Behaviour a client meets is in the API changelog for 2026-11-07.
    • (2026-11-07, Round 10) Regenerated from the contract: Warnings on PhoneNumber (NumberWarning: Code BILLING_RATE_UNAVAILABLE, Direction, Provider, CallType (NumberWarningCallType), Message — a route your plan does not price, saved all the same), and AI_PROVIDER_UNAVAILABLE among the 422s of CreateCallAction (a transfer to a call flow whose AI agent cannot speak here). Behaviour a client meets is in the API changelog for 2026-11-07.
    • (2026-11-06, Round 9) Regenerated from the contract: the AI_PROVIDER_UNAVAILABLE error code, Availability on agents, FromSource on calls, PayloadVersion on voice applications (answer-URL payload 2; payload 1 is deprecated), and UnavailableReason and Gaps on call transcripts — see the API changelog for 2026-11-06.
    • (2026-11-06, Round 8) Regenerated from the contract: whole-number fields are int / *int (Limit: trovacast.Ptr(50), MaxDurationSec int) — the contract types them integer now; a call flow's Definition is a *CallFlowDocument (x-document in the contract), so a typed document is sent as it is, without AsObject; WebhookEvent.Livemode (required by ParseWebhookEvent); Mock on the call summary and its extraction, SpeechUnavailable on the gather event, From and NumberID on outbound calls.
    • (2026-11-06) The first version, generated from the v1 contract the Node SDK 0.2.0 and the Python package 0.1.0 are built from (183 operations): NewClient and one Client method per operationId in Go case (CreateMessage, GetWhatsAppConsent, ListSMSSenders), taking a context, the path parameters, a <Method>Params struct for the query and a typed body; a Go type for every component schema (a struct per object, a string type and constants per enum, CallFlowVerb and the other verb unions with MarshalJSON/UnmarshalJSON), Nullable[T] for the optional fields the API also accepts as null, Ptr, File for the two upload operations, and AsObject / FormatTime.
    • The Node and Python SDKs' transport rules: an Idempotency-Key on every write (a fresh UUID per call, reused by its retries; WithIdempotencyKey, WithoutIdempotencyKey); retries of timeouts, network errors, 429, 500/502/503/504 and 409 IDEMPOTENCY_KEY_IN_FLIGHT with equal-jitter exponential backoff that honours Retry-After up to WithMaxRetryAfter, only when repeating is safe, never for an error replayed from the idempotency store; a per-attempt timeout; redirects never followed; the caller's context cancellation returned as ctx.Err().
    • *APIError (Status, Code, Message, RequestID, DocURL, Retryable, RetryAfter, IdempotencyKey, IdempotentReplayed, Body, IsNotFound), the ErrorCode constants of every documented code, KnownErrorCodes, IsKnownErrorCode, SDKErrorCodes and ErrorCodeFamilies.
    • WithResponseInfo (status, headers, request id, idempotency key, replay, RateLimit), RateLimitFromHeader and ParseRetryAfter.
    • <Method>Iter for every paginated read: an Iterator with Next/Item/Err, Cursor to resume, and All for range.
    • VerifyWebhook, WebhookVerifier (several secrets while you rotate), ParseWebhookEvent, CreateWebhookSignatureHeader, WebhookError and the WebhookEventType constants, WebhookEventTypes, OptInWebhookEventTypes and WebhookEventScopes from the contract's webhook catalog, checked against the documented signature vector.
    • A generator (go run ./internal/cmd/generate, with -check) that regenerates the typed surface from openapi.json, standard library only.

    Security

    • (2026-11-06) Printing a Client never shows the API key, under any fmt verb (%s on a Client value and %t on a pointer used to print it), by value or pointer, inside a struct, a slice, a map or an error: Client implements fmt.Formatter, fmt.GoStringer, fmt.Stringer and slog.LogValuer (all print trovacast.Client(<base URL>)), and holds the key where reflection cannot reach it.
    • (2026-11-06) A plain http:// base URL is refused with ErrInsecureBaseURL unless its host is loopback (localhost, 127.0.0.0/8, [::1]), so the key never crosses the network in the clear; a base URL with no host (https://:443) is refused too. If you pointed WithBaseURL at http:// on another host, use https://.
    • (2026-11-06) Answer bodies are read up to a limit: 10 MiB by default (DefaultMaxResponseBytes, WithMaxResponseBytes), 1 MiB for an error answer. A longer one is closed unread and the call returns an *APIError (INVALID_RESPONSE for a 2xx, HTTP_<status> for an error) whose cause is the new *ResponseTooLargeError (Status, Limit; errors.As finds it through APIError.Unwrap).