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
A +1 call is held to the called party's own local time
UnreleasedAdded
PATCH /v1/settings/callstakesrecordingRequired— the console's "Record every call" — alone or withaiCallsEnabled(at least one of the two;aiCallsEnabledis no longer required).falselets each call say whether it is recorded (recording.enabled, a flow'srecord);truerecords every call, andPOST /v1/callsthen needsrecording.consentEvidence. A new organization still starts with it on. Same compare-and-set onversion, audited against the key (organization.updated,recordingRequired.from/.to). An integration acting for an organization it provisioned (withsettings:writedelegated) 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/callswith atc_test_key acting for a test organization (livemode: false— one a test integration key provisioned) now setsaiCallsEnabledandrecordingRequired, 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 still422 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, aFLOWcall'sdefinition, 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-incall.dtmf, as an AI conversation's are; never a key pressed into a sensitive gather, never a dialled party's.sequencenow 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) takesbridge.to.phoneId, one of your own phones (/v1/phones), rung by id so your staff's number never leaves the platform. WithringFirst: agentit rings that phone first and dials the contact once it answers (assigned to no one; a phone already on a call is409); 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. AphoneIdthat is not one of your phones is400 VALIDATION_FAILED. The call'sbridgegainsphoneIdandtarget: "phone". - An SMS refused once its recipient is known — no opt-in (
CONSENT_REQUIRED), an opt-out, the sender, the window — carries the contact'scontactIdin the error body, as WhatsApp and email refusals already did, so a send byto.phonethat created the contact can record its consent and retry. - Verification is country-aware.
GET /v1/verifications/requirementspublishes what a business must give in a country — its profile (in,us,gb,eufor the 27 member states,internationalfor 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/verificationstakesidentifiers(by kind:gstin,pan,cin,ein,company_number,vat_number,registration_number,tax_number) andjurisdiction(a US state of registration);gstin,panandcinkeep working as the kinds they stand for in the business's country. The verification resource gainsbusiness.jurisdiction,identifiers.last4ByKind,requirements.profileandrequirements.identifiers; a refused submission (422 VERIFICATION_INCOMPLETE) gainsmissingIdentifiers. 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;verifiedstays false (a test organization never goes live).- India in the sandbox: a test key orders
+91sandbox numbers —+91 <area> 0000 0XXXin Delhi (11), Mumbai (22), Kolkata (33), Hyderabad (40), Chennai (44) and Pune (20), subscriber numbers no Indian exchange can issue (a leading0is the trunk prefix in every SDCA) — routes them and takes simulated and outbound test calls on them as on US and UK ones. They arelocaland 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/registrationsays which SMS registration regime applies to the organization's country —dlt(India),us_10dlc(the US),sender_id(the UK) ornone— 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_MISSINGnaming the scope otherwise), and takes the key's mode (a test key's receives test traffic). Awebhook.testto an integration endpoint names no organization (organizationIdis the nil UUID) and carriesintegrationId. - Event envelopes (deliveries and
GET /v1/events) of an organization an integration provisioned carryexternalReference, the integration's own reference for it, besideorganizationId. - The integrator pays:
billing: { payer: "integration" | "organization", spendCap?: { amountMinor, period: "month" } }onPOSTandPATCH /v1/organizationsbills an organization's calls, messages, plan fees and numbers to the integration's billing organization (set by the platform;409 BILLING_PAYER_NOT_CONFIGUREDuntil it is), each ledger entry naming the organization; refunds and re-ratings go back to the wallet that was charged. The organization resource andGET /v1/balancegainbilling(payer, cap, this month's spend). A dial, send or number activation past the monthly cap is402 BILLING_SPEND_CAP_REACHED(spendCapMinor,spentThisPeriodMinor; also a message'sfailure.codewhen the send worker refuses it); a top-up of an organization its integration pays for is409 BILLING_PAID_BY_INTEGRATION. NewGET /v1/organizations/{organizationId}/usage(getOrganizationUsage,organizations:read): one organization's usage rows, as its ownGET /v1/usage.GET /v1/usage?breakdown=organizationbreaks a billing organization's spend down by the organizations it paid for (each row'sorganizationId), and statements (GET /v1/invoices…) carrypaidFor. - Acting for an organization (integration keys): an integration key holding the new scope
organizations:actsendsTrovacast-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 is404; a suspended one409 ORGANIZATION_NOT_ACTIVE; an undelegated scope403 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/meanswers the integration'sdelegatedScopesand, 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 anorganizationoption. - Test integration keys (
tc_test_…): theirPOST /v1/organizationsprovisions test organizations (livemode: falseon 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/organizationstakesentitlements({ calling, messaging }, messaging only by default),planId(your default plan by default) andcountry(ISO 3166-1 alpha-2, the deployment's home country by default), and the newPATCH /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 codesPRODUCT_LINE_NOT_OFFERED(409,line) andPLAN_NOT_OFFERED(409,planId). The organization resource gainsplanIdandcountry. 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_LIMITnow carrieslimit(the cap that applies, asSUBACCOUNT_LIMIT_REACHEDalready 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.scriptsets 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;atsets the call's clock forhours. Every event a live call fires reaches your test endpoints. Each number aconnect, 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 codeSANDBOX_NUMBER_NOT_ROUTED(409, withreason). - Test calls play on the same path (T8): once answered, a test
FLOWorBRIDGEcall's flow runs on the sandbox's media plane and anAI_AGENTcall's mock agent talks — the session webhook, real signed tool calls, the opt-out and the hand-off — scripted by the newsandboxfield onPOST /v1/calls(test keys only; a live key is400 VALIDATION_FAILED), which takes the inbound script plusmachine: the answering-machine verdict (call.machine_detected, the flow'samd, 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):
GETandDELETE /v1/calls/{id}/recordingnow 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-messagestakesmedia(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 yourhelpReplyas live, returned as the newreplyfield (elsenull).textmay be left out whenmediais given. - 10DLC in test mode (T8):
POST /v1/sms/brands,/v1/sms/campaignsand/v1/sms/campaigns/{id}/numbers(andDELETE) take a test key, which registers in the sandbox (livemode: false: never filed with the registry), and the newPOST /v1/sandbox/sms-registrations/review(reviewSandboxSmsRegistration,sms:manage, test keys only) approves or rejects one, as the registry would; each move issms.registration.updatedto test endpoints. Brands, campaigns and number assignments, and the event'sregistration, gainlivemode. - Sandbox numbers for test keys (T8): a test key searches (
GET /v1/numbers/available), orders (POST /v1/numberswithcountryandareaCodeorprefix, or anumberits 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 (NANP555-01XXin 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 gainslivemode(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: retiredin 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 asfrom, and presents one by default. - Ordering a number by place, under your own order id (T7):
POST /v1/numberstakescountrywithareaCode(as dialled at home:415, UK020) orprefix,typeandsms— 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 new409 NO_NUMBERS_AVAILABLE(another area code may have numbers). Every order takesreferenceandmetadata(kept on the number:referenceis new on the number, set byPATCHtoo and listed byGET /v1/numbers?reference=) andorderId, your own id for the order for good: the same id answers the number it bought, never a second one (409 NUMBER_ORDER_CONFLICTwith another request or once the number is no longer yours,409 NUMBER_ORDER_IN_PROGRESSwhile the first is placed); the order answers it asorderId. - 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: trueon the number (new),pending.codeNUMBER_PENDING_COMPLIANCEon the order and the refusal ofPOST /v1/numbers/{numberId}/activatewhile it lasts — until the review settles. The new webhook eventnumber.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_OUTDATEDwhen the statement changed) andDELETE /v1/settings/destinations/tcpawithdraws it — the console's step, now automatable;GET /v1/settings/destinationsanswers the statement's words astcpa.statement. New error codeDESTINATION_STATEMENT_OUTDATED. - A voice application's fallback flow (T9):
fallbackFlowIdonPOST/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 typeapplication.fallback(applicationId,flowId,code). - Per-organization live-call caps (T9): the platform can raise (or lower) one organization's live
/v1call caps over the deployment's (PUBLIC_API_MAX_LIVE_CALLS_PER_ORGANIZATION/_PER_KEY);GET /v1/settings/callsanswers the caps the organization is held to asliveCallLimits: { perOrganization, perKey }. A call over either is still429 CALL_CONCURRENCY_LIMIT, itslimitthe organization's own. - Port-out (T7):
POST /v1/numbers/{numberId}/port-outunlocks a number for the carrier you are moving it to and answers the account number and a transfer PIN (once; validvalidForDays, default 7);POST /v1/numbers/{numberId}/port-out/cancelrelocks it;GET /v1/numbers/port-outsandGET /v1/numbers/port-outs/{portOutId}read them (numbers:read/numbers:write). The new webhook eventnumber.port_out.updatedtells every step — unlocked, completed (the number left the platform), failed (refused, given up, or the PIN expired: relocked) and cancelled. New error codesPORT_OUT_NUMBER_NOT_PORTABLE,PORT_OUT_NOT_OPEN,PORT_OUT_INVALID_TRANSITIONandPORT_OUT_VERSION_CONFLICT. - Port-in detail (T7): a rejected port request carries
rejection(the losing carrier's own reason and code), a completed onecompletedNumbers(each number with its id), andnumber.port_request.updatedcarriespreviousStatus(a newfocDatewithinapprovedreads 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/campaignsandPOST/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 yourreference(another body with the same reference is409 SMS_REGISTRATION_REFERENCE_CONFLICT) — filed with the platform's SMS provider (or reviewed by the platform) and read back until decided. The new webhook eventsms.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 topending_verification. New error codesSMS_REGISTRATION_REFERENCE_CONFLICT,SMS_REGISTRATION_CLOSED,SMS_NUMBER_NOT_ELIGIBLEandSMS_NUMBER_ALREADY_ASSIGNED. - The SMS HELP auto-reply (T6):
GET /v1/settings/smsandPATCH /v1/settings/sms(settings:read/settings:write) sethelpReply— 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 —mediastays its first file — each with anindex. Files are fetched from the vendor, checked and stored;message.media.ready/message.media.failedfire once the last of a message's files has settled.GET /v1/messages/{messageId}/mediatakesindexto fetch any one of them. While a file whose type the vendor did not say is stillpending, itskindreadsunknown. - An AI conversation can run with its own configuration besides its agent's:
POST /v1/calls(mode: AI_AGENT) takesaiAgent.firstMessage,aiAgent.instructions,aiAgent.toolsandaiAgent.session; a number'sairoute takesroute.aiwith the same fields (read back asroute.ai); a call flow'saiverb takesfirstMessage,instructions,tools,sessionandonUnavailable. 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 itsfirstMessage,firstSpeaker,instructions,language,endCallPhrases,maxTurnsandtools— a signed POST (event: agent.session, with the call's context) answered withintimeoutSeconds(default 5). A session that does not answer leaves the call on its own options and the agent's configuration; a flow'saiverb can takeonUnavailableinstead. Test calls ask it too. New error codeAGENT_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,fromandto(your number in full, the contact masked to the last four digits, withcontactId),numberId, the call's and the number'smetadata, and yourreference. POST /v1/callstakesreference: your own id for the call, echoed on the call asreferenceand in an AI agent's tool and session requests.- An AI call can hand the caller to a person:
transfer: { number | phoneId, ringTimeoutSeconds?, whisper? }onaiAgent, a number'sroute.ai(phoneIdonly) or a session's answer. The agent is offered atransfer_to_persontool; 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 eventcall.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? }onaiAgent, a number'sroute.ai, a flow'saiverb 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_CALLon any later call), the agent says the reply and the call ends. Webhook eventcall.ai.opt_out(calls:read):{ call, optOut: { method, key, phrase, contactId, doNotCall } }, recorded with the mark. POST /v1/callstakesnotAfter: nothing is dialled at or after it — a request that arrives too late is422 CALL_NOT_AFTER_PASSED(new error code), and a call caught by the dial's last check failsNOT_AFTER_PASSED.POST /v1/calls/cancel(calls:write,cancelCalls):{ reference }ends every queued or live call placed with it, idempotently, answering each one'soutcome(cancelled,ended,pending,unsupported).- The answering-machine verdict reaches a call's flow as the
amdvariable (human,machine,unknown; aswitchon it waits a few seconds for the verdict), andaiAgent.onMachine: hangupends 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
connectrings several parties:targetsin place ofto(up to 10; each anumber, anagentor aclient, with its owntimeoutSeconds,skipwindows — weekly local ranges in atimezone, and spans between two instants — and yourreference), rung one after another (strategy: sequential, the default) or every number at once (simultaneous, withinCALL_CHILD_LEGS_MAXlegs), withintotalTimeoutSecondsin 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. connecttakesconfirm: { 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, thenonNoAnswer.- A recording notice:
connect,recordandvoicemailtakenotice, spoken before the recording starts.connectwithrecord: truenow 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. voicemailtakeskeysandreply: a key pressed through the greeting or the message ends the voicemail (what was recorded is kept), becomes thedigitsvariable, and the reply is spoken. The key is kept on the voicemail:call.missed'smissed.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 risingversion. 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,unchangedfor 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'smetadatarules), set withPATCH /v1/numbers/{numberId}and read back on the number. It is copied onto every inbound call to the number as the call'smetadata, so it is echoed on the call's events. GET /v1/callstakesmetadata=key:value(repeat for up to 5 pairs), asGET /v1/messagesdoes: calls whosemetadata— their own, or their number's — holds every pair, by exact match, indexed.call.ringingandcall.answeredare told for an inbound call a number routes, which is answered by the platform on arrival and so had neither:call.ringingwhen aconnectstarts ringing someone (ringing: the strategy and each party — its place intargets, yourreference, a number's last four digits and the/v1/phonesphone it is), andcall.answeredwhen 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 owncall.ringingandcall.answeredcarryringing: nullandansweredBy: null.- Webhook event
call.voicemail.ready(calls:read,transcripts:read): a caller's message is ready —voicemailwith itsrecordingId,key, andtranscript({ status, text }): the voicemail step'stranscribe(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 aftercall.missed. - A call's
recording(andGET /v1/calls/{callId}/recording) says what it is of —purpose:callorvoicemail— and whether a recording notice played before it started (noticePlayed).GET /v1/calls/{callId}/recordingtakesrecordingIdto fetch one recording of the call by id, such as a voicemail's beside the call's own. POST /v1/callstakescalledPartyTimeZone: 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
hoursverb takes the schedule itself in place of a schedule id:schedule: { timezone, weekly, holidays, overrides, closures }.weeklyis the usual local ranges per ISO weekday;holidaysare local dates closed all day (theholidaybranch);overridesgive one date its own same-day ranges in place of its weekday's (none: closed that day);closuresare 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.reasonsays which,missed.queueIdnames the queue involved, andmissed.voicemailis 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/phonesregisters one (number, with your ownlabelandreference),GETlists and reads them with the number masked,DELETEremoves one. A leg a call flow'sconnect, or a transfer, dials to a registered phone is your staff answering their own handset (legRole: AGENT_PHONEon 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 codesOWN_PHONE_IS_CARRIER_NUMBER(400) andOWN_PHONE_LIMIT_REACHED(409).
Changed
- A test SMS to India now carries the
SMS_DLT_ENTITY_MISSINGwarning whenever no DLT principal entity is set — with no SMS settings too, where it used to saySMS_NOT_CONFIGUREDalone (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), andpanis India's only: sent for a business elsewhere it is now400 VALIDATION_FAILED(it was stored and meant nothing). A draft saved before shows any new gap inrequirements; a submission is refused422 VERIFICATION_INCOMPLETEuntil 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 — itsfrom, 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 namedfrom. A seat with an allocated number and nofrompresents it as before. - A test key's
POST /v1/sms/brands,POST /v1/sms/campaignsand the number-assignment writes are no longer422 TEST_MODE_UNSUPPORTED: they register in the sandbox (T8), andsms.registration.updatedis delivered to test endpoints for sandbox registrations. A tightened requirement: theGET /v1/sms/brands,/campaignsand…/numbersreads now list the registrations of the key's own mode only, and a live registration is404 NOT_FOUNDto 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/numbersnow lists its sandbox numbers only — it used to list the organization's live numbers — and a live number is404 NOT_FOUNDto it onGET /v1/numbers/{numberId},PATCH,PUT …/route,activateandrelease(the writes used to answer422 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. ItsGET /v1/numbers/availableanswers sandbox numbers instead of the platform's inventory; ordering withnumberId(the inventory) is still422 TEST_MODE_UNSUPPORTEDfor a test key;PATCH,PUT …/route,activateandreleasework on its own sandbox numbers. - A test
FLOW,BRIDGEorAI_AGENTcall 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'sflow_step.*entries, its transcript what was said on it, and itshangupwho ended it (anAI_AGENTcall with no script: the agent,application/ai_ended, after a short scripted conversation).EXTERNAL_AGENTand agent-firstBRIDGEtest 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.respectCallingWindowreads 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
BRIDGEcall 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-Organizationand 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_LIMITEDwithRetry-Afteronce 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/eventsfrom listing them, but a delivery recorded earlier — one waiting out a retry, or any of the last 30 days resent withPOST /v1/integration/webhook-endpoints/{endpointId}/deliveries/resend(or one delivery's/resend) — was still sent. It is nowfailedat once withlastError: "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/callstakes one of your sandbox numbers asfromin every country that has them. India's sandbox range (+91 11 0000 0XXXand its five sister area codes) is one no real line can have, and the format check onfromrefused 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 still422 CALLER_ID_NOT_OWNED.- A call forwarded by the carrier to a +1 number was refused
DESTINATION_BLOCKEDeven 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: aconnector 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
connectfail (FLOW_CONNECT_FAILED, causeBILLING_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}/exportwas422 TEST_MODE_UNSUPPORTEDfor 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 stays422 TEST_MODE_UNSUPPORTEDto it. - A test key could change a live person's consent: an outbound test
AI_AGENTcall to a live contact's number (byto.phoneorcontactId) 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 onecall.ai.opt_outsaysdoNotCall: falseand 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 ascall.missedto 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 ascall.voicemail.readyto 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_UNSUPPORTEDamong the refusals ofPUT /v1/numbers/{numberId}/route,POST /v1/numbers/{numberId}/activateandPOST /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 is404to it. The refusal is no longer listed there (ordering an inventory number, a DLT header, an SMS sender and porting still answer it).
Contacts keep the attributes they already carry
2026-11-07Fixed
- 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/contactson 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").
- 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.
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-07Changed
- 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
numberIdandstep— on the number (GET /v1/numbers/{numberId}) and in the answers toPATCH/DELETE /v1/agents/{agentId}andPATCH /v1/settings/calls— the first being the one its calls fail with. With AI calls off, a step whose agent is archived warned onlyAI_CALLS_DISABLED, and switching AI calls back on answeredwarnings: []while the step still failedAGENT_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/callswithaiCallsEnabled: truelists 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_INACTIVEwarning told you to switch the agent on withPATCH /v1/agents/{agentId}(active: true) whether it was switched off or archived, and thatPATCHrefuses an archived agent. Thereasonis unchanged; themessagenow 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".
PATCHandPOST …/tool-secreton an archived agent answer400 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.joinedwith noleg.left, though a test call's timeline shows both. Each now leaves with the call: itsleg.leftfollows the end, once, with thechildCallIditsleg.joinednamed (a party'sleg.leftnamed none before). A conference's parties still on at its end are told byconference.ended, as before — noconference.participant.leftfor them. A blind transfer's agent leaving the call now always writes itsleg.lefttoo. - 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, thenqueue.left(ABANDONED) andtransfer.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, thentransfer.failed(NO_AGENTS) when the call ends or another transfer takes the caller; a second queue transfer meanwhile is409 CALL_ACTION_IN_PROGRESS, as live. The live caller's voicemail is not modelled (the sandbox runs no flow).
- 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
Phone numbers caught however they are written; dates no longer masked
2026-11-07Changed
- **A tightened requirement: an
attributesvalue holding a phone number written with any separator is refused.**POST /v1/contactsrefused 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 now400 VALIDATION_FAILED; a calendar date (15/11/2026,2026-11-15) is not a phone number and is accepted. Send phone numbers inphone. - **
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
aistep 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 readsunavailableinstead. 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.
- **A tightened requirement: an
A test call's actions on its timeline, a webhook for a call's charge, every broken AI route named
2026-11-07Added
- **
call.rated** (calls:read): the call, with itscharge, once the charge is written —charged,waivedornot_connected, with theruleandreasonit was rated by. A call is rated after its finalcall.*event, so those carrycharge: null(0 of 35 final deliveries carried a charge in review), and a webhook-only integration never learned what a call cost. Anunratedcharge (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/callsanswers withwarnings.** While AI calls are off, every number whoseairoute or routed flow's AI step now refuses its callers (AI_AGENT_UNAVAILABLE,reason: AI_CALLS_DISABLED), in the shapePATCH /v1/agents/{agentId}answers;[]while they are on. Switching AI calls off listed nothing before. - **
flowIdanddetailon 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 anairoute's own), and whether the number's details are in the warning (below).
Changed
- **
DELETE /v1/agents/{agentId}answers200with the archived agent andwarnings** (it answered204with no body). Archiving an agent only a routed flow's AI step names was allowed and said nothing, while the number then warnedAGENT_INACTIVE; the answer now names each number (and flow) whose step falls back, as the agentPATCHdoes. A repeat answers200again. A client that treated any 2xx as success is unaffected; one that checked for204should accept200. An agent a number'sairoute answers with is still refused409 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 onlyagents:*scopes was refusedGET /v1/numbers(403) yet read number ids, channels and route state in the agentPATCHanswer. Withoutnumbers:readeach warning now carries onlynumberId,codeandreason—provider,agentId,stepandflowIdnull,detail: false, and a message that names no route. Give the keynumbers:readfor 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/callsanswers the same cause with:409 AI_AGENT_INACTIVEfor an agent switched off or archived and404 AI_AGENT_NOT_FOUNDfor one that is not your organization's live one (a test agent reads exactly as an unknown id) — both were400 VALIDATION_FAILED— beside the unchanged409 AI_CALLS_DISABLEDand422 AI_PROVIDER_UNAVAILABLE. An inbound call'sfailure.codestaysAI_AGENT_UNAVAILABLEfor 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) whileGET /v1/calls/{callId}/eventsshowed onlycreated…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'sleg.joined(childCallId: null— the sandbox dials no leg) andresumed, andleg.leftonce the call ends; a transfer to a queue addstransfer.started,transfer.ringingandqueue.entered, thenqueue.left(ABANDONED) andtransfer.failed(CALLER_HUNG_UP) when the caller hangs up waiting;recordaddsrecording.pausedandrecording.resumed. A gather, speak or play writes no entry on any call. - A test call refuses what a live call refuses.
resumewhen the caller is not on hold is409 CALL_NOT_HELD;recordon a call whose channel records it itself is409 RECORDING_NOT_CONTROLLABLE; a second queue transfer while the caller waits is409 CALL_ACTION_IN_PROGRESS. The sandbox answered all three200.
- **
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-07Changed
- Switching an AI agent off, or archiving it, stops its calls. An
AI_AGENTcall admitted while the agent was on, whose agent is switched off or archived before it rings, failsAI_AGENT_UNAVAILABLE(call.failed) without ringing; one whose agent goes off between dial and answer is hung up when its audio arrives, failedAI_AGENT_UNAVAILABLE, and — answered with nobody speaking — charged at the channel's manual rate for its connected time (charge.ruleAI_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 isunavailablerather 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.reasonforAI_AGENT_UNAVAILABLEnow 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 itsBILLING_*code and status (402 or 503), now with the plain sentence for that code —BILLING_INSUFFICIENT_CREDITreads "Not enough credit to place this call; ask a project admin" — instead of the sentencePOST /v1/callsanswers 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 oncode, never on the sentence./v1/callsitself 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 answered429 RATE_LIMITED(withRetry-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'shangup.reason(and the SDKs' doc comments made from it) now listsagent-hangup(an agent hung up in the console) andsupervisor-end(a supervisor's End call), which calls already carried and this reference already listed;hangup.side's says a person in the console isagent. No call reads differently.
- Switching an AI agent off, or archiving it, stops its calls. An
Test calls on the timeline, every refused AI route warned, unchanged routes always saved, why a call was charged, supervisors end calls
2026-11-07Added
- 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 readsreason: "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.
chargeon a call (asGET /v1/calls/{callId}reads it, and on thecall.*events sent after the call is rated) and the timeline'sratedentry carryruleandreason. A call is rated after its final event, socall.completed,call.failed,call.no_answerandcall.busycarrycharge: null; thecall.ratedevent (see the later 2026-11-07 entry) carries the charge. (This entry said "in everycall.*event" until then.)rulenames the rule the call was rated by when it was not its talk time at its plan's rate for its type:STALL_SILENTandSTALL_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.reasonis the rating's own sentence (null when there is nothing to say). Switch onrule; v1 may add values. - **
AI_AGENT_UNAVAILABLEon a number'swarnings**, withreasonAI_CALLS_DISABLED(AI calls are switched off for your organization),AGENT_INACTIVE(the agent is switched off or archived) orTEST_AGENT— on anairoute (its calls are refusedAI_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 withwarnings**: each number the change leaves failing (numberIdand 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 sameroutesent 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}/eventswith a test key answered[]for every test call while itscall.*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 noratedentry. A live key still reads none of them (404). - **Re-sending a number's
airoute after its agent lost its voice** was refused422 AI_PROVIDER_UNAVAILABLEalthough 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
dryRunthat 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.
- A supervisor can end a live call from the desk. Such a call reads
New organizations' first calls, stuck-call billing, forwards held to the call ceiling
2026-11-07Fixed
- 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/callsat once, say — could answer500for 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 usual402/503billing refusal. - A stuck call cleared because it went silent is billed to its last sign of life. A call closed
failure.code: WATCHDOG_EXPIREDbecause 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
unavailableonce its grading gives up, exactly as when the credential itself is unavailable. Agents with no credential of their own are unchanged.
- A new organization's first concurrent calls are all answered. The first billable requests of an organization that had never been billed — several
A call's timeline, numbers that warn when their AI cannot answer, unpriced calls never charged by surprise
2026-11-07Added
- **
GET /v1/calls/{callId}/events** (calls:read,listCallEventsin the SDKs): the call's timeline, oldest first and paged like every list —created,queued,ringing,answered,ended(with the call'sstatusandfailure); each flow step (flow_step.started, thenflow_step.endedwith itsoutcome, whether it took itsfallbackand thecodewhy); each AI step admitted or refused (ai_step.admitted,ai_step.refusedwith 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 answers404, 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.
warningson the number resource gainsAI_PROVIDER_UNAVAILABLE: the AI agent anairoute answers with — or one an AI step of aflowroute hands the caller to — cannot speak on this deployment (itsavailability.runnableis false: a provider key, or a credential alias, it needs is gone), with the samereasonGET /v1/agents/{agentId}reports. A flow route also warnsBILLING_RATE_UNAVAILABLE(callType: full_ai) for an AI step whose AI call your plan does not price. Each warning gainsagentId,reasonandstep({ node, index }, null when it is about the route itself). Warnings never block a save. - **
PROMOTIONAL_NUMBER_REQUIRED**,PROMOTIONAL_PURPOSE_REQUIREDandPROMOTIONAL_WINDOW_CLOSEDare listed with the other dial refusals ofPOST /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 staysunratedunless 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.
- **
Refused inbound calls on the record, route pricing warnings, AI whose voice never started billed as manual
2026-11-07Added
- **
warningson the number resource.**GET /v1/numbers,GET /v1/numbers/{numberId}andPATCH /v1/numbers/{numberId}answer each number withwarnings: [{ 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 (callTypefull_aifor a route to an AI agent,manualfor 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/pricinglists 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) andAI_AGENT_UNAVAILABLE, each with its ownfailure.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 itdirection: inbound,status: failed,failure.codethe refusal's code, it firescall.failed(nevercall.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_AGENTcall) 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.ratePerMinuteMinorsays which). - An AI step checks its agent's availability first. A call flow's
aiverb orconnectto an AI agent whoseavailability.runnableis false is refused before it starts — the step readsfailed,cause: AI_PROVIDER_UNAVAILABLE— so the flow takes its fallback and the call is not charged as an AI call. Atransferaction to a call flow that hands callers to such an agent is422 AI_PROVIDER_UNAVAILABLE(reason,provider,leg,agentId) before anything happens to the call. - The default caller ID prefers the contact's country. A
/v1call with nofrompresents 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+91number to an Indian contact, however old your+1number is.fromSourcestill readsorganization_number.
Fixed
- The answer-URL request section of the reference stated payload 1's
callfields after payload 2's example; each version's fields are now stated once, under its version.
- **
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-07Changed
- 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" }onGET /v1/agents, and anAI_AGENTcall to it is422 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
aistep, or aconnectto{ ai }, naming an agent whoseavailability.runnableis false is422 CALL_FLOW_INVALIDwhen the flow is created, versioned, published or validated, and when it is sent inline onPOST /v1/calls(nothing is dialled); the issue'smessagenames the reason, e.g.(voice_key_missing). A published flow whose agent loses its voice later still takes the step'sfailedpath 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}withroute: { kind: "ai" }naming such an agent is422 AI_PROVIDER_UNAVAILABLEwithreason,providerandleg, as anAI_AGENTcall 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
gapsreflect 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
/v1call past its ceiling runs on every server; it no longer waits out a scheduler lease held by a server that died.
- 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
A call's ceiling for its whole life, every call in flight priced, null refused, test objects unseen
2026-11-06Changed
- **A call keeps its
maxDurationSecfor its whole life** (a security fix: a tightened requirement). A/v1call 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, atransferto 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'sconnect) are hung up, andcall.completedreportshangup: { 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/callswas 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. The402 BILLING_INSUFFICIENT_CREDITrefusal'sinFlightMinutesincludes 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
nullis400 VALIDATION_FAILEDon every write.** EveryPOST,PATCHandPUTbody takesnullonly where the contract documents the field as nullable (it clears the value, it unassigns); any othernull, at any depth of the body, is refused before anything is written. Omit an optional field instead of sendingnull. For examplePOST /v1/conversations/{conversationId}/assignwith{"email": null}answered500; it is400now ({"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 inPOST /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_INVALIDwith "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}/checkcounts 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 with409 VERIFY_NOT_PENDINGwhile 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 are409 VERIFY_NOT_PENDING(failed). - A DLT header is refused under a rejected or suspended entity.
POST /v1/dlt/headersnaming an entity the platform rejected is409 DLT_REGISTRATION_REJECTED, and one it suspended409 DLT_REGISTRATION_LOCKED. Register the corrected entity and file the header there.
Fixed
- A dial Plivo refused answers
502with the status alone — never Plivo's own error text, which could quote the number dialled.
- **A call keeps its
AI agents that cannot speak, cross-mode call routes, your own caller ID, answer-URL payload 2, transcript reasons
2026-11-06Added
- **
422 AI_PROVIDER_UNAVAILABLEbefore anAI_AGENTcall 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 areason(voice_key_missing,agent_id_missing,transcription_key_missing,reasoning_key_missing),providerandleg, before the contact is created or the call written: no call, nocall.queued, nocall.failed. A test call is held to the same check. New error code. - **
availabilityon the agent.**GET /v1/agents[/{agentId}]readsavailability: { runnable, reason }— whether a call with the agent would be admitted here now, in the samereasonvocabulary. - **
fromSourceon calls and everycall.*event**: where an outbound call'sfromcame from —request,organization_number,agent_number,carrier_accountorplatform;nullinbound. - **
payloadVersionon voice applications** (1or2; create and update take it). Payload 2 of the answer-URL request reads the call as the call resource does (see Changed). - **
unavailableReasonandgapson the call transcript.**unavailableReasonsays why a transcript isunavailable—disabled,too_short,processing_failed,stt_unavailableornot_recorded— andgaps: [{ startedAt, endedAt, phase }]lists when the call's speech-to-text was down (readable while the call is up; areadytranscript with gaps is a partial one). The outage is noted on the transcript, not sent as new webhook events.
Changed
- **A call with no
frompresents 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 aPROMOTIONALcall only), the oldest assignment first — with itsnumberId, 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: platformorcarrier_account). An agent-first call keeps the seat's allocated number first. To present a particular number, name it infrom. - Answer-URL payload 2 for every voice application made from today:
callhas the call resource'sid,from(the calling number) andto(the number dialled) whichever way the call goes — on an outbound callfromis your caller ID andtothe contact masked•••• ••3210— a lowercasedirection,livemode,numberIdandcontactId, and the request carriesversionandlivemode. 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 withPATCH /v1/applications/{applicationId}{ "payloadVersion": 2 }. - **An
AI_AGENTcall that fails after it was written is answered201** with that call (status: failed,failure.code: AI_PROVIDER_UNAVAILABLE), never a503naming no call; its replay with the sameIdempotency-Keyis that201withIdempotent-Replayed: true. - Saving an agent that could not take a call is refused (a tightened requirement):
/v1/agentsanswers422 MODEL_UNAVAILABLEwith thereason(an ElevenLabs voice with no ElevenLabs agent id isagent_id_missing), and a model neither the catalog lists nor its provider confirmed is400.MODEL_UNAVAILABLEfor a provider with no key now carriesreasontoo. Agents saved before keep working as they did, and say so inavailability. - **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 with422 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 the404too. - 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 inCALL_FLOW_INVALID'sissues.
Fixed
- Conferences on a test call. A live key's
POST /v1/conferenceson a test call is the unknown-call404 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: nullfor 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.
- **
Calls through a speech-to-text outage, caller IDs, event modes, test configuration kept apart
2026-11-06Added
- Every webhook event says its mode at the top level. Each delivery envelope — and each
GET /v1/eventsitem — carrieslivemodebesidetypeandid:falsefor test traffic (it reachestestendpoints only),truefor 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 thelivemodeof the resource indata; those copies stay. Awebhook.testdelivery carries its endpoint's mode. The SDKs' envelope types require it. - Outbound calls name their caller ID. An outbound call's
fromis the business number it presents to the contact, in E.164 — the request'sfrom, else the assigned agent's allocated number, else the channel account's own caller ID — andnumberIdis that number's id when it is in your inventory. Stored when the call is written, socall.queuedcarries it as every latercall.*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 ascall.summary.readyonce, aftercall.transcript.ready— so the event and the extraction can be built against before going live. The summary and extraction objects carrymock(alwaysfalseon a live call). - **
speechUnavailableoncall.gather.completed**:trueon atimeoutwhen the gather asked for speech and nothing could listen (see below). - **The live
gatheraction takes the flow verb's names.**timeoutSeconds,interDigitTimeoutSecondsandspeechTimeoutSecondsare accepted as aliases oftimeoutSec,interDigitTimeoutSecandspeechTimeoutSec; a name and its alias together is400 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-onlygatherthat nothing can listen to ends at once and takes itsonTimeoutbranch (an answer URL'sresultsaysspeechUnavailable: true); adtmf_speechgather listens for keys alone. AnAI_AGENTcall whose AI cannot start still fails, now asfailedwithfailure.code: AI_PROVIDER_UNAVAILABLEinstead 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'sGET /v1/agents,/v1/call-flowsor/v1/applications, and every route of one — read,PATCH,DELETE, a flow'sarchive,versionsandpublish, an application'srotate-secret, an agent'stool-secret— is404 NOT_FOUND, as an unknown id. A/v1queue naming a test flow asoverflowFlowIdis400 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'sPOST /v1/messageswith a test conversation'sconversationId(the sandbox's thread, a test contact's) is404 CONVERSATION_NOT_FOUND(was409 NO_SENDER_AVAILABLE); a test key's on a live customer's thread the same (was422 TEST_MODE_UNSUPPORTED); areplyToMessageId/reaction.messageIdnaming a message of the other mode404 REPLY_TARGET_NOT_FOUNDeither way — the body an unknown id gets. - **Whole numbers are
integerin the contract.** Limits, durations, counts, versions and minor-unit amounts were typednumber; onlylatitude,longitude,confidenceanditemPriceare fractional. The Go SDK's fields areint/*int(Limit: trovacast.Ptr(50)), and a call flow'sDefinitionis a typed*CallFlowDocument(the contract marks each call-flowdefinitionwithx-document: CallFlowDocument). - **The test-call cap names its count
testCalls.** A test call over the sandbox's cap is429 CALL_CONCURRENCY_LIMITwithlivemode: falseandtestCalls(wasliveCalls, added the day before); the live caps keepliveCalls. - **
GET /v1/membersleaves out platform staff** who hold no role in the organization (the platform administrator who created it was listed as a member).
Fixed
- **A
401names 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.
- Every webhook event says its mode at the top level. Each delivery envelope — and each
India SMS checked against DLT at every send, call ceilings held on every carrier, `null` refused on upserts
2026-11-06Changed
- 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). OtherwisePOST /v1/messages(andPOST /v1/verifyto an Indian number) answers409 SMS_SENDER_NOT_ALLOWED(country: "IN"), and a message already queued fails withSMS_SENDER_NOT_ALLOWEDinstead 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 gainIN, or the platform enables India — every active header without that registration goes back topending_verification(sms.sender.updated) until the platform activates it again. - **An
AI_AGENTcall ends at itsmaxDurationSecon every channel.** The line already playing is let out, then the call is hung up, and the call'shangupreads{ 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
BRIDGEon a channel whose bridge takes no per-call limit — is priced at the deployment's call time limit, so a402 BILLING_INSUFFICIENT_CREDITmay come sooner while one is up. - **Client voice: a token that binds
callerIdsplaces a call that names nofromfrom its first bound number** — never your organization's default caller ID. A token that binds none is unchanged. - **
GET /v1/membersanswerspresence: nullto 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_goneondlt.contest.updatedandsms.sender_contest.updatedmeans the value your claim waits on became free; it never says what happened to the holder.
Fixed
POST /v1/contactson an existing contact answeredattributes: nullwith a500and silently reset the name ondisplayName: null.nullindisplayName,email,externalReferenceorattributesis now400 VALIDATION_FAILED; leave a field out to keep it (PATCH /v1/contacts/{contactId}clearsexternalReference).POST /v1/verificationsansweredcountry: nullwith a500;nullincountryorversionis now400 VALIDATION_FAILED.
- 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
Teams and members, both ends of a call, calls admitted by mode
2026-11-06Added
- Teams and members.
GET /v1/teams(teams:read) andGET /v1/members(members:read), read-only and cursor-paged: the team idsPOST /v1/queuestakes, and the seat ids a queue's members and a BRIDGE call'sbridge.to.agentMembershipIdtake, with each member's display name, email masked (a•••@example.com), status, roles, teams and deskpresence. A test key reads the same rows (Teams and members). - Both ends of a call. The call resource — and so
call.inboundand everycall.*event — carriestoandnumberId: an inbound call'stois your number the caller dialled (international format) andnumberIdits id; an outbound call'stois the contact masked to the last four digits (•••• ••3210). An inbound call'sfromis now the caller, masked the same way (it wasnull); an outbound call'sfromis unchanged. - Conversations say their mode. Every conversation carries
livemode(falsefor a test contact's thread or one on the platform's test sender). - A credit refusal of a call (
402 BILLING_INSUFFICIENT_CREDIT) carriesinFlightMinutesand, when a shorter call would be placed now,maxDurationSecAvailable— the longestmaxDurationSecthat fits. - A test call over the sandbox's own cap is
429 CALL_CONCURRENCY_LIMITwithlivemode: 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, andVerifyWebhook— 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 shortermaxDurationSecwhen 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 a404. - 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.openedfires for WhatsApp only; SMS and email threads open the same way.
- Teams and members.
Sender values belong to their business: claims survive the holder, rejections stick, voice headers follow their number
2026-11-06Added
dlt.contest.updated(dlt:read) andsms.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 voice403 VOICE_CALLER_ID_NOT_ALLOWED. POST /v1/voice/access-tokens:purpose(what the token's calls are for, defaultTRANSACTIONAL) andcallerIds(thefromnumbers its calls may use — your own assigned voice numbers), bound into the token and echoed ingrants.
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:placerefusesrespectCallingWindowandpurpose(400 VALIDATION_FAILED): a client call always keeps to the calling window and takes its purpose from the token. A new socket is refusedclient:revokedservice_unavailablewhen the platform cannot count connections (caps are now exact across replicas).
`null` means clear, or it is refused
2026-11-06Changed
- **
nullin a nested orPUTfield is refused — a tightened requirement.** On everyPATCHandPUT, a field nested in an object (voice,tracking, …) or in an array's elements (members[]), and everyPUTfield, takesnullonly where the contract declares itnullable; anywhere else it is400 VALIDATION_FAILED. Twenty fields readnullas "left as it is" or as their default —PATCH /v1/email/domains/{domain}withtracking: { opens: null }left open tracking on. They arevoice.voiceId,reasoning.providerandtranscription.modelon/v1/agents(create and update),marketing,updates,textShownandcapturedAtonPUT /v1/contacts/{contactId}/consent/{channel},tracking.opensandtracking.clicks(andtrackingmust be an object), and a member'spriorityandskilland the list'sversiononPUT /v1/queues/{queueId}/members. To keep a value, leave the field out.
- **
A sensitive gather pauses every recording of the call, or does not run
2026-11-06Added
GET /v1/calls/channelsanswerssensitiveGatherper channel: whether asensitivegather 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 newIdempotency-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 with409 RECORDING_NOT_CONTROLLABLEand nothing is collected. A flow's sensitivegatherthat is refused fails its run (FLOW_ERROR;call.flow.failednamesflow.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.
Test traffic stays on test endpoints, examples that run, AI agents before provider keys
2026-11-06Added
- AI agents in test mode without provider keys. A test key's
GET /v1/modelsalso lists themockprovider'smock-voiceandmock-reasoning(testOnly: true; every model now carriestestOnly). A test agent on them (voice: { provider: "mock", model: "mock-voice" }) is created and itsAI_AGENTtest 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 needssubaccounts:read; not your subaccount is404). The answer'ssubaccountIdnames whose spend it is (nullfor your own). contact.consent.updated,conversation.openedandconversation.resolvedcarrydata.livemode(see Fixed).GET /v1/numbers/availableanswerswarnings[](see Changed).hangup.sidevalueapplication, andhangup.reasonvalueshangup_verb,instructions_ended,ai_ended,callback_requested,flow_failedandcaller_hung_up(see Fixed).- An inbound call routed to a call flow or a voice application fills
flow(source: call_flowwithcallFlowId, orsource: applicationwithapplicationId); it readflow: 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),validateCallFlowandcreateCallFlowVersion(a menu flow) andupdateSubaccount(rename, suspend).
Changed
- A supplier that cannot be searched no longer fails the number search.
GET /v1/numbers/availableanswers the inventory and every carrier that answered, and names each one it could not search inwarnings[](code: NUMBER_SUPPLIER_UNAVAILABLE,supplier,orderable— whether you could have ordered its stock —retryAfterSeconds). It is503 NUMBER_SUPPLIER_UNAVAILABLEonly when nothing could be searched (every carrier asked failed and the inventory has nothing that matches). - **
hangup.sidereports only a recorded ending — a correction.** A completed call that nothing recorded an ending for readcontact; it now readsunknown. The platform records its own endings first (your API hang-up andhangupframe asagent; a flow's or answer URL's own hang-up asapplication; the ceiling, a lost agent or a failed flow asplatform; the caller leaving a running flow ascontact), so what readsunknownis 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 avoice_140orvoice_160header 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 staysreservedandpendingsays 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
modetakesTEST/LIVE(asGET /v1/menames a key's mode) as well astest/live. - A test call's transcript: only a test call an AI agent runs (
mode: AI_AGENT) gets the sandbox's scripted conversation. AFLOW,BRIDGEorEXTERNAL_AGENTtest call is not scripted — nothing spoke — and readsunavailable(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'sconversation.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 asdata.livemode. - Sandbox replies. A test key replying on the sandbox's thread by
conversationId, or reacting to its messages with no recipient, was refused409 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(noprovider),PATCH /v1/numbers/{id}(onlyversion),POST /v1/sandbox/inbound-messages(no customer; asubjecton WhatsApp),validateCallFlowandcreateCallFlowVersion(an empty definition), a consent write recording no decision, andPATCH /v1/subaccounts/{id}with nothing to change. - A flow's or answer URL's
hangupverb read as the contact hanging up. - Docs: a flow's
aiverb 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 liveEXTERNAL_AGENTcall.
- AI agents in test mode without provider keys. A test key's
A contract that describes itself: webhooks, docs links, every operation
2026-11-06Added
- The webhook catalog is in the contract.
x-webhooks(OpenAPI 3.0 has nowebhookskeyword; the shape is 3.1's) lists every event type as the signedPOSTit is — itsTrovacast-Signature,Trovacast-Event-IdandTrovacast-Event-Typeheaders, the scopes that read it (x-required-scopes),x-opt-inforcall.transcript.segment— and its delivery body as a component schema:WebhookEvent<Name>(the envelope;message.sent→WebhookEventMessageSent) with itsdataasWebhookEvent<Name>Data, embedding the same resource schemas the reads answer with.webhook.testis listed too. - Errors link to their docs. Every
/v1error envelope carriesdocUrl: the code's row on the developer site's errors page (https://trovacast.com/developers/errors#code-api-key-scope-missing; aMETA_<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-onlystays the flag of the routes that refuse it themselves).
Changed
- Call-flow validation names the problem. A verb written
{ "type": "say" }answers "unknown fieldtype— a verb is named byverb(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 ("missingtext(a string)", "expected one ofcompleted,rejected,busy"); branch targets andconnect.toname their forms.422 CALL_FLOW_INVALID'smessagecarries the first issue (The flow does not validate: definition.nodes.main.0: …);issues(path,message) is unchanged in shape. - Response documentation corrected:
createAgent/updateAgentanswer409 AI_AGENT_NAME_TAKEN/AI_AGENT_VERSION_CONFLICT(notCONFLICT);hangupCall,markMessageReadand the conference participant and end operations declare the422 TEST_MODE_UNSUPPORTEDthey answer;createOrganizationdeclares409 ORGANIZATION_ERASING; creating an application or a call flow never answersTEST_MODE_UNSUPPORTED. - Descriptions link to the developer site (
https://trovacast.com/developers/…) instead of naming repository files.
- The webhook catalog is in the contract.
Client voice for your own app, honest test transcripts
2026-11-06Added
- 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 scopevoice: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 rulePOST /v1/callsapplies (theoutgoinggrant needscalls:write), is rung by a number routed to it or any flow'sconnect, 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 withidentity(null on every other kind). - Call flows:
connecttakesto: { client: "<identity>" }.
Changed
- A test-mode
EXTERNAL_AGENTcall no longer gets the scripted transcript (no segments,call.transcript.segmentorcall.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/participantswithto.callIdstays 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.
- Client voice: your own app — a web page or a native app — places and answers calls as one identity of your organization.
Sender registration, MMS, and loose ends
2026-11-06Added
- DLT registrations over the API.
GET /v1/dlt/entities,POST /v1/dlt/entities,GET/PATCH/DELETE /v1/dlt/entities/{id},POST /v1/dlt/headersandGET/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 scopesdlt:readanddlt:write(live keys only); new eventsdlt.entity.updatedanddlt.header.updated; codesDLT_ALREADY_REGISTERED,DLT_REGISTRATION_CLAIMED,DLT_REGISTRATION_LOCKED,DLT_VERSION_CONFLICT. - SMS senders are writable.
POST /v1/sms/sendersregisters a DLT header or alphanumeric sender ID (pending until the platform activates it),GET /v1/sms/senders/{id}reads one andDELETE /v1/sms/senders/{id}removes one. New scopesms:manage(live keys only); new eventsms.sender.updated(sms:read) for every status a sender reaches; codesSMS_SENDER_ALREADY_REGISTERED,SMS_SENDER_CLAIMED. - WhatsApp senders.
GET /v1/whatsapp/sendersandGET /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/messageswithchannel: "sms",type: "mms"sends one JPEG or PNG (media.urlormedia.id, at most 5 MB) with optionaltext, 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"onGET /v1/pricing). Anywhere else is422 SMS_MMS_UNSUPPORTEDwithcountry, before anything is created; the message readstype: "mms"with itsmediablock. Test keys send to the SMS sandbox. - PDF statements.
GET /v1/invoices/{period}.pdf, orGET /v1/invoices/{period}withAccept: 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/availablefails with503 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=falsesearches the platform's own stock alone; it is now read correctly from the query string (falsewas read as true).GET /v1/pricinglists 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 (exotelon most deployments) and the internalsimchannel are no longer listed.voice[].provideris one of the channels/v1/callscan name.POST /v1/numbers/{id}/sms-senderregisters a US or Canadian number aspending_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.updatedreports both.
- DLT registrations over the API.
Examples that work, every code published, paperwork for every number
2026-11-06Added
GET /v1/modelsmarks each modelavailable: 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, withprovider,legandmodel) 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),CallFlowVerband oneCallFlowVerb<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,createCallActionandcreateTemplate. 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 theAllowheader andallowin the body (it was404). - Codes the API already answered with are now in
PublicApiErrorCodeand 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_TARGETandWHATSAPP_SANDBOX_NOT_IMPLEMENTED— and the newMODEL_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
modeandpurpose, consentsourceand a WhatsApp template'scategory— accept either case (ai_agentorAI_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_LOAon file for those types (VERIFICATION_DOCUMENTS_REQUIRED). - A body that is not valid JSON is answered with a
requestIdlike every other error. - A
429says how long to wait (Too many requests — retry after 17 s). - A nested field's validation message names its path once (
to.phone, notto.to.phone). - A template message naming neither
template.idnortemplate.nameis 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.
Voice and AI depth
2026-11-06Added
- AI inside call flows: the
aiverb, andconnectwithto: { 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 (itshand_backtool) or passes them to a person (transfer_to_person, offered when the step hasonEscalate). The step's outcome is theaivariable (ended,handed_back,escalated,max_duration,failed); an agent that cannot run takesonEscalate(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 with422 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, andGET /v1/calls/{callId}/transcript/streamserves the transcript as Server-Sent Events (resumable withLast-Event-ID,endonce final, at most 20 open streams per project). Nothing said while asensitivegather is open is transcribed. A test call's transcript is the sandbox's scripted conversation, with its events andcall.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); eventsverify.approvedandverify.expired; scopesverify:readandverify: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 is123456. New error codesVERIFY_*. - Lookup:
GET /v1/lookup/{phone}(lookupPhoneNumber, new scopelookup:read) answers whether a number is valid (withinvalidReasonwhen 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;carrieris in the shape butavailable: false— no carrier names without a vendor. The number in the path is never stored or logged. New error codePHONE_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) andPUT /v1/queues/{queueId}/members(setQueueMembers), under the new scopesqueues:readandqueues: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 aversioncompare-and-set. Writes are live-only. Error codesTEAM_NOT_FOUND,QUEUE_VERSION_CONFLICT,QUEUE_NAME_TAKENandQUEUE_IN_USEare now published (QUEUE_NOT_FOUNDanswers 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, andcall.inboundfires 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,aiAgentIdset) 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.
- AI inside call flows: the
Security fixes: voice reach defaults to the home market
2026-11-06Changed
- Calls reach the home market only by default — a changed default. A call placed to a contact (console, campaigns, sequences,
POST /v1/callsin 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 is422 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_PRICEDotherwise) — never the home rate. +1 keeps its rules (opened per organization, your TCPA acknowledgement, the TCPA calling window). Transfers, conference parties andBRIDGEnumbers keep their own list (childLegPrefixes). Self-hosted deployments can widen the default withVOICE_DEFAULT_DESTINATION_COUNTRIES(never1). DESTINATION_BLOCKEDcarries nocountryCallingCodewhen the number's country could not be read at all (it is refused, not guessed).
Added
GET /v1/settings/destinationsanswersdefaultCountryCodes— the home market every call to a contact may reach with nothing opened.
Fixed
POST /v1/messageschecks 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 answered401without its body being read, and a body declared past 12 MB is a413before 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 with413(/v1/messages13 MiB,/v1/media17 MiB, KYC documents 11 MiB, every other/v1route 1 MiB).- A number routes only to a live AI agent:
PATCH /v1/numbers/{id}withroute.kind: ainaming a test agent (one a TEST key created) is a400, 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_clearedaudit 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_RESTRICTEDif it was queued before — and its sender readsrestricteduntil 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 sameIdempotency-Keyused to replay itstoolSigningSecret. - Inbound email through SES is held to the same sender check as SendGrid: a mail whose
From:domain publishes no DMARC policy (SES'sGRAY), 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_LIMITEDwithRetry-Afterpast 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: transactionalmust carry its one-time code (4 to 10 digits), else400. - 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.
- Calls reach the home market only by default — a changed default. A call placed to a contact (console, campaigns, sequences,
Call outcomes name the organization's own wrap-up code
2026-11-06Added
- The call summary's
outcome(GET /v1/calls/{callId}/summaryandcall.summary.ready) carriescodeandlabel: 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);valuestays the standard outcome the code counts as. Both arenullfor a standard outcome and for the AI's verdict.
- The call summary's
Try messaging before KYC
2026-11-06Added
- 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.comfor email). See Try messaging before KYC. warningson 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/templatescreates 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 containingrejectis rejected,pendingstays pending, anything else is approved at once), announced astemplate.updatedto 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) andGET /v1/sandbox/emails/{messageId}(getSandboxEmail), scopemessages: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), scopemessages:write, test keys only — a test contact "writes" on WhatsApp, SMS or email;message.receivedgoes to test endpoints, a WhatsApp one opens the 24-hour window, an SMSSTOP/STARTmoves the test contact's SMS consent. - Test broadcasts: with a test key,
POST /v1/broadcastsbroadcasts 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:writeandbroadcasts: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).
- 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 (
Subaccounts; top-ups over the API
2026-11-06Added
- Subaccounts (
/v1/subaccounts, scopessubaccounts:readandsubaccounts: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 gaintransfer_inandtransfer_outlines. - Top-ups over the API (
POST /v1/balance/top-ups,GET /v1/balance/top-ups/:id, scopebilling: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 refusalsBILLING_TOP_UP_BELOW_MINIMUM,BILLING_TOP_UP_ABOVE_MAXIMUM,BILLING_PAYMENTS_UNAVAILABLE;VERIFICATION_REQUIREDgainsfeature: "subaccounts".
Changed
billing:managenow also starts top-ups (it still never moves credit by itself: the payment does).
- Subaccounts (
AI agents that do real work; onboarding without the console
2026-11-06Added
- AI agents (
POST/PATCH /v1/agents) takefirstMessage,firstSpeaker(agentorcaller),language(BCP 47),endCallPhrases,maxTurns,toolsandextraction, and every agent answers them (withtoolSigningSecretLast4). - Tools: functions an agent calls mid-call, answered by your HTTPS endpoint — a signed
agent.tool_callPOST (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 astoolSigningSecret;POST /v1/agents/{agentId}/tool-secret(rotateAgentToolSecret) rotates it. - Post-call extraction: an agent's
extraction.schemais applied to each finished call's transcript; the result isextractiononGET /v1/calls/{callId}/summaryand incall.summary.ready. - KYC over the API:
POST /v1/verifications(saveVerification),POST /v1/verifications/{verificationId}/documents(uploadVerificationDocument) andPOST /v1/verifications/{verificationId}/submit(submitVerification), under the new scopeverifications:write— available to test keys, since a pre-KYC organization holds only test keys.GET /v1/verificationsanswers the verification'sidandversion. livemodeon contacts:falsefor 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:writeis no longer refused whole for test keys); on a live contact it is still422 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_AGENTorEXTERNAL_AGENTcall is admitted while the organization's AI-call switch is off (a test call never reaches a carrier); a live one is still409 AI_CALLS_DISABLED. - An error's
path(and amessagequoting a URL) keeps the query string, with only sensitive values replaced by[redacted].
Fixed
recordresumeon a call its carrier records answers409 RECORDING_NOT_CONTROLLABLE, aspausedoes.call.queuedalways carriescall.status: queued, also for a test call (it readinitiating).
- AI agents (
SMS outside India, status callbacks, media uploads, scheduled sends, conversation triage, more WhatsApp message types
2026-11-06Added
- SMS outside India. To any country the platform has enabled (beyond India),
POST /v1/messageswithchannel: "sms"takes free text —type: "text"withtextandsms.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/senderslists it withkind: "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 codesSMS_SENDER_NOT_ALLOWEDandSMS_SENDER_REGISTRATION_REQUIRED(409, withcountry) — the United States and Canada take registered numbers only — and the same failure codes at send time. - Per-request status callbacks.
statusCallback: { url, events? }onPOST /v1/messagesandPOST /v1/callsPOSTs 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 withPOST /v1/status-callback-secret(shown once) and read withGET /v1/status-callback-secret. New error codeSTATUS_CALLBACK_SECRET_MISSING(409). - Media uploads.
POST /v1/media(multipart) uploads a file once; send it withmedia: { id }on a WhatsApp media message, any number of times for 7 days.GETandDELETE /v1/media/{id}. - Scheduled sends.
sendAtonPOST /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 carryscheduledAt. New error codeMESSAGE_NOT_CANCELABLE(409). - Conversation triage.
POST /v1/conversations/{id}/assign(to a member byuserIdoremail, oruserId: null),…/resolveand…/reopen, with the new scopeconversations:writeand an optionalversioncheck. Conversations carryassignedUserId,assignedAt,resolvedAtandversion;conversation.openedgainsreason: "api". New error codesCONVERSATION_CHANGED(409) andASSIGNEE_NOT_A_MEMBER(422). - WhatsApp message types.
type: "location"(location),type: "contacts"(contacts), and interactivecta_url(a button that opens a link) andflow(a button that opens a WhatsApp Flow).
Changed
sms.headeron a message is nullable (an SMS the platform vendor sent from its default sender).SMS_TEMPLATE_REQUIREDis now answered only for free text to an Indian number; a free-text SMS withoutsms.categoryis400 VALIDATION_FAILED.
- SMS outside India. To any country the platform has enabled (beyond India),
Voice reach: per-organization destinations, +1 with TCPA
2026-11-06Added
GET /v1/settings/destinations(settings:read): the country calling codes your calls may not reach (+1by default), the ones the platform opened for your organization, the prefixes a leg dialled from a live call (transfer, conference party,BRIDGEnumber) may go to — each markedneedsRatewhen 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) andDESTINATION_CALLING_WINDOW_CLOSED(409, withnextAllowedAt: 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: falseincluded).
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.
Speech gather, agent-first click-to-call
2026-11-06Added
gather(aPOST /v1/calls/{callId}/actionsaction and a flow verb) takesinput:dtmf(default),speechordtmf_speech, withlanguage,hintsandspeechTimeoutSec(speechTimeoutSecondsin a flow). What the caller said arrives asspeech: { text, confidence }oncall.gather.completed(besideinput) and in an answer URL'sresult. Asensitivegather stays keys-only and never hears speech. A deployment without speech recognition answers422 CALL_ACTION_UNSUPPORTED(reason: speech_recognition_unavailable).bridge.ringFirstonPOST /v1/calls(mode: BRIDGE):contact(default) oragent— 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/channelssays which channels can (agentFirst); a seat with no phone on file is422 AGENT_PHONE_REQUIRED. Calls read back withbridge.ringFirst.
Changed
- A flow
gathermay take speech only; it used to be refused.
Numbers: read one, order carrier stock, port in, SMS long codes
2026-11-06Added
GET /v1/numbers/{numberId}reads one number you hold.- Supplier stock you can order:
GET /v1/numbers/availablenames each number'sprovider, and a carrier's stock isorderable(at your plan's number price) once the platform resells that carrier and your plan prices the number. Order it withPOST /v1/numbers{ number, provider }: it is held, bought from the carrier when it activates, and charged like any number. Error codesNUMBER_NOT_PRICED,NUMBER_SUPPLIER_ORDER_FAILED(nothing charged; retry or cancel the hold) andNUMBER_SUPPLIER_ORDER_IN_PROGRESS. - Port-in:
POST /v1/numbers/port-requests(your numbers, their current carrier and aNUMBER_LOAdocument from your business verification),GET /v1/numbers/port-requests,GET /v1/numbers/port-requests/{id},POST /v1/numbers/port-requests/{id}/cancel, and thenumber.port_request.updatedevent (numbers:read). CodesPORT_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-sendermakes one of your SMS-capable numbers outside India an SMS sender (NUMBER_SMS_UNSUPPORTEDotherwise);GET /v1/numbers?capability=smslists the candidates.
Changed
POST /v1/numberstakes exactly one ofnumberId(withversion) ornumber(withprovider);numberIdandversionare no longer required on their own.
Transfer a live call to a queue
2026-11-06Added
transferonPOST /v1/calls/{callId}/actionstakesto: { 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.transferredcarriestransfer.target: queueandtransfer.queueId.- Error codes
QUEUE_NOT_FOUND(404) andQUEUE_CLOSED(409).
Changed
- A flow's
connectto 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).
Voice security: onward legs are dialled calls; caller IDs are your own
2026-11-06Changed
- A
transferto a number, a flowconnectto a number and an answer-URLconnectasking formode: "release"now all run asbridge: 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 (
fromonPOST /v1/calls,callerIdonconnectand on atransfer) 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 with422 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).
- A
Test mode: build configuration with a test key; test and live data kept apart
2026-11-06Added
- 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.livemodeon every call flow, application and agent. mode(live|test) on webhook endpoints, and as an optional field onPOST /v1/webhook-endpoints(a key may name only its own mode). Atestendpoint receives the events of test traffic only, aliveendpoint live events only.x-live-onlyin 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 arelive. A live call naming a test flow, application or agent answers its usual not-found code.
- A test key creates call flows, voice applications and AI agents of its own: they read
AI over the API: transcripts, summaries, AI inbound routes, the AI-call switch
2026-11-06Added
GET /v1/calls/{callId}/transcript: the call's transcript, oldest first and paginated — final segments with theirspeaker(contact,agent,ai, …), offsets and text (spoken phone numbers masked to their last four digits) — with astatus(pending,ready,unavailable).GET /v1/calls/{callId}/summary: the AI's summary of a finished call, itsdisposition,sentiment,confidenceand anyfollowUpAt, and the call'soutcome(the agent's wrap-up, else the AI's verdict).- Events
call.transcript.ready(the call and a segment count — never the text) andcall.summary.ready(the call and the summary). route.kind: "ai"onPATCH /v1/numbers/{numberId}: an AI agent answers the number's inbound calls itself.GET /v1/settings/callsandPATCH /v1/settings/calls: whether the organization allows AI calls (aiCallsEnabled), switched with aversioncompare-and-set and audited against the key.- Scopes
transcripts:read,settings:read,settings:write; error codesSETTINGS_VERSION_CONFLICTandAI_AGENT_IN_USE(archiving an AI agent a number routes to).
Voice: conferences, answering-machine detection, flow failures you can see, more reliable bridges
2026-11-06Added
- Conferences:
POST /v1/conferencesopens 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; eventsconference.participant.joined,conference.participant.left,conference.ended. machineDetectiononPOST /v1/calls(detect,detect_and_hangup) on a channel whosemachineDetectionistrue(Plivo, Twilio, Telnyx);422 MACHINE_DETECTION_UNSUPPORTEDelsewhere. The call carriesmachineDetection: { mode, result, detectedAt }, and the verdict (human,machine,unknown) arrives as the newcall.machine_detectedevent.call.flow.failed({ call, flow: { runId, code, step, verb, cause } }) when a call's flow fails; the call'sfailurecarries a documentedFLOW_*code whatever its status. Every call failure code is listed under Calls → "Call failure codes"./v1/agentstakes enum values in either case (openaiorOPENAI,autoorAUTO); lower case — what responses and/v1/modelsanswer — is canonical.
Changed
- A
FLOWorBRIDGEcall starts its flow once the contact has answered; on Airtel aconnectthat is the first verb was refused (the call ended at once) and now dials and bridges. - A stored flow, an inline definition or a
BRIDGEprompt/whisper/noAnswerMessagethat speaks text is refused when it is saved or placed on a deployment with no speech synthesis (CALL_FLOW_INVALIDwith the places, or503 TTS_UNAVAILABLEfor 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 ownmaxDurationSec.
- Conferences:
Two-way SMS, email tracking and inbound email, invoices, balance alerts, key rotation
2026-11-06Added
- Inbound SMS: a text to one of your SMS-capable numbers arrives as
message.received(channel: "sms") on the contact's SMS conversation, withsms.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.trackingon the message, and the eventsemail.openedandemail.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}andGET /v1/invoices/{period}/csv: monthly statements of the prepaid balance.PATCH /v1/balancesets the low-balance threshold (scopebilling:manage), and thebalance.lowevent.chargeon calls and messages once rated.POST /v1/me/rotate: a key rotates itself, the old secret valid for an overlap.
- Inbound SMS: a text to one of your SMS-capable numbers arrives as
Voice: call flows, AI agents, click-to-call, live-call actions, numbers and usage
2026-11-06Added
POST /v1/callsruns 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;fromtakes your own numbers from the inventory first.- The call graph on every call:
parentCallId,rootCallId,legRole, andpurpose,aiAgentId,flow,bridge;GET /v1/calls?include=legsand?rootCallId=.GET /v1/calls/channelsreportsflows. 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-flowswith 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/callskeeps listing the calls you placed, and lists the legs withinclude=legs(orrootCallId).
Changed
agentonPOST /v1/callsis required withmode: EXTERNAL_AGENTonly (it was required always; a relaxation).
Email, SMS, broadcasts and webhook recovery
2026-10-28Added
- Email through
POST /v1/messages(channel: "email"): templates or text,cc/bccand attachments on transactional email, sending domains (/v1/email/domains) and the suppression list (/v1/email/suppressions), with themessage.complainedevent. - SMS through
POST /v1/messages(channel: "sms") on India's DLT: SMS templates on/v1/templates(channel: "sms"), DLT headers onGET /v1/sms/senders, the promotional sending window and ansmsblock on the message. - Consent on every channel:
GETandPUT /v1/contacts/{contactId}/consent/{channel}for WhatsApp, email and SMS. - Broadcasts:
POST /v1/broadcastssends 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/eventsandGET /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/requestslists what a key did in the last seven days.- Calls:
GET /v1/calls(the list),GET /v1/calls/channels,GET /v1/calls/{callId}/recordingandDELETE /v1/calls/{callId}/recording, and a caller ID (from) onPOST /v1/calls. - The
conversation.opened,conversation.resolved,message.media.readyandmessage.media.failedevents. - Every error code the API answers with is published as
PublicApiErrorCodein the contract, and the standardX-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Resetheaders report the key's budget.
Changed
- Subscribing an endpoint to an event needs the scope that reads what the event carries (
messages:readformessage.*,calls:readforcall.*, and so on);webhooks:managealone no longer reads any event. - A 5xx on a write that may already have acted is stored against its
Idempotency-Keyand replayed (Idempotent-Replayed: true); retrying with the same key returns the same error. Endpoints that are safe to run again are markedx-idempotent-rerunin the contract. - The
X-RateLimit-*-apiKeyheaders are deprecated in favour of the unsuffixed ones.
- Email through
Calls
2026-10-12Added
POST /v1/callsplaces a call and streams its audio to your own agent over a WebSocket;GET /v1/calls/{callId}andPOST /v1/calls/{callId}/hangup.- The
call.queued,call.ringing,call.answered,call.completed,call.failed,call.no_answer,call.busyandcall.recording.readyevents.
The v1 API
2026-10-06Added
- API keys as bearer tokens, with per-key scopes, per-key rate limits,
Idempotency-Keyon every write, cursor pagination and the OpenAPI contract atGET /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.
- API keys as bearer tokens, with per-key scopes, per-key rate limits,
Node.js SDK
Unreleased
UnreleasedAdded
- Call settings. Regenerated from the contract:
updateCallSettingstakesrecordingRequiredbesideaiCallsEnabled(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.
- Call settings. Regenerated from the contract:
0.4.0
2026-11-17A 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-incall.dtmf. - Staff-first click-to-call to your own phones. Regenerated from the contract:
bridge.to.phoneIdoncreateCall(one of the organization's own phones,/v1/phones, rung first withringFirst: "agent"or connected to the contact otherwise), andphoneIdwithtarget: "phone"on a call'sbridge. - 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),identifiersandjurisdictiononsaveVerification,business.jurisdiction,identifiers.last4ByKindandrequirements.profile/requirements.identifierson the verification, thetax_registrationdocument 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) oncreateOrganizationandupdateOrganizationand (payer,spendCap,spend) on the organization and ongetBalance;breakdownonlistUsageandorganizationIdon its rows;paidForon invoices; the error codesBILLING_SPEND_CAP_REACHED,BILLING_PAYER_NOT_CONFIGUREDandBILLING_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) andlistIntegrationEvents,getIntegrationEvent(/v1/integration/events), integration keys with the scopeorganizations:events;externalReferenceon stored events.TrovacastEventEnvelopegainsexternalReference(an integration's organization) andintegrationId(awebhook.testto an integration's endpoint). - Acting for an organization.
organizationon the client options and on each call's options (nullfor none) sendsTrovacast-Organization: an integration key holdingorganizations:actthen acts for that organization with the scopes the platform delegated to its integration.ACTING_ORGANIZATION_HEADERis exported. Regenerated from the contract:actingForandintegration.delegatedScopesongetMe,livemodeon the organization, the scopeorganizations: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,planIdandcountryoncreateOrganization;planIdandcountryon the organization; the error codesPRODUCT_LINE_NOT_OFFEREDandPLAN_NOT_OFFERED.
- A call flow's keys. Regenerated from the contract: a flow document takes
0.3.0
2026-11-16A package build for consumers outside this repository (the package is still not on npm):
pnpm packproduces a working, versioned tarball. Everything the API'sfeat/global-cpaaswork 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;livemodeon brands, campaigns, number assignments andsms.registration.updated'sregistration;mediaoncreateSandboxInboundMessage(a test MMS) andreplyon its result (the HELP answer). - Regenerated from the contract:
sandboxoncreateCall(test keys): the script a test call's other side plays once answered, andmachine, 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 codeSANDBOX_NUMBER_NOT_ROUTED.getCallRecordinganddeleteCallRecordingtake 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 packbuilds and smoke-testsdist/first (prepack), andpnpm pack:checkproves 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:
acknowledgeTcpaandwithdrawTcpa(POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key —tcpa.statementon the destination settings, and the error codeDESTINATION_STATEMENT_OUTDATED. - Regenerated from the contract:
fallbackFlowIdon a voice application (createApplication,updateApplication) — the call flow run when its answer URL is down — and the call timeline'sapplication.fallbackentry (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— thenumber.port_out.updatedwebhook event and the error codesPORT_OUT_NUMBER_NOT_PORTABLE,PORT_OUT_NOT_OPEN,PORT_OUT_INVALID_TRANSITIONandPORT_OUT_VERSION_CONFLICT; a port request'srejectionandcompletedNumbers, andpreviousStatusonnumber.port_request.updated. - Regenerated from the contract:
orderNumberorders by place —countrywithareaCodeorprefix,type,sms— and takesreference,metadataandorderId(the order's own id, for good; answered asorderId); a number carriesreferenceandpendingCompliance,updateNumbertakesreferenceandlistNumbersfilters by it; thenumber.updatedwebhook event (a carrier's compliance review settled); the error codesNO_NUMBERS_AVAILABLE,NUMBER_PENDING_COMPLIANCE,NUMBER_ORDER_CONFLICTandNUMBER_ORDER_IN_PROGRESS. - Regenerated from the contract: US 10DLC registration —
createSmsBrand,listSmsBrands,getSmsBrand,createSmsCampaign,listSmsCampaigns,getSmsCampaign,assignSmsCampaignNumber,listSmsCampaignNumbers,getSmsCampaignNumber,removeSmsCampaignNumber— thesms.registration.updatedwebhook event, and the error codesSMS_REGISTRATION_REFERENCE_CONFLICT,SMS_REGISTRATION_CLOSED,SMS_NUMBER_NOT_ELIGIBLEandSMS_NUMBER_ALREADY_ASSIGNED. - Regenerated from the contract:
getSmsSettingsandupdateSmsSettings(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 itsindex, also onmedia), andgetMessageMediatakesindex. - Regenerated from the contract:
cancelCalls(POST /v1/calls/cancel),notAfteroncreateCall,onMachineonaiAgent, and the error codeCALL_NOT_AFTER_PASSED. - Regenerated from the contract:
optOutonaiAgent, a number'sairoute and a flow'saiverb (the built-in opt-out), and thecall.ai.opt_outand opt-incall.dtmfwebhook events. - Regenerated from the contract:
transferonaiAgentand a number'sairoute (a hand-off to a person), and thecall.ai.transferwebhook event (WebhookEventCallAiTransfer). - Regenerated from the contract:
createCall'saiAgenttakesfirstMessage,instructions,toolsandsession(the session webhook asked when the conversation starts), and the call takesreference(read back asreference); a number'sairoute takesai; a call flow'saiverb takesfirstMessage,instructions,tools,sessionandonUnavailable; the error codeAGENT_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:
metadataon a number (updateNumbersets it) and themetadatafilter onlistCalls. - Regenerated from the contract:
ringingoncall.ringingandansweredByoncall.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.readywebhook event (WebhookEventCallVoicemailReady,calls:readandtranscripts:read) — a caller's message with itsrecordingId,keyandtranscript; andkeyoncall.missed'smissed.voicemail. verbs.connect(and a builder's.connect) takes a list of targets in place ofto—ConnectTarget: exactly one ofnumber,agentorclient, with its owntimeoutSeconds,skipwindows andreference— rung bystrategy(sequentialorsimultaneous) withintotalTimeoutSeconds, withconfirmandnotice. Regenerated from the contract:noticeonrecord;notice,keysandreplyonvoicemail;purposeandnoticePlayedon a call's recording;recordingIdongetCallRecording. Behaviour a client meets is in the API changelog's Unreleased entries.- Regenerated from the contract: the
call.missedwebhook event (calls:read, dataWebhookEventCallMissedData) — 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 codesOWN_PHONE_IS_CARRIER_NUMBERandOWN_PHONE_LIMIT_REACHED. - Regenerated from the contract:
calledPartyTimeZoneoncreateCall— 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
airoute options,metadata,reference,pendingComplianceandwarnings, a summary'smock, a transcript'sgapsandunavailableReason, an application'spayloadVersionandfallbackFlowId, the call settings'liveCallLimits).
- Regenerated from the contract:
0.2.0
UnreleasedAdded
- (2026-11-07, Round 13) Regenerated from the contract:
deleteAgentresolves to the archived agent with itswarnings(PublicAgentDto; it resolved toundefined— the API answered204);updateCallSettingsanswerswarnings(PublicAgentNumberWarningDto[], while AI calls are off); and onPublicAgentNumberWarningDto,flowIdanddetail. 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.ratedwebhook event (WebhookEventCallRated,calls:read) — the call with itschargeonce it is rated. A call is rated after its finalcall.*event, which carriescharge: 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) andreasonon a call'scharge(PublicCallChargeDto, also the timeline'sratedentry); the warning codeAI_AGENT_UNAVAILABLEand the reasonsAI_CALLS_DISABLED,AGENT_INACTIVE,TEST_AGENTonPublicNumberWarningDto; andwarnings(PublicAgentNumberWarningDto: the number's warning plusnumberId) on the agentupdateAgentanswers 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 (schemasPublicCallTimelineEventDto,PublicCallTimelineDataDto,PublicCallTimelinePageDto; page it withclient.paginate('listCallEvents', { path: { callId } })); and on the phone number'swarnings, the codeAI_PROVIDER_UNAVAILABLEbesideBILLING_RATE_UNAVAILABLEand the fieldsagentId,reasonandstep(PublicNumberWarningStepDto:node,index). Behaviour a client meets — anunratedcall 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:
warningson the phone number (schemaPublicNumberWarningDto:code: BILLING_RATE_UNAVAILABLE,direction,provider,callType,message— a route your plan does not price, saved all the same), andAI_PROVIDER_UNAVAILABLEamong the422s ofcreateCallAction(atransferto a call flow whose AI agent cannot speak here;agentIdnames it). Behaviour a client meets: a refused inbound call is afailedcall with aBILLING_*orAI_AGENT_UNAVAILABLEfailure.codeand firescall.failed; a call with nofrompresents 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_UNAVAILABLEerror code (TrovacastErrorCode; anAI_AGENTcall whose agent cannot speak here, refused before anything is written —reason,provider,leg),availability: { runnable, reason }on agents,fromSourceon calls (where an outbound call'sfromcame from),payloadVersionon voice applications (answer-URL payload 2; payload 1 is deprecated), andunavailableReasonandgapson call transcripts. Behaviour a client meets: a call with nofrompresents your own number on the channel; a call of the other mode is a404on 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
livemodeon every webhook envelope (TrovacastEventEnvelope.livemode, required byparseWebhookEvent/constructWebhookEvent),mockon the call summary and its extraction,speechUnavailableoncall.gather.completed'sgather,fromandnumberIdon outbound calls,testCallson the sandbox's concurrency refusal; whole-number fields are typedintegerin the bundled contract (anumberin TypeScript either way), and each call-flowdefinitionnames its document (x-document: CallFlowDocument). - (2026-11-06) Regenerated from the contract:
listTeamsandlistMembers(GET /v1/teams,GET /v1/members) with theirTeam/Membertypes;livemodeon every conversation;toandnumberIdon every call (an inbound call'sfromis now the caller, masked); the newteams:readandmembers:readscopes. Additive. - (2026-11-06, Round-7 security fixes) Regenerated from the contract: the
dlt.contest.updatedandsms.sender_contest.updatedevent types (a claim'soutcome:opened,holder_gone,awarded,dismissed); the error codesDLT_REGISTRATION_CONTESTED,DLT_REGISTRATION_REJECTED,SMS_SENDER_CONTESTEDandSMS_SENDER_REJECTED;purposeandcallerIdsoncreateVoiceAccessToken(request andgrants). The voice client'sreadyevent carries the token'spurposeandcallerIds. - (2026-11-06) Regenerated from the contract:
sensitiveGatheron everylistCallChannelsitem (whether asensitivegather can run on the channel's recorded calls), andRECORDING_PAUSE_FAILEDinTROVACAST_ERROR_CODES(a sensitive gather whose carrier did not confirm it paused its recording). - (2026-11-06) Regenerated from the contract:
livemodeon thecontact.consent.updated,conversation.openedandconversation.resolvedevent data;warningson thesearchAvailableNumbersanswer (NUMBER_SUPPLIER_UNAVAILABLE, per supplier);testOnlyon everylistModelsitem and themockprovider for test agents;subaccountIdonlistUsage(query and answer); theapplicationhang-up side; a subaccount key'smodein either case; named request examples fororderNumber,updateNumber,createSandboxInboundMessage,validateCallFlow,createCallFlowVersionandupdateSubaccount. Additive: aswitchoverhangup.sideneeds the new member (or itsdefaultbranch). - (2026-11-06) Webhook event types from the contract.
WebhookEventDataMap— and soTrovacastEvent'sdatapertype— is generated from the contract's webhook catalog (x-webhooks), as areWEBHOOK_EVENT_TYPESand the newWEBHOOK_EVENT_SCOPES(the scopes each type needs) andOPT_IN_WEBHOOK_EVENT_TYPES; every delivery body is also a named schema (Schemas['WebhookEventMessageSent'], itsdataSchemas['WebhookEventMessageSentData']). The readable aliases (CallTransferInfo,ConsentUpdateSource, …) are kept, now derived from it. - (2026-11-06)
TrovacastApiError.docUrl: where the error'scodeis 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:VoiceDeviceconnects with a client-voice access token (createVoiceAccessToken, new), places calls (device.call), is rung (incoming), and eachVoiceCallanswers, rejects, mutes, holds, sends DTMF and hangs up;browserAudio()is the default audio in a browser. No dependencies. The contract gains thevoice:clientscope, number routes of kindclient(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); thedlt.entity.updated,dlt.header.updatedandsms.sender.updatedevents;type: "mms"on SMS sends; the codesDLT_ALREADY_REGISTERED,DLT_REGISTRATION_CLAIMED,DLT_REGISTRATION_LOCKED,DLT_VERSION_CONFLICT,SMS_SENDER_ALREADY_REGISTERED,SMS_SENDER_CLAIMEDandSMS_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_*) andMODEL_UNAVAILABLE; models carryavailable; the call-flow schemas (CallFlowDocument,CallFlowAnswerDocument,CallFlowVerb*) are typed; request bodies takemode,purpose, consentsourceand templatecategoryin either case. - (2026-11-06) Call-flow builders.
callFlow()andanswer()(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 throwsCallFlowValidationErrorwith every issue's path.validateCallFlow/validateAnswerDocumentcheck any document against the contract'sCallFlow*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 typesVerify,VerifyCheck); eventsverify.approved,verify.expiredand the opt-incall.transcript.segment; scopesverify:read,verify:write; error codesVERIFY_*. 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 typePhoneNumberLookup);listQueues,createQueue,getQueue,updateQueue,setQueueMembers,deleteQueue(friendly typesQueue,QueueMember); scopeslookup:read,queues:read,queues:write; error codesPHONE_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 (nullfor a standard outcome and the AI's verdict). - Messaging sandbox (2026-11-06):
listSandboxEmails,getSandboxEmail,createSandboxInboundMessage;warningson every message,livemodeon every template; theSANDBOX_TEST_KEY_REQUIREDerror code. - (2026-11-06) Subaccounts:
createSubaccount,listSubaccounts,getSubaccount,updateSubaccount,getSubaccountUsage,createSubaccountTransfer,createSubaccountApiKey,revokeSubaccountApiKey, thesubaccounts:read/subaccounts:writescopes; top-upscreateTopUp/getTopUp; statement linestransfer_in/transfer_out; the new error codes. - Voice reach and numbers (2026-11-06):
getDestinationSettings;gatherinput(dtmf|speech|dtmf_speech) withlanguage,hintsandspeechTimeoutSec, andspeech: { text, confidence }oncall.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 thenumber.port_request.updatedevent; the new error codes. - **
trovacast listen** (the package'sbin;npx @trovacast/sdk listen --forward-to <url>): forwards the organization's webhook events to a local handler by pollingGET /v1/events, oldest first and once each, re-signed with a localwhsec_listen_…secret.@trovacast/sdk/listenexports 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.
transferactionto.queueId(a transfer to a call queue), thecall.transferredtransfer.queueIdfield, and the error codesQUEUE_NOT_FOUNDandQUEUE_CLOSED.- (2026-11-06) AI agents that do real work:
createAgent/updateAgenttakefirstMessage,firstSpeaker,language,endCallPhrases,maxTurns,toolsandextraction;rotateAgentToolSecret; the call summary'sextraction. Verify a tool call withverifyWebhookSignatureand the agent's tool-signing secret (the same scheme as a webhook). - (2026-11-06) KYC over the API:
saveVerification,uploadVerificationDocument(send aFormDatabody) andsubmitVerification, theverifications:writescope, andid/versionon the verification;livemodeon contacts. - README: how to run
trovacast listenbefore the package is on npm.
Changed
- (2026-11-07, Round 13)
PublicAgentNumberWarningDto.provider(the warningsupdateAgent,deleteAgentandupdateCallSettingsanswer) isPublicCallProvider | null: a key withoutnumbers:readis told onlynumberId,codeandreason(detail: false), the rest null. Checkdetail(orprovider !== 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.
PlaceCallOptionsno longer hasrespectCallingWindoworpurpose: a client call always keeps to the organization's calling window, and its purpose is bound into the access token by your server (purposeoncreateVoiceAccessToken). An older client that still sends either is refusedVALIDATION_FAILED.frommust be one of the token'scallerIdswhen it binds any (VOICE_CALLER_ID_NOT_ALLOWED). A new connection may be refusedservice_unavailable(retry with backoff). - (2026-11-06) Event
datatypes follow the contract, which corrects two that had drifted from what the API sends:CallTransferInfo.targetmay be'queue'(withqueueId), andConversationOpenedReasonmay be'api'. Aswitchover either needs the new member (or itsdefaultbranch). - An error the API replayed from its idempotency store is final. The API now stores a 5xx outcome against the
Idempotency-Keywhen the endpoint may already have acted (every write exceptPOST /v1/messages,POST /v1/messages/{messageId}/read,DELETE /v1/contacts/{contactId}andDELETE /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 andIdempotent-Replayed: true. The client no longer retries such an error — it is thrown after the attempt that received it, withretryable: 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: whenerror.idempotentReplayedistrue, 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, andupdateWebhookEndpointwhen it changes the URL or the events, answer403 API_KEY_SCOPE_MISSINGunless the key holds, for every event the endpoint will carry:messages:readformessage.*(message.receivedalsocontacts:read),contacts:readforcontact.consent.updated,templates:readfortemplate.updated,whatsapp:readforwhatsapp.account.updated,calls:readforcall.*(call.recording.readyalsorecordings:read, as before).listEvents/getEventwithhold the events the key cannot read the same way (atypefilter on one is a 403).webhooks:managealone 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.senderIdis nowmessage.sms.header** (the DLT header text). The request'ssenderIdstays the sender's id; list them withlistSmsSenders. SMS shipped unreleased, so no integration should depend on the old name. - **The external-agent
startframe'stois an object** —{ phone, last4 };phoneis the full number only when the call was placed withto.phone,nullfor a call placed bycontactId. - 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 aFormDatawith the file infile; the client sends it asmultipart/form-data),getMedia,deleteMedia;cancelMessagefor a message scheduled withsendAt;assignConversation,resolveConversation,reopenConversation;getStatusCallbackSecret,rotateStatusCallbackSecretandstatusCallbackoncreateMessage/createCall; free-text SMS outside India (sms.category), WhatsApplocation,contactsand interactivecta_url/flow. The new error codes are inTROVACAST_ERROR_CODES. - Conferences (voice).
createConference,getConference,addConferenceParticipant,updateConferenceParticipant,removeConferenceParticipant,endConference, theConference,ConferenceParticipantandConferenceParticipantAddedtypes, and theconference.participant.joined|leftandconference.endedevents. - Answering-machine detection and failed flows (voice).
createCalltakesmachineDetection('detect','detect_and_hangup'); the call carriesmachineDetection { mode, result, detectedAt }; the eventscall.machine_detectedandcall.flow.failed(with the exportedCallFlowFailure) are inWEBHOOK_EVENT_TYPESand narrow by type;MACHINE_DETECTION_UNSUPPORTEDis inTROVACAST_ERROR_CODES. Agent enums accept either case ('openai'or'OPENAI'). - Voice:
createCalltakesmodeFLOW(a call flow, inline or stored, or a voice application's answer URL),AI_AGENT(aiAgent.agentId) andBRIDGE(click-to-call, the contact dialled first) besideEXTERNAL_AGENT, andpurpose; calls carryparentCallId,rootCallId,legRole,aiAgentId,flowandbridge, andlistCallstakesinclude: 'legs'androotCallId.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, …) andlistModelsoperations; the eventscall.inbound,call.held,call.resumed,call.transferredandcall.gather.completed(CallTransferInfo,CallGatherResult); friendly typesCallAction,CallActionResult,Application,ApplicationWithSecret,CallFlow,CallFlowVersion,CallFlowValidation,Agent,AgentWithInstructions,Model; and the voice error codes. - Numbers, billing and business verification:
listNumbers,searchAvailableNumbers(inventory priced, supplier stocknull-priced and not orderable),orderNumber(anumber_order: activated, or held with the refusal it met inpending),activateNumber,updateNumber(label, inboundroute, voice DLT header — oneversion),releaseNumber;getBalance,listUsage(per UTC day × channel × destination, at most 90 days),getPricing(the plan's cells as stored) andgetVerification(identifiers to their last four). Friendly typesPhoneNumber,AvailableNumber,NumberOrder,Balance,Usage,UsageRow,Pricing,Verification; error codesNUMBER_VERSION_CONFLICTandNUMBER_NOT_ASSIGNED. - AI over the API:
getCallTranscript(paginated:paginatewalks its segments),getCallSummary,getCallSettingsandupdateCallSettings(the AI-call switch, aversioncompare-and-set);updateNumbertakesroute.kind: 'ai'; the eventscall.transcript.ready(CallTranscriptReady: a count, never the text) andcall.summary.ready; friendly typesCallTranscript,TranscriptSegment,CallSummary,CallSettings; error codesSETTINGS_VERSION_CONFLICTandAI_AGENT_IN_USE. New scopestranscripts: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) andgetMessageMedia; per-channel consent (getChannelConsent,setChannelConsent); email domains and suppressions;listCalls,listCallChannelsandgetCallRecording;listEvents,getEvent,resendWebhookDeliveriesandlistApiKeyRequests; and, later in the round,updateTemplate(PATCH /v1/templates/{templateId}), email templates,cc/bcc/attachmentson email, the broadcasts operations, reactions, SMS senders,deleteCallRecording, caller-IDfromoncreateCall, the integration data-subject operations, andGET /v1/contacts?updatedAfter=. - The
message.complainedevent,start_keywordas a consent source, andcontact.consent.updatedtyped as the channel consent (PublicChannelConsentDto,consent.objectnaming the channel). - The
conversation.opened(with itsConversationOpenedReason:first_message,customer_reply,agent) andconversation.resolvedevents, each carrying thePublicConversationDto. - A message's
reaction,location,contactsandorderblocks (inbound reactions, shared locations, shared contact cards and catalog orders; a reaction's target is itscontext). - A message's
mediablock (kind,mimeType,fileName,sizeBytes,status—pending,ready,failed,rejected— andfailureCode; never a link), and themessage.media.ready/message.media.failedevents that say when a received file settled. - Sending a WhatsApp reaction (
type: "reaction"), filteringlistMessagesbymetadata(key:value, repeatable) andlistConversationsbychannel;createMessage404s name what is missing (CONTACT_NOT_FOUND,TEMPLATE_NOT_FOUND, …) and its refusals are typed (PublicSendRefusalDto). - A WhatsApp message that failed as
SUBMISSION_UNKNOWNcan later turnsent/delivered/readwhen Meta's statuses show it was accepted (itsmessage.sentfollows themessage.failed). TrovacastApiError.idempotentReplayed—truewhen 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, withchangedAtand itsconsenton 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
listEventsand 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 newPublicApiErrorCodeenum),KnownTrovacastErrorCode,TROVACAST_ERROR_CODE_FAMILIES(META_) andisKnownErrorCode(code).TrovacastApiError.codeis now typedTrovacastErrorCode— 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 readingcodeas astringworks as before. ApiResponse.rateLimit({ limit, remaining, resetSeconds }ornull), read from the standardX-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Resetheaders the API now sends, and therateLimitOf(headers)helper andRateLimitInfotype behind it. The suffixedX-RateLimit-*-apiKeyheaders are deprecated by the API and not read.- Package metadata for publishing (
repository,homepage,bugs,keywords,publishConfig), this changelog in the published files, and aprepublishOnlybuild. The package staysprivateuntil it is released (see CONTRIBUTING.md → Releasing).
- (2026-11-07, Round 13) Regenerated from the contract:
0.1.0
2026-10-06Added
- The first version, consumed inside the monorepo (
workspace:*): one typed method per operation of the v1 contract,withResponse,paginateandpages; anIdempotency-Keyon every write; retries with jittered exponential backoff that honourRetry-After;TrovacastApiError; webhook signature verification (verifyWebhookSignature,constructWebhookEvent) and typed events.
- The first version, consumed inside the monorepo (
Python SDK
0.1.0
UnreleasedAdded
- Call settings. Regenerated from the contract:
update_call_settingstakesrecordingRequiredbesideaiCallsEnabled(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-incall.dtmf. - Staff-first click-to-call to your own phones. Regenerated from the contract:
bridge.to.phoneIdoncreate_call(one of the organization's own phones,/v1/phones, rung first withringFirst: "agent"or connected to the contact otherwise), andphoneIdwithtarget: "phone"on a call'sbridge. - 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),identifiersandjurisdictiononsave_verification,business.jurisdiction,identifiers.last4ByKindandrequirements.profile/requirements.identifierson the verification, thetax_registrationdocument 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;billingoncreate_organization,update_organization, the organization and the balance;breakdownonlist_usage;paidForon invoices; the error codesBILLING_SPEND_CAP_REACHED,BILLING_PAYER_NOT_CONFIGUREDandBILLING_PAID_BY_INTEGRATION. - One webhook feed for an integration. Regenerated from the contract:
list_integration_webhook_endpoints,create_integration_webhook_endpointand the rest of/v1/integration/webhook-endpoints, andlist_integration_events/get_integration_event(/v1/integration/events) — integration keys with the scopeorganizations:events;externalReferenceon stored events. TheWebhookEventtyped dict gainsexternalReferenceandintegrationId(both optional). - Acting for an organization.
organization=onTrovacastandAsyncTrovacastsendsTrovacast-Organizationon every request: an integration key holdingorganizations:actthen acts for that organization with the scopes the platform delegated to its integration.ACTING_ORGANIZATION_HEADERis exported. Regenerated from the contract:actingForandintegration.delegatedScopesonget_me,livemodeon the organization, the scopeorganizations: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,planIdandcountryoncreate_organization's body;planIdandcountryon the organization; the error codesPRODUCT_LINE_NOT_OFFEREDandPLAN_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;livemodeon brands, campaigns, number assignments andsms.registration.updated'sregistration;mediaoncreate_sandbox_inbound_message(a test MMS) andreplyon its result. - Regenerated from the contract:
sandboxoncreate_call(test keys): the script a test call's other side plays once answered, andmachine, 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 codeSANDBOX_NUMBER_NOT_ROUTED.get_call_recordinganddelete_call_recordingtake 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_tcpaandwithdraw_tcpa(POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key —tcpa.statementon the destination settings, and the error codeDESTINATION_STATEMENT_OUTDATED. - Regenerated from the contract:
fallbackFlowIdon a voice application (create_application,update_application) — the call flow run when its answer URL is down — and the call timeline'sapplication.fallbackentry (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— thenumber.port_out.updatedwebhook event and the error codesPORT_OUT_NUMBER_NOT_PORTABLE,PORT_OUT_NOT_OPEN,PORT_OUT_INVALID_TRANSITIONandPORT_OUT_VERSION_CONFLICT; a port request'srejectionandcompletedNumbers, andpreviousStatusonnumber.port_request.updated. - Regenerated from the contract:
order_numberorders by place —countrywithareaCodeorprefix,type,sms— and takesreference,metadataandorderId(the order's own id, for good; answered asorderId); a number carriesreferenceandpendingCompliance,update_numbertakesreferenceandlist_numbersfilters by it; thenumber.updatedwebhook event (a carrier's compliance review settled); the error codesNO_NUMBERS_AVAILABLE,NUMBER_PENDING_COMPLIANCE,NUMBER_ORDER_CONFLICTandNUMBER_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 thesms.registration.updatedwebhook event. - Regenerated from the contract:
get_sms_settingsandupdate_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 itsindex, also onmedia), andget_message_mediatakesindex. - Regenerated from the contract:
cancel_calls(POST /v1/calls/cancel),notAfteroncreate_call,onMachineonaiAgent, and the error codeCALL_NOT_AFTER_PASSED. flows.aitakesopt_out. Regenerated from the contract:optOutonaiAgentand a number'sairoute, and thecall.ai.opt_outand opt-incall.dtmfwebhook events.- Regenerated from the contract:
transferonaiAgentand a number'sairoute (a hand-off to a person), and thecall.ai.transferwebhook event. flows.aitakesfirst_message,instructions,tools,sessionandon_unavailable: a step's own configuration and the session webhook. Regenerated from the contract:create_call'saiAgenttakesfirstMessage,instructions,toolsandsession, and the call takesreference(read back asreference); a number'sairoute takesai; the error codeAGENT_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:
metadataon a number (update_numbersets it) and themetadatafilter onlist_calls. - Regenerated from the contract:
ringingoncall.ringingandansweredByoncall.answered: who an inbound call's route rang and who took it;Noneon an outbound call's own events. - Regenerated from the contract: the
call.voicemail.readywebhook event (calls:read,transcripts:read) — a caller's message with itsrecordingId,keyandtranscript; andkeyoncall.missed'smissed.voicemail. flows.connecttakestargets(several parties, each exactly one ofnumber,agentorclientwith its owntimeoutSeconds,skipwindows andreference),strategy,total_timeout_seconds,confirmandnotice;tois optional (exactly one of the two).flows.recordtakesnotice;flows.voicemailtakesnotice,keysandreply. A call's recording carriespurposeandnoticePlayed, andget_call_recordingtakesrecording_id. Behaviour a client meets is in the API changelog's Unreleased entries.- (2026-11-07, Round 13) Regenerated from the contract:
delete_agentreturns the archived agent with itswarnings(Agent; it returnedNone— the API answered204);update_call_settingsanswerswarnings(AgentNumberWarning, while AI calls are off); and onAgentNumberWarning,flowIdanddetail, withprovidernowNonefor a key withoutnumbers:read(onlynumberId,codeandreasonare 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.ratedwebhook event (WebhookEventCallRated,calls:read) — the call with itschargeonce it is rated. A call is rated after its finalcall.*event, which carriescharge: 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, orNone) andreasonon a call's charge (CallCharge, also the timeline'sratedentry); the warning codeAI_AGENT_UNAVAILABLEand the reasonsAI_CALLS_DISABLED,AGENT_INACTIVE,TEST_AGENTonNumberWarning; andwarnings(AgentNumberWarning: the number's warning plusnumberId) on the agentupdate_agentreturns. 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;paginatepages it like every list); and on the phone number'swarnings(NumberWarning), the codeAI_PROVIDER_UNAVAILABLEbesideBILLING_RATE_UNAVAILABLEand the fieldsagentId,reasonandstep(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:
warningson the phone number (NumberWarning:code: BILLING_RATE_UNAVAILABLE,direction,provider,callType,message— a route your plan does not price, saved all the same), andAI_PROVIDER_UNAVAILABLEamong the422s ofcreate_call_action(atransferto 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_UNAVAILABLEerror code,availabilityon agents,fromSourceon calls,payloadVersionon voice applications (answer-URL payload 2; payload 1 is deprecated), andunavailableReasonandgapson 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
livemodeon every webhook envelope (WebhookEvent["livemode"], required byparse_webhook_event),mockon the call summary and its extraction,speechUnavailableoncall.gather.completed,fromandnumberIdon outbound calls; whole-number fields areintin the generated types (limits, durations, counts, versions, minor units). - (2026-11-06) Regenerated from the contract:
list_teamsandlist_members(GET /v1/teams,GET /v1/members),livemodeon every conversation,toandnumberIdon every call (an inbound call'sfromis now the caller, masked), and theteams:read/members:readscopes. - (2026-11-06) Regenerated from the contract:
sensitiveGatheron every call channel (whether asensitivegather can run on the channel's recorded calls), and theRECORDING_PAUSE_FAILEDerror code. - (2026-11-06) Regenerated from the contract:
livemodeon thecontact.consent.updated,conversation.openedandconversation.resolvedevent data,warningson the number search,testOnlyon models (and the test-modemockprovider),subaccount_idonlist_usage, theapplicationhang-up side, and the new named request examples. - (2026-11-06)
TrovacastApiError.doc_url: where the error'scodeis documented on the developer site (Nonefor an SDK code or an answer without one). - (2026-11-06)
WEBHOOK_EVENT_SCOPES(the scopes each event type needs) andOPT_IN_WEBHOOK_EVENT_TYPES, from the contract's webhook catalog (x-webhooks); every delivery body is a TypedDict introvacast.types(WebhookEventMessageSent, itsdataWebhookEventMessageSentData, …). - (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, scopevoice: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 takekind: "client"withidentity; flows'connecttakesto: {"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); thedlt.entity.updated,dlt.header.updatedandsms.sender.updatedevents;type: "mms"on SMS sends; the codesDLT_ALREADY_REGISTERED,DLT_REGISTRATION_CLAIMED,DLT_REGISTRATION_LOCKED,DLT_VERSION_CONFLICT,SMS_SENDER_ALREADY_REGISTERED,SMS_SENDER_CLAIMEDandSMS_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_*) andMODEL_UNAVAILABLE; models carryavailable; the call-flow schemas (CallFlowDocument,CallFlowAnswerDocument,CallFlowVerb*) are TypedDicts; request bodies takemode,purpose, consentsourceand templatecategoryin either case. - (2026-11-06) Call-flow builders.
trovacast.flows:CallFlowBuilderandAnswerBuilderbuild stored flows and answer documents with one chained method per verb (snake_case keyword arguments for the API's camelCase fields;set_andswitch_), a function per verb, and the branch helpersnode()/url();to_dict()validates and raisesCallFlowValidationError(aValueError) with every issue's path.validate_call_flow/validate_answer_documentcheck any document against the contract'sCallFlow*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; eventsverify.approved,verify.expiredand the opt-incall.transcript.segment; error codesVERIFY_*. 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 codesPHONE_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 (Nonefor a standard outcome and the AI's verdict). - (2026-11-06) Messaging sandbox.
list_sandbox_emails,get_sandbox_email,create_sandbox_inbound_message;warningson every message,livemodeon 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_upandget_top_up; thesubaccounts:read/subaccounts:writescopes, thetransfer_in/transfer_outstatement lines and the new error codes. - (2026-11-06) AI agents that do real work.
create_agent/update_agenttakefirstMessage,firstSpeaker,language,endCallPhrases,maxTurns,toolsandextraction;rotate_agent_tool_secret; the call summary'sextraction. A tool call is signed like a webhook: verify it withtrovacast.webhooks.verify_webhook_signatureand the agent's tool-signing secret. - (2026-11-06) KYC over the API.
save_verification,upload_verification_documentandsubmit_verification, theverifications:writescope, andid/versionon the verification;livemodeon contacts. - Messaging.
upload_media(body=FileUpload(content, file_name, content_type))— the exportedFileUploadis sent asmultipart/form-data—get_media,delete_media;cancel_messagefor a message scheduled withsendAt;assign_conversation,resolve_conversation,reopen_conversation;get_status_callback_secret,rotate_status_callback_secretandstatusCallbackoncreate_message/create_call; free-text SMS outside India, WhatsApplocation,contactsand interactivecta_url/flow. The new error codes are inTROVACAST_ERROR_CODES. - Voice reach and numbers (2026-11-06):
get_destination_settings;gatherinput(dtmf|speech|dtmf_speech) withlanguage,hintsandspeechTimeoutSec, andspeech: { text, confidence }oncall.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 thenumber.port_request.updatedevent; the new error codes. - Conferences (voice).
create_conference,get_conference,add_conference_participant,update_conference_participant,remove_conference_participant,end_conference, theConferencetypes, and theconference.*events. - Answering-machine detection and failed flows (voice).
create_calltakesmachineDetection("detect","detect_and_hangup"); the call carriesmachineDetection;call.machine_detectedandcall.flow.failedare inWEBHOOK_EVENT_TYPES;MACHINE_DETECTION_UNSUPPORTEDis inTROVACAST_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_callwithFLOW,AI_AGENTandBRIDGE,create_call_action, the applications, call-flows, agents andlist_modelsmethods — and AI over the API:get_call_transcript(walk it withpaginate),get_call_summary,get_call_settings,update_call_settings,route.kind: "ai"onupdate_number, and thecall.transcript.ready/call.summary.readyevents):TrovacastandAsyncTrovacast, one keyword-only method per operationId (snake_case, e.g.create_message,get_whatsapp_consent),with_response(ApiResponsewithstatus,headers,request_id,idempotency_key,idempotent_replayed,rate_limit),paginateandpages. - The Node SDK's transport rules: an
Idempotency-Keyon every write (a fresh UUID per call, reused by its retries;idempotency_key=Falsesends none and disables retries); retries of timeouts, network errors,429,500/502/503/504and409 IDEMPOTENCY_KEY_IN_FLIGHTwith equal-jitter exponential backoff that honoursRetry-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_CODESandis_known_error_code.- TypedDicts for every component schema (
trovacast.types), andWEBHOOK_EVENT_TYPES. trovacast.webhooks:verify_webhook_signature,construct_webhook_event,parse_webhook_event,create_webhook_signature_headerandTrovacastWebhookError, checked against the documented signature vector.- A generator (with
--check) that regenerates the typed surface fromopenapi.json.
- Call settings. Regenerated from the contract:
Go SDK
0.1.0
UnreleasedChanged
GetMessageMediatakes a*GetMessageMediaParamsbefore its options: an incoming MMS may carry several files, andIndexpicks one. Passnilfor the first file (what it fetched before):c.GetMessageMedia(ctx, id, nil). Regenerated from the contract withMediaItemsandMedia.Indexon a message.CallFlowVerbConnect.Tois a*CallFlowVerbConnectTo: aconnectnow takes exactly one ofToorTargets(several parties, rung byStrategy), soTois nil on a connect that ringsTargets. WriteTo: &trovacast.CallFlowVerbConnectTo{…}where you wrote the value, and check it for nil when reading a document. Regenerated from the contract withTargets,Strategy,TotalTimeoutSeconds,ConfirmandNoticeonconnect,Noticeonrecord,Notice,KeysandReplyonvoicemail, andPurposeandNoticePlayedon a call's recording.- (2026-11-07, Round 13)
DeleteAgentreturns(*Agent, error)instead oferror: the API answers the archived agent with itsWarnings(it answered204). Replaceerr := c.DeleteAgent(ctx, id)with_, err := c.DeleteAgent(ctx, id), or read the warnings. - (2026-11-07, Round 13)
AgentNumberWarning.Provideris a*AgentNumberWarningProvider: nil for a key withoutnumbers:read, which is told onlyNumberID,CodeandReason(Detailfalse). CheckDetailbefore dereferencing it. - (2026-11-07, Round 11)
NumberWarning.Codeis aNumberWarningCodeinstead of astring: 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 astringvariable needsstring(w.Code). - (2026-11-06, Round 9)
WebhookVerifier.Secretsis aWebhookSecrets, built withtrovacast.WebhookSecretsOf(current, previous)instead of a[]stringliteral: 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 anyfmtverb (%vdid;%pand verbs fmt does not know print a struct's fields without calling its methods), inslogor inencoding/json. A verifier prints as its count of secrets and tolerance. ReplaceSecrets: []string{a, b}withSecrets: trovacast.WebhookSecretsOf(a, b).
Added
- Call settings. Regenerated from the contract:
UpdateCallSettingstakesRecordingRequiredbesideAICallsEnabled(either or both), the organization's "Record every call" policy; both are*boolnow (each is optional), soAICallsEnabled: truebecomes 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-incall.dtmf. - Staff-first click-to-call to your own phones. Regenerated from the contract:
PhoneIDon the call's bridge target (createCall'sbridge.to: one of the organization's own phones,/v1/phones, rung first withringFirst: "agent"or connected to the contact otherwise), andPhoneIDwith targetphoneon 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),IdentifiersandJurisdictiononSaveVerification,Business.Jurisdiction,Identifiers.Last4ByKindandRequirements.Profile/Requirements.Identifierson the verification, thetax_registrationdocument 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;BillingonCreateOrganization,UpdateOrganization, the organization and the balance;BreakdownonListUsage;PaidForon invoices; the error codesBILLING_SPEND_CAP_REACHED,BILLING_PAYER_NOT_CONFIGUREDandBILLING_PAID_BY_INTEGRATION. - One webhook feed for an integration. Regenerated from the contract:
ListIntegrationWebhookEndpoints,CreateIntegrationWebhookEndpointand the rest of/v1/integration/webhook-endpoints, andListIntegrationEvents/GetIntegrationEvent(/v1/integration/events) — integration keys with the scopeorganizations:events;ExternalReferenceon stored events.WebhookEventgainsExternalReference(an integration's organization) andIntegrationID(awebhook.testto an integration's endpoint). - Acting for an organization.
WithOrganization(client) andForOrganization(per call;""for none) sendTrovacast-Organization: an integration key holdingorganizations:actthen acts for that organization with the scopes the platform delegated to its integration.ActingOrganizationHeadernames the header. Regenerated from the contract:ActingForandIntegration.DelegatedScopesonGetMe,Livemodeon the organization, the scopeorganizations: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,PlanIDandCountryonCreateOrganization;PlanIDandCountryon the organization; the error codesPRODUCT_LINE_NOT_OFFEREDandPLAN_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;Livemodeon brands, campaigns, number assignments andsms.registration.updated'sRegistration;MediaonCreateSandboxInboundMessage(a test MMS) andReplyon its result. - Regenerated from the contract:
SandboxonCreateCall's body (test keys): the script a test call's other side plays once answered, andMachine, 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 codeSANDBOX_NUMBER_NOT_ROUTED.GetCallRecordingandDeleteCallRecordingtake 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:
AcknowledgeTCPAandWithdrawTCPA(POST/DELETE /v1/settings/destinations/tcpa) — the organization's TCPA acknowledgement given by its key —TCPA.Statementon the destination settings, andErrorCodeDestinationStatementOutdated. - Regenerated from the contract:
FallbackFlowIDon a voice application (CreateApplication,UpdateApplication) — the call flow run when its answer URL is down — and the call timeline'sapplication.fallbackentry (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(answersNumberPortOutUnlockwith the account number and the transfer PIN, once),CancelNumberPortOut,ListPortOuts(andListPortOutsIter),GetPortOut— thenumber.port_out.updatedwebhook event (WebhookEventNumberPortOutUpdated) and theErrorCodePortOut…codes; a port request'sRejectionandCompletedNumbers, andPreviousStatusonnumber.port_request.updated. - Regenerated from the contract:
OrderNumberorders by place —OrderNumber.CountrywithAreaCodeorPrefix,Type,SMS— and takesReference,MetadataandOrderID(the order's own id, for good; answered asNumberOrder.OrderID); a number carriesReferenceandPendingCompliance,UpdateNumbertakesReferenceandListNumbersfilters by it; thenumber.updatedwebhook event (WebhookEventNumberUpdated); the error codesErrorCodeNoNumbersAvailable,ErrorCodeNumberPendingCompliance,ErrorCodeNumberOrderConflictandErrorCodeNumberOrderInProgress. - Regenerated from the contract: US 10DLC registration —
CreateSMSBrand,ListSMSBrands,GetSMSBrand,CreateSMSCampaign,ListSMSCampaigns,GetSMSCampaign,AssignSMSCampaignNumber,ListSMSCampaignNumbers,GetSMSCampaignNumber,RemoveSMSCampaignNumber— and thesms.registration.updatedwebhook event. - Regenerated from the contract:
GetSMSSettingsandUpdateSMSSettings(GET/PATCH /v1/settings/sms) — the SMS HELP auto-reply (helpReply). - Regenerated from the contract:
CancelCalls(POST /v1/calls/cancel),NotAfteronCreateCall,OnMachineonaiAgent, and the error codeCALL_NOT_AFTER_PASSED. - Regenerated from the contract:
OptOutonaiAgent, a number'sairoute and a flow'saiverb, and thecall.ai.opt_outand opt-incall.dtmfwebhook events. - Regenerated from the contract:
TransferonaiAgentand a number'sairoute (a hand-off to a person), and thecall.ai.transferwebhook event. - Regenerated from the contract:
aiAgentonCreateCalltakesFirstMessage,Instructions,ToolsandSession(the session webhook asked when the conversation starts), and the call takesReference(read back asReference); a number'sairoute takesAi; a call flow'saiverb takesFirstMessage,Instructions,Tools,SessionandOnUnavailable; the error codeAGENT_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:
Metadataon a number (UpdateNumbersets it) and theMetadatafilter onListCalls. - Regenerated from the contract:
Ringingoncall.ringingandAnsweredByoncall.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.readywebhook event (calls:read,transcripts:read) — a caller's message with itsRecordingID,KeyandTranscript; andKeyoncall.missed's voicemail. - (2026-11-07, Round 13) Regenerated from the contract:
Warningson theCallSettingsUpdateCallSettingsreturns (while AI calls are off), andFlowIDandDetailonAgentNumberWarning. 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.ratedwebhook event (WebhookEventTypeCallRated,calls:read) — the call with itsChargeonce it is rated. A call is rated after its finalcall.*event, which carries a nilCharge. 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) andReasonon a call's charge (also the timeline'sratedentry);NumberWarningCodeAIAgentUnavailableand the reasonsNumberWarningReasonAICallsDisabled,NumberWarningReasonAgentInactive,NumberWarningReasonTestAgent; andWarnings([]AgentNumberWarning: the number's warning plusNumberID) on theAgentUpdateAgentreturns. 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.ListCallEventsandListCallEventsIter(GET /v1/calls/{callId}/events,calls:read) — a call's timeline, oldest first (CallTimelineEvent,CallTimelineEventType,CallTimelineData,CallTimelinePage); and onNumberWarning,AgentID,Reason(NumberWarningReason) andStep(*NumberWarningStep:Node,Index), with the codeAI_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:
WarningsonPhoneNumber(NumberWarning:CodeBILLING_RATE_UNAVAILABLE,Direction,Provider,CallType(NumberWarningCallType),Message— a route your plan does not price, saved all the same), andAI_PROVIDER_UNAVAILABLEamong the422s ofCreateCallAction(atransferto 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_UNAVAILABLEerror code,Availabilityon agents,FromSourceon calls,PayloadVersionon voice applications (answer-URL payload 2; payload 1 is deprecated), andUnavailableReasonandGapson 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 themintegernow; a call flow'sDefinitionis a*CallFlowDocument(x-documentin the contract), so a typed document is sent as it is, withoutAsObject;WebhookEvent.Livemode(required byParseWebhookEvent);Mockon the call summary and its extraction,SpeechUnavailableon the gather event,FromandNumberIDon 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):
NewClientand oneClientmethod per operationId in Go case (CreateMessage,GetWhatsAppConsent,ListSMSSenders), taking a context, the path parameters, a<Method>Paramsstruct 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,CallFlowVerband the other verb unions withMarshalJSON/UnmarshalJSON),Nullable[T]for the optional fields the API also accepts as null,Ptr,Filefor the two upload operations, andAsObject/FormatTime. - The Node and Python SDKs' transport rules: an
Idempotency-Keyon every write (a fresh UUID per call, reused by its retries;WithIdempotencyKey,WithoutIdempotencyKey); retries of timeouts, network errors,429,500/502/503/504and409 IDEMPOTENCY_KEY_IN_FLIGHTwith equal-jitter exponential backoff that honoursRetry-Afterup toWithMaxRetryAfter, 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 asctx.Err(). *APIError(Status,Code,Message,RequestID,DocURL,Retryable,RetryAfter,IdempotencyKey,IdempotentReplayed,Body,IsNotFound), theErrorCodeconstants of every documented code,KnownErrorCodes,IsKnownErrorCode,SDKErrorCodesandErrorCodeFamilies.WithResponseInfo(status, headers, request id, idempotency key, replay,RateLimit),RateLimitFromHeaderandParseRetryAfter.<Method>Iterfor every paginated read: anIteratorwithNext/Item/Err,Cursorto resume, andAllforrange.VerifyWebhook,WebhookVerifier(several secrets while you rotate),ParseWebhookEvent,CreateWebhookSignatureHeader,WebhookErrorand theWebhookEventTypeconstants,WebhookEventTypes,OptInWebhookEventTypesandWebhookEventScopesfrom 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 fromopenapi.json, standard library only.
Security
- (2026-11-06) Printing a
Clientnever shows the API key, under anyfmtverb (%son aClientvalue and%ton a pointer used to print it), by value or pointer, inside a struct, a slice, a map or an error:Clientimplementsfmt.Formatter,fmt.GoStringer,fmt.Stringerandslog.LogValuer(all printtrovacast.Client(<base URL>)), and holds the key where reflection cannot reach it. - (2026-11-06) A plain
http://base URL is refused withErrInsecureBaseURLunless 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 pointedWithBaseURLathttp://on another host, usehttps://. - (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_RESPONSEfor a 2xx,HTTP_<status>for an error) whose cause is the new*ResponseTooLargeError(Status,Limit;errors.Asfinds it throughAPIError.Unwrap).