Changelog

​

New Contacts, call tags and user status API endpoints

• Contacts: List and search contacts, Create a contact, Look up contacts, Bulk upsert contacts, Get a contact, Update a contact, Delete a contact, Add tags to a contact, Remove tags from a contact
• Contact tags: List contact tags, Create a contact tag, Rename a contact tag, Delete a contact tag
• Contact fields: List contact fields
• Call tags: List call tags, List a call’s tags, Add tags to a call, Remove tags from a call
• User status: List user statuses, Get a user’s status, Set a user’s status, List user status types

​

Know whether your messages arrived

• Why it failed: on not_delivered and failed, error.code gives the reason to act on (for example invalid_recipient or blocked), and error.message a sentence you can show your users.
• Pair it with message.sent: the event carries the status change only. Match it to the message on message_id, the same value as id on message.sent.
• Which messages: messages sent from your CloudTalk numbers. Messages you receive have no delivery status.

​

Choose where a VoiceAgent’s calendar invite goes

• Your own variable: set the booking skill’s invite e-mail to a variable you send in call_properties.system_prompt.variables of Initiate VoiceAgent call, for example {{customer_email}} in the dashboard for a customer_email you send, and the invite goes to the first valid e-mail in it (a single address, several separated by commas, or a list). Sending the variable alone does not change the skill: it keeps the variable it is set to. Outbound calls can then book without a CloudTalk contact.
• Your contact.* values now reach the invite too: a non-empty contact.emails you send replaces the contact’s e-mails for the invite, as it already did for what the agent is told. ct_call_context.contact in the analysis still shows the contact.
• Inbound calls carry only contact fields, so a variable of your own is always empty there and the agent offers the booking-link SMS instead.
• No e-mail, no booking in the call: when the variable is empty or holds no valid address, the agent does not book an event type that needs an e-mail and sends the booking link by SMS, if it has that scenario.

​

Outbound VoiceAgent calls know the contact they call

• Contact variables: {{contact.*}} variables in the prompt, greeting, skills and scenarios, and custom tools that reference contact fields, now receive the matched contact’s values on outbound calls. Before, they were empty. A call without a contact still gets empty values, unless you send your own (below).
• Your own values still win: a non-empty value you send for a contact.* variable in call_properties.system_prompt.variables (as a nested "contact": {"name": …} object or a flat "contact.name" key) replaces the matched contact’s value. An empty or blank value, null, or an empty array or object does not: the contact’s value is used. Your value changes what the agent is told, what it sends to custom tools and, for the variable the booking skill takes the invite e-mail from, where the calendar invite goes. The analysis’ ct_call_context.contact stays the matched contact’s.
• Post-call analysis: the analysis of an outbound call, including the Extract Information webhook payload, now carries the matched contact in ct_call_context.contact (id, name, emails), as it already did for inbound calls.
• Calendar invite: when the agent books on Calendly or Cal.com with the booking skill’s invite e-mail left at contact.emails, the matched contact’s first valid e-mail address receives the invite on outbound calls too.

​

Tell a VoiceAgent call which contact it is calling

• What the contact is used for: the {{contact.*}} variables, the ct_call_context.contact of the post-call analysis, and the calendar invite while the booking skill takes the invite e-mail from contact.emails. A non-empty contact.* value you send in call_properties.system_prompt.variables still wins for that variable in what the agent is told, what it sends to custom tools and, for the invite variable, where the invite goes; the analysis keeps the contact named by contact_id.
• New errors, only when you send contact_id: 422 with errors[].message contact_not_found (location body.contact_id) when the contact does not exist in your company, belongs to another company or was deleted; 503 contact_lookup_unavailable when the contact could not be looked up. In both cases no call is queued, so a 503 is safe to retry. Requests without contact_id behave as before.

​

Every MCP action runs on its first call

​

Receive a call’s post-call data in one webhook

• When: once per call, usually a few minutes after it ends: as soon as every part the call can have has arrived, or 30 minutes after the call ended, whichever comes first. Parts a call can’t have, such as voice_agent on a call no AI Voice Agent handled, are marked not_applicable instead of waited for. Data that arrives later is not added, and the event is not sent again.
• What is included: sources gives each part’s status (ready, not_applicable, timed_out or failed), and a part that is not ready is left out.
• Size: each delivery is at most 64 KB. Anything shortened or left out to fit is listed in truncated.
• Not in v1: a recording URL and an insights URL. Use the API by call_id.

​

Connect an AI assistant by signing in with CloudTalk

• Only users with the Admin role can sign in.
• An API key that the server refuses now answers 403 instead of 401. A 401 means no credentials, or an expired sign-in, and carries a WWW-Authenticate challenge that points clients to CloudTalk’s sign-in.

​

Manage webhook endpoints from the API

• Endpoints: list, create, get, update and delete, plus the event types you can subscribe to. A create returns the signing secret and accepts an Idempotency-Key: retrying with the same key and the same body returns the endpoint it already made instead of creating a second one.
• Signing secrets: read and rotate. A rotation returns the new secret and previousSecretExpiresAt: for 24 hours every delivery is signed with both secrets.
• Deliveries: send a test event, list deliveries, get one with its payload and every attempt, and retry a delivery. Payloads are kept for 30 days.

​

Ask your assistant how a campaign is performing

• The Analytics profile now covers campaigns. https://mcp.cloudtalk.io/analytics includes the new tool and cloudtalk_list_campaigns, so a reporting assistant can find a campaign and read its results. The Campaigns profile has the new tool too.
• Read-only, aggregate figures. No contact, agent or call is identified, and like every tool it only reaches your own company’s campaigns.
• Requires the new Sales Dialer add-on, like the other campaign tools.

​

Choose a voice agent’s provider and model directly

• resolvedProvider and resolvedLlm are removed. Read the new provider and llm attributes instead. llm is the canonical model id, such as openai - gpt-4o-mini, not a {provider, model} object.
• providerOverride and llmOverride are deprecated and no longer returned. Writes still accept them as aliases of provider and llm; when a request sends both, the alias wins.
• The server no longer changes an agent’s provider or model on its own. It picks them once at create. A replace that omits provider, llm or minorVersion keeps the stored value, and linking a knowledge base leaves them as they are.

• provider (elevenlabs or deepgram) and llm are writable and returned on every read, as null when the agent has none set. An llm the provider does not offer is rejected with 422 and the detail code LLM_OVERRIDE_NOT_AVAILABLE_FOR_PROVIDER.
• minorVersion is writable. A create takes 0 to the latest; a replace takes the stored value or the latest.
• optimizedSettings (read-only) lists the values CloudTalk recommends for the agent’s current setup: isAvailable, the changes as {path, from, to}, and effects. To apply them, set each path to its to value and replace the agent.

​

Archived dispositions can no longer be used on campaign buttons

• Get a campaign’s disposition buttons leaves out a button whose call tag is archived. Previously it was returned with its normal name, but an outcome recorded with it was never attached to the call.
• Replace a campaign’s disposition buttons rejects an archived tag_id with 422, the same as an unknown one.
• List disposition tags no longer lists archived dispositions.

​

Buttons for a deleted disposition are no longer returned

• A button whose call tag has been deleted is left out of the response. Previously it was returned with name, color and outcome set to null. Deleting a disposition in your account settings now removes it from every campaign, as the settings page states.
• null resolved fields now mean the call tags could not be read. While that lasts, every button is returned with name, color and outcome set to null. color is also null for a tag that has no colour.

​

Get real-time events pushed to your endpoint

• Overview covers setup, the shared event envelope, and the full catalogue of 22 event types.
• Verify signatures shows how to authenticate every delivery, in Node, Python, PHP and Go.
• Delivery and retries documents the retry schedule, automatic endpoint disabling, replay, and 30-day payload retention.
• Event references for calls, contacts, users, messages, Conversation Intelligence, AI Voice Agents and Dialer give every payload field with an example.

​

An undecodable pagination cursor is now a 400

• A cursor the Dialer cannot decode is rejected instead of ignored. It now answers 400 with code: "PAGINATION.INVALID_CURSOR". Until this release such a cursor was ignored and the endpoint returned 200 with the first page — the behaviour the 2026-09-02 entry below documented, and which that entry described as deliberate.

​

Deleted campaigns leave the default campaign list

• An unfiltered campaign list no longer returns deleted campaigns. Campaigns whose status is deleted are excluded when you send no status filter. Until v1.0.22 they were included, which is what the previous entry on this page documented — that was the behaviour at the time, and v1.0.22 changes it so the list matches what Delete a dialer campaign already promises: a deleted campaign drops out of the listings while its history stays available for reporting.

• include_deleted=true — a new optional boolean query parameter, default false. Set it to true and the list returns campaigns of every status, deleted included. Only the literal strings true and false are accepted; anything else is a 400.
• status=deleted — unchanged, and still the way to list only deleted campaigns. When status is set, include_deleted has no effect.

​

Stricter validation on the Dialer, and four corrections to these pages

• A whitespace-only name is rejected. name is now trimmed before it is validated on campaign, call-script and survey creates and updates, so " " is exactly as empty as "" and answers 400 with name should not be empty in subErrors. It previously created a resource whose name rendered blank everywhere it was shown.
• schedule_policy.start_date and start_time are format-pinned. start_date must be a real calendar date in YYYY-MM-DD, start_time a valid HH:MM or HH:MM:SS; anything else, including a date that does not exist such as 2026-02-30, is a 400 naming the field, for example schedule_policy.start_date must be a real calendar date in YYYY-MM-DD. A 31-12-2026 typo used to be stored and silently left the campaign with no scheduled start at all.
• Export filters are validated. On Request a campaign data export, filters.contactId and filters.userId must be 1 or greater, and filters.dateFrom / filters.dateTo must be strict ISO 8601 — otherwise 400. A window whose dateTo is not after its dateFrom now answers 422 with dateTo must be after dateFrom, and a bound that clears the strict ISO 8601 check but falls outside the published RFC 3339 date-time shape (the week date 2026-W33, for one) answers 422 with dateFrom must be a parseable ISO 8601 date-time — in both cases no job is enqueued; such requests used to be accepted and complete with a header-only file that looked like “no data”. Supplying only one bound is still valid: a missing end resolves to the time the job runs, a missing start to the campaign’s creation.
• The unmatched-route 404 body changed. A request to a path the Dialer does not route — DELETE /v1/dialer/surveys/{surveyId}, for instance — now answers the standard error envelope with the fixed message Route not found and a correlationId. It no longer echoes an internal path or your query string back to you. Every error the Dialer service itself raises carries a correlationId, this one included — errors answered before the request reaches the service, such as the auth layer’s 401, do not.

• A malformed jobId is a 400, not a 500. Get an export job’s status and Get a download link for a completed export answer 400 with Validation failed (uuid is expected) and a correlationId when jobId is not a UUID. Both operations now document that 400.

• List dialer campaigns returns soft-deleted campaigns. The page said they appear only when you filter with status=deleted. They do not: an unfiltered list returns every status, deleted included. Pass status if you need them left out.
• Policy bundles are not stored verbatim. The calling_policy description said a bundle read back may carry knobs added by a newer release. Unknown keys are dropped on write, so only the documented knobs are ever stored.
• An unknown outcome_kind is a 400, not a 422. On Replace a campaign’s disposition buttons, enum and shape violations are 400. The 422 is for a tag_id that is not a call tag on your account; a duplicated tag_id is 409.
• Association ids are not checked for existence. Replace a campaign’s associations accepts any ref_id for an agent, target tag or queue group without verifying that it exists — a nonexistent target tag is stored and simply contributes no contacts. Validate the ids on your side.

​

Connect AI assistants to CloudTalk

• Overview covers what MCP is, the tool profiles, and what each one is built for.
• Quickstart gets a client connected in five minutes.
• Tool reference lists every tool with its parameters, defaults and limits.

​

The Dialer partner API uses your standard API keys

​

A new home for the CloudTalk API docs

• Send requests from the page. Every endpoint has a playground. Fill in your own API keys and see the real response.
• Point your AI tools at the docs. There is an MCP server at https://developers.cloudtalk.io/mcp that lets an assistant search these pages directly. Every page also has a Copy page menu that hands the content to ChatGPT, Claude, Cursor, VS Code or Perplexity.
• Search across every page, and a dark mode that respects your system setting.