> ## Documentation Index > Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt > Use this file to discover all available pages before exploring further. # CloudTalk MCP Tool Reference > Every tool the CloudTalk MCP server exposes: parameters, defaults, and limits across calls, contacts, messaging, AI Voice Agents, campaigns, and account data. Every tool in the CloudTalk MCP catalogue, grouped by area. You don't call these by name (the assistant picks them), but this reference tells you what's possible and what each tool needs. The campaign tools need the Sales Dialer add-on; the rest are available on any MCP-enabled account. * Required parameters are shown in **bold**; everything else is optional. Defaults are noted in the description. * **Rate limit: 60 requests per minute per company** across all tools. A large job runs in batches; a `429` means wait a minute and continue. * A ⚠️ marks a write you cannot undo through the MCP (a deleted campaign, or a created contact / voice agent / knowledge base / AIVA tool that has no delete tool here). * Tools marked **Asks for confirmation** return a preview of what would happen instead of acting, and execute only when the call carries explicit confirmation. **Your assistant is what decides to show you that preview and ask.** CloudTalk does not remember that a preview was returned, so an assistant that confirms on its own behalf executes in one step — treat this as a review step your assistant honours, not a lock CloudTalk enforces. * The [Campaigns](#campaigns) tools require the new Sales Dialer add-on. * Call tags and contact tags are separate catalogs; an id from one is rejected by the other. * Every profile includes the [connection check](#connection) and the four [account lookups](#account-lookups). ## Calls & analytics ### cloudtalk\_search\_calls Find calls, newest first. Returns compact summaries (with tags as `{id, name}`); use `cloudtalk_get_call` for detail. Covers external calls only: internal agent-to-agent calls are not in this call log, so totals can read lower than the Dashboard, which counts them. Each row's `total_time` is a composite duration, not the connected time: ring plus talking plus wrap-up on an inbound call, talking plus wrap-up on an outbound one. The public API's `billsec` for the same call counts only the connected part, so the two do not match — compare `talking_time`, the closest counterpart. The first page also returns the total match count (`items_count`, `page_count`); later pages return rows only. You can page through up to 10,000 matching calls per search; to reach more, narrow the date range or add a filter. | Parameter | Type | Description | | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_from` | string | ISO datetime (UTC). Defaults so the search covers the last 3 months, the maximum window per search. Move the window back for older calls. | | `date_to` | string | ISO datetime (UTC), inclusive upper bound. | | `contact_id` | integer | Filter by contact. Matches the contact id frozen onto the call when it was logged. CloudTalk back-fills its own call records when a number is later attached to a contact; this index is not back-filled, so a per-contact total here can sit well below the same contact's figure in the Dashboard or the public API, and paging further will not close the gap. To cover every call on a number regardless of attribution, filter by `public_external` instead. | | `user_id` | integer | Filter by agent. | | `group_id` | integer | Filter by agent group. | | `voice_agent_id` | integer | Filter by AI Voice Agent. | | `tag_id` | integer | Filter by call tag. | | `country_code` | string | Filter by the **contact's** country as an ISO-2 code, e.g. `US`, not the dialled number's country. | | `direction` | string | `incoming` or `outgoing`. Internal agent-to-agent calls are not part of this call log, so there is no internal option. | | `status` | string | `answered` or `missed`. | | `sentiment` | string | Filter by the call's overall AI sentiment: `positive`, `negative`, or `neutral`. Only analysed calls carry a verdict, so a filtered total can read lower than the same window without it. | | `public_external` | string | Customer phone number. Matched as a substring, so a fragment such as the last six digits is enough; a full E.164 number is not required. | | `without_tags` | boolean | Only calls that have no tags. | | `call_id` | integer | Exact call; no date range needed. | | `limit` | integer | Results per page, up to 200. Default `50`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_get\_call\_insights AI summary, sentiment, topics, smart notes and talk-listen ratio for one call. | Parameter | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------ | | **`call_id`** | integer | CloudTalk call ID. | | `include` | array | Any subset of `summary`, `sentiment`, `topics`, `smart_notes`, `talk_listen`. Default: all five. | ### cloudtalk\_get\_call Full detail for one call: contact, agent, tags, timings, call flow, topics, sentiment. | Parameter | Type | Description | | ------------- | ------- | ------------------ | | **`call_id`** | integer | CloudTalk call ID. | ### cloudtalk\_get\_call\_transcript The verbatim, speaker-tagged transcript as time-coded segments. A call with no transcript answers `transcription: null` with `reason: "no_transcript"` — an answer, not a transport failure, so there is nothing to retry. | Parameter | Type | Description | | ------------- | ------- | ---------------------------------------------- | | **`call_id`** | integer | CloudTalk call ID. | | `limit` | integer | Segments per page, up to 1000. Default `200`. | | `offset` | integer | Segment offset for the next page. Default `0`. | ### cloudtalk\_get\_call\_recording A signed link to the call audio, valid for up to 12 hours and sometimes much less. Fetch it again rather than storing it. A call with no recording returns a clear "no recording" answer. Every access is audit-logged. | Parameter | Type | Description | | ------------- | ------- | ------------------------------------- | | **`call_id`** | integer | CloudTalk call ID. | | `action` | string | `play` or `download`. Default `play`. | ### cloudtalk\_list\_call\_tags List the call tags your company can attach to a call. Every id returned is one `cloudtalk_add_call_tags` accepts. Call tags are a separate catalog from contact tags (`cloudtalk_list_contact_tags`); the ids are not interchangeable. | Parameter | Type | Description | | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | Results per page, up to 1000. Default `200`. | | `cursor` | string | Pagination cursor from a previous response. Omit for the first page. | | `call_type` | string | Keep only tags usable on `incoming` or `outgoing` calls (direction-agnostic tags are always included). Omit for the whole catalog. | ### cloudtalk\_add\_call\_tags Attach one or more call tags to a call. Idempotent: tags already on the call are ignored, so re-running is safe. Returns the call's full tag set after the change. | Parameter | Type | Description | | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **`call_id`** | string | The call to tag. Prefer the numeric call id from `cloudtalk_search_calls`; the call uuid from `cloudtalk_get_call` also works. | | **`tag_ids`** | integer or array | One call-tag id or a list of them, up to 100 per call. Get ids from `cloudtalk_list_call_tags`; contact-tag ids are rejected. | ### cloudtalk\_remove\_call\_tags Detach one or more tags from a call. Idempotent: tags not on the call are ignored, and only the ids you name are removed. Reversible with `cloudtalk_add_call_tags`. Returns the call's full tag set after the change. | Parameter | Type | Description | | ------------- | ---------------- | ------------------------------------------------------ | | **`call_id`** | string | The call to untag (numeric call id or uuid). | | **`tag_ids`** | integer or array | One call-tag id or a list of them, up to 100 per call. | ### cloudtalk\_get\_agent\_performance One agent's activity aggregated over a period: call counts, talk time, top contacts and tags. Counts are reliable; the talk-time figures presently often come back `null`, which means no answered call in the window reported a duration — unknown, never zero. Read `talk_reported_count` against `answered` for the coverage, and `cloudtalk_get_call` for one call's exact duration. | Parameter | Type | Description | | ---------------------- | ------- | -------------------------------------------------------------------- | | **`date_from`** | string | ISO datetime (UTC). The window may not exceed one year. | | `user_id` | integer | Agent ID. Provide one of `user_id`, `email`, `extension`. | | `email` | string | Agent email. | | `extension` | string | Agent extension. | | `date_to` | string | ISO datetime (UTC), upper bound. | | `max_calls` | integer | Calls to aggregate, up to 1000. Default `200`. | | `include_intelligence` | boolean | Also sample recent calls for a sentiment breakdown. Default `false`. | | `intelligence_sample` | integer | Calls to sample, up to 25. Default `25`. | ### cloudtalk\_realtime\_group\_stats Live queue stats per group: agents online, waiting calls, abandon rate, wait times. Counts are today-so-far (UTC). No parameters. ## Contacts ### cloudtalk\_get\_contact\_interactions\_summary Compact digest of one contact's history: counts, last contact, top tags, plus AI summaries and a sentiment trend over recent calls. | Parameter | Type | Description | | ------------- | ------- | ------------------------------------------------------------ | | `contact_id` | integer | Provide this or `phone`. | | `phone` | string | E.164 number to resolve to a contact. | | `date_from` | string | ISO datetime (UTC). Window up to 1 year (the default). | | `date_to` | string | ISO datetime (UTC), upper bound. | | `max_calls` | integer | Calls to aggregate, up to 500. Default `50`. | | `sample_size` | integer | Recent calls to sample for AI signals, up to 8. Default `5`. | ### cloudtalk\_list\_contacts List contacts, search them by free text, or look up an exact address with `email`. Tag filtering differs by lane: listing matches all the given tags by default; a keyword `query` always matches any one. | Parameter | Type | Description | | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Free-text search, 2 to 200 characters. Matches text anywhere on the record, so a result is **not** proof that a contact holds that exact address or number — use `email` for that. Omit to list. | | `email` | string | Exact email lookup: returns every contact holding this address, or none. Each row's `email` is the address that matched, which need not be the contact's first. `pagination.truncated` is `true` when more matches exist, `false` when the list is complete, and `null` when that could not be determined — so only `false` makes `totalCount` trustworthy. Cannot be combined with `query`, `tags`, `country`, or a page past the first. | | `tags` | array | Filter by tag name. Only natively applied tags match; a tag applied by a CRM or integration sync matches nothing. When listing, `tag_match` decides all vs any; with `query` it always matches at least one. Under `all`, a name that matches no tag empties the result, so zero results can mean one name was wrong. | | `tag_match` | string | `all` (default) or `any`. Applies only when listing; ignored with `query`. | | `country` | string | ISO-2 country code, e.g. `GB`. | | `limit` | integer | Results per page, up to 100. Default `20`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_get\_contact Full detail for one contact: profile, address, all numbers and emails, tags, CRM links. | Parameter | Type | Description | | ---------------- | ------- | --------------------- | | **`contact_id`** | integer | CloudTalk contact ID. | ### cloudtalk\_get\_contact\_journey 360° timeline for one contact: every call in the window, notes and activities, merged newest-first. Includes the 100 most recent notes and 100 most recent activities. | Parameter | Type | Description | | ---------------------- | ------- | -------------------------------------------------------- | | `contact_id` | integer | Provide this or `phone`. | | `phone` | string | E.164 number to resolve to a contact. | | `date_from` | string | ISO datetime (UTC). Window up to 1 year (the default). | | `date_to` | string | ISO datetime (UTC), upper bound. | | `max_calls` | integer | Calls to include, up to 500. Default `100`. | | `include_intelligence` | boolean | Also sample recent calls for sentiment. Default `false`. | | `intelligence_sample` | integer | Calls to sample, up to 25. Default `20`. | ### cloudtalk\_create\_contact Create a contact. ⚠️ No duplicate check: creating the same person twice makes two contacts, and there is no tool to delete a contact through the MCP. Search with `cloudtalk_list_contacts` first, then create only the ones that are missing. | Parameter | Type | Description | | ------------------- | ------- | ------------------------------------------- | | **`name`** | string | Contact display name, up to 150 characters. | | `company` | string | Up to 100 characters. | | `title` | string | Job title, up to 255 characters. | | `industry` | string | Up to 100 characters. | | `website` | string | Up to 100 characters. | | `address` | string | Street address, up to 255 characters. | | `city` | string | Up to 255 characters. | | `state` | string | Up to 255 characters. | | `zip` | string | Up to 15 characters. | | `source` | string | Contact source label, up to 64 characters. | | `phone_numbers` | array | Phone numbers in E.164 form. | | `emails` | array | Email addresses. | | `tags` | array | Tag names to attach. | | `favorite_agent_id` | integer | User ID of the favourite agent. | | `custom_fields` | object | Custom field values keyed by field name. | ### cloudtalk\_update\_contact Update fields on a contact. Only the fields you pass change, but `tags`, `phone_numbers`, `emails` and `custom_fields` are replaced in full, so send the complete list. **Asks for confirmation.** | Parameter | Type | Description | | ---------------- | ------- | --------------------- | | **`contact_id`** | integer | CloudTalk contact ID. | Optional fields: the same set as `cloudtalk_create_contact`. ### cloudtalk\_add\_contact\_note Add a note to a contact. Notes are additive; existing ones are never touched. | Parameter | Type | Description | | ---------------- | ------- | ----------------------------------- | | **`contact_id`** | integer | CloudTalk contact ID. | | **`note`** | string | Note body, up to 25,000 characters. | ### cloudtalk\_log\_contact\_activity Log a CRM-style activity: an order, an email, a custom event from another system. | Parameter | Type | Description | | ------------------- | ------- | ------------------------------------------ | | **`contact_id`** | integer | CloudTalk contact ID. | | **`type`** | string | Activity type, e.g. `order`; free-form. | | **`name`** | string | Short activity title. | | **`activity_date`** | string | ISO datetime the activity occurred at. | | `description` | string | Longer free-text description. | | `external_url` | string | Link to the activity in the source system. | | `external_id` | string | Identifier in the source system. | | `external_service` | string | Name of the source system. | | `cdr_id` | integer | Related call ID, if any. | | `activity_author` | string | Who performed the activity. | ### cloudtalk\_bulk\_tag\_contacts Tag many contacts in one call. Returns per-contact success and error counts. **Asks for confirmation.** | Parameter | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | **`contact_ids`** | array | Contact IDs, 1 to 500 per call. | | **`tags`** | array | Tag names to assign. | | `mode` | string | `append` adds the tags alongside existing ones; `replace` overwrites each contact's tag set. Default `append`. | ## Messaging & calling ### cloudtalk\_send\_sms Send an SMS to a customer from one of your numbers. Sends to one recipient per call; to message several people, send them one at a time. **Asks for confirmation.** | Parameter | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`recipient`** | string | Customer number, E.164. | | **`sender`** | string | A number your company owns (E.164) that has SMS enabled. Use `cloudtalk_list_numbers` and pick one whose `sms_supported` is true, or the send is rejected. | | **`message`** | string | SMS body text. | ### cloudtalk\_initiate\_call Click-to-call: rings the chosen agent first, then dials the customer once they pick up. The agent must be online in CloudTalk and not already on a call, or the call fails. **Asks for confirmation.** | Parameter | Type | Description | | ------------------- | ------- | ------------------------------------------------- | | **`agent_id`** | integer | The agent to ring first; must be online and free. | | **`callee_number`** | string | Customer number, E.164. | ### cloudtalk\_trigger\_aiva\_call Place an outbound AI Voice Agent call. The call is queued; a session ID comes back for tracking. **Asks for confirmation.** | Parameter | Type | Description | | -------------------- | ------ | ----------------------------------- | | **`voice_agent_id`** | string | From `cloudtalk_list_voice_agents`. | | **`call_number`** | string | Customer number, E.164. | ### cloudtalk\_list\_sms\_conversations An agent's SMS threads: customer number, unread count, last-message preview. | Parameter | Type | Description | | ---------------- | ------- | ---------------------------------------------------------------- | | **`user_id`** | integer | SMS is scoped to an agent's numbers, so say whose view you want. | | `contact_number` | string | Only threads with this customer number (E.164). | | `unread` | boolean | Only unread threads. | | `limit` | integer | Results per page, up to 100. Default `20`. | | `cursor` | integer | Pagination cursor from a previous response. | ### cloudtalk\_list\_sms\_messages The messages in one SMS thread, newest first. | Parameter | Type | Description | | --------------------- | ------- | ------------------------------------------- | | **`conversation_id`** | integer | From `cloudtalk_list_sms_conversations`. | | **`user_id`** | integer | The acting agent. | | `limit` | integer | Results per page, up to 100. Default `20`. | | `cursor` | integer | Pagination cursor from a previous response. | ## AI Voice Agents ### cloudtalk\_create\_voice\_agent Create an AI Voice Agent. Invalid configurations are rejected with specific errors and nothing is saved. ⚠️ There is no tool to delete a voice agent through the MCP; a created agent is managed or removed in the Dashboard. **Asks for confirmation.** | Parameter | Type | Description | | ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`agentName`** | string | Display name. | | **`direction`** | string | `inbound` or `outbound`. | | **`defaultOutboundNumberId`** | integer | Outbound number ID; `1` = automatic. | | **`language`** | string | Primary language code, e.g. `en`. | | **`maxCallDuration`** | integer | Maximum call duration in minutes; the server rejects values above 120. | | **`temperature`** | number | 0 to 1. | | **`voice`** | string | Voice ID. | | **`stability`** | number | Voice stability, 0 to 1. | | **`similarity`** | number | Voice similarity boost, 0 to 1. | | **`optimizeStreamingLatency`** | integer | Streaming latency optimisation, 0 to 4. | | **`startSpeakingFirst`** | boolean | Whether the agent speaks first. | | **`goalPrompt`** | string | The agent's goal / system prompt. | | `greeting` | string | Opening line. | | `secondaryLanguages` | array | Additional language codes. | | `knowledgeBaseIds` | array | Knowledge bases to link. | | `tone` | array | Identity tone presets shaping how the agent speaks: `professional`, `friendly`, `casual`, `calm`, `empathetic`, `direct`. Presets only — free text is rejected, repeats are dropped, and an empty list is saved as `friendly`, `direct`. | | `verbosity` | string | How much the agent says per turn: `concise`, `standard` or `thorough`. `""` means unset and is saved as `standard`. | | `skills` | object | Skill toggles: transfer to human, take a message, extract data, answer questions, book appointments. | | `scenarios` | array | Scenario rules. | | `guardrails` | array | Guardrail rules. | | `dialTime` | integer | Ring timeout in seconds, 5 to 120. `0` means use the provider's own default instead. | | `failoverOutboundNumberId` | integer | Fallback outbound number. Required when `defaultOutboundNumberId` is `1` (automatic), and it must be the id of a real number from `cloudtalk_list_numbers` — `1` is not accepted here. | | `llmOverride` | string | Optional LLM model override. | | `providerOverride` | string | Optional provider override. | | `elevenLabsSettings` | object | Advanced voice-provider settings. | ### cloudtalk\_list\_voice\_agents Your AI Voice Agents: ID, name, direction. | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------- | | `limit` | integer | Results per page, up to 200. `pagination.items_count` carries the unpaged total. Default `50`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_get\_voice\_agent One agent's full configuration: fetch it, modify it, pass it back to `cloudtalk_update_voice_agent`. | Parameter | Type | Description | | -------------------- | ------ | ----------------------------------- | | **`voice_agent_id`** | string | From `cloudtalk_list_voice_agents`. | ### cloudtalk\_update\_voice\_agent Replace an agent's configuration: send the full config back, not just the changed fields. **Asks for confirmation.** | Parameter | Type | Description | | -------------------- | ------ | -------------------- | | **`voice_agent_id`** | string | The agent to update. | Plus the same required and optional set as `cloudtalk_create_voice_agent`. ### cloudtalk\_list\_knowledge\_bases Knowledge bases with type, status, and which agents use them. | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------- | | `limit` | integer | Results per page, up to 200. `pagination.items_count` carries the unpaged total. Default `50`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_create\_knowledge\_base Give voice agents material to answer from: inline text, or a public web page ingested in the background. ⚠️ There is no tool to delete a knowledge base through the MCP; manage it in the Dashboard. **Asks for confirmation.** | Parameter | Type | Description | | ---------- | ------ | ---------------------------------------------------------------------- | | **`name`** | string | Display name, up to 50 characters. | | `type` | string | `custom` (inline text) or `url` (ingest a web page). Default `custom`. | | `text` | string | Content; required when `type` is `custom`. | | `url` | string | Public http(s) URL; required when `type` is `url`. | ### cloudtalk\_list\_voice\_agent\_tools HTTP actions a voice agent can perform mid-conversation, with their current assignments. | Parameter | Type | Description | | ---------------- | ------- | ------------------------------------------ | | `voice_agent_id` | string | Only the tools assigned to this agent. | | `limit` | integer | Results per page, up to 200. Default `50`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_assign\_tool\_to\_voice\_agent Give an agent an action. Assigning one it already has is a safe no-op. **Asks for confirmation.** | Parameter | Type | Description | | -------------------- | ------ | ---------------------------------------- | | **`tool_id`** | string | From `cloudtalk_list_voice_agent_tools`. | | **`voice_agent_id`** | string | The agent to assign to. | ### cloudtalk\_unassign\_tool\_from\_voice\_agent Take an action away from one agent; other agents keep it. **Asks for confirmation.** | Parameter | Type | Description | | -------------------- | ------ | ---------------------------------------- | | **`tool_id`** | string | From `cloudtalk_list_voice_agent_tools`. | | **`voice_agent_id`** | string | The agent to unassign from. | ### cloudtalk\_create\_voice\_agent\_tool Create an AIVA tool: an HTTP action a voice agent can call mid-conversation. If the server rejects the tool, it returns the validator's specific errors and nothing is saved. ⚠️ There is no tool to delete an AIVA tool through the MCP; manage it in the Dashboard. **Asks for confirmation.** Header and parameter values may hold credentials for your endpoint. They are sent to CloudTalk but never shown back in previews or responses. | Parameter | Type | Description | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`name`** | string | Up to 64 characters; letters, numbers, hyphen and underscore only. | | **`method`** | string | `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`. | | **`url`** | string | The endpoint to call. May embed `{{param}}` placeholders resolved at call time. | | **`awaiting_response_message`** | string | What the agent says while waiting for the response, up to 4096 characters. | | `description` | string | What the tool does, for the agent's benefit. | | `voice_agent_config_ids` | array | Agents to assign the tool to. Empty means assigned to none. | | `headers` | array | HTTP headers: `key` plus a `CONST` value or a `SECRET` reference (`secret_id`). | | `query_params` | array | Query parameters: `param_name`, `data_type` (STRING, INTEGER, NUMBER, BOOLEAN) and a value that is `CONST` (fixed), `PARAM` (taken from the call), or `LLM` (filled in by the agent mid-conversation). | | `body_params` | array | Request-body parameters; same shape as `query_params`. | ### cloudtalk\_update\_voice\_agent\_tool Update an AIVA tool. Only the fields you pass change; omitted fields, including stored header and parameter values, are preserved. Passing an empty list explicitly clears that list. **Asks for confirmation.** | Parameter | Type | Description | | ------------- | ------ | ---------------------------------------- | | **`tool_id`** | string | From `cloudtalk_list_voice_agent_tools`. | Optional fields: the same set as `cloudtalk_create_voice_agent_tool`. ## Campaigns The campaign tools require the new **Sales Dialer** add-on. Without it, these tools have nothing to operate on. ### cloudtalk\_launch\_campaign\_from\_source Create a campaign, attach its sources, and start it in one step. Not atomic: if a later step fails, the campaign is left in `initializing` and dials nothing, and the response says how far it got. **Asks for confirmation.** | Parameter | Type | Description | | ------------- | ------- | --------------------------------------------------------------------- | | **`name`** | string | Campaign name. | | **`mode`** | string | `sequential` or `parallel` (`predictive` is accepted but deprecated). | | `target_tag` | array | At least one of `target_tag`, `queue_group`, `agent` is required. | | `queue_group` | array | Agent-group IDs. | | `agent` | array | Agent IDs. | | `activate` | boolean | Pass `false` to stage the campaign without dialing. Default `true`. | Also accepts the same optional config bundles as `cloudtalk_create_campaign` (the policy objects, `agent_permissions`, `waterfall_order`, `call_script_id`, `survey_id`). ### cloudtalk\_list\_campaigns List outbound campaigns with status, mode and contact sources. | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------------------------------------------ | | `status` | string | Filter by campaign status: `initializing`, `active`, `inactive`, `archived`, or `deleted`. | | `mode` | string | Filter by dialing mode: `sequential`, `parallel`, or `predictive`. | | `limit` | integer | Results per page, up to 100. Default `100`. | | `cursor` | string | Pagination cursor from a previous response. | ### cloudtalk\_get\_campaign One campaign in detail: sources, status, policies, linked script and survey. | Parameter | Type | Description | | ----------------- | ------ | ------------ | | **`campaign_id`** | string | Campaign ID. | ### cloudtalk\_create\_campaign Create a campaign. It starts in `initializing` and dials nothing until you add sources and set it active. **Asks for confirmation.** | Parameter | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------- | | **`name`** | string | Campaign name. | | **`mode`** | string | `sequential` or `parallel` (`predictive` is accepted but deprecated). | | `calling_policy` | object | Calling-policy bundle. | | `queue_policy` | object | Queue-policy bundle. | | `retry_policy` | object | Retry-policy bundle. | | `schedule_policy` | object | Schedule-policy bundle. | | `ttl_policy` | object | Contact time-to-live policy. | | `agent_permissions` | object | Agent-permissions bundle. | | `waterfall_order` | array | Ordered contact-source tiers. | | `call_script_id` | string | Call script to link. | | `survey_id` | string | Survey to link. | ### cloudtalk\_update\_campaign Update a campaign's configuration. Scalar fields merge, but a policy bundle you pass is replaced in full: send the complete bundle from `cloudtalk_get_campaign`, because any key you leave out is dropped from the stored bundle. It is not reset to some default value — `cloudtalk_get_campaign` simply stops returning it, and the campaign runs as though that setting had never been configured. **Asks for confirmation.** | Parameter | Type | Description | | ----------------- | ------ | ------------ | | **`campaign_id`** | string | Campaign ID. | Plus at least one field from the `cloudtalk_create_campaign` set. Pass `null` for `call_script_id` or `survey_id` to clear that link. ### cloudtalk\_set\_campaign\_status Start, pause or archive a campaign. Pausing never interrupts calls already in progress. **Asks for confirmation.** | Parameter | Type | Description | | ----------------- | ------ | ------------------------------------ | | **`campaign_id`** | string | Campaign ID. | | **`status`** | string | `active`, `inactive`, or `archived`. | ### cloudtalk\_delete\_campaign ⚠️ Delete a campaign. This is terminal and irreversible: the status becomes `deleted`, with no undo and no way to reactivate it. This is not archiving; to retire a campaign reversibly, use `cloudtalk_set_campaign_status` with `archived` (which exits back to `inactive`). **Asks for confirmation.** | Parameter | Type | Description | | ----------------- | ------ | ------------ | | **`campaign_id`** | string | Campaign ID. | ### cloudtalk\_get\_campaign\_associations A campaign's contact sources (tags) and assignees (groups, agents). Read this before replacing them. | Parameter | Type | Description | | ----------------- | ------ | ------------ | | **`campaign_id`** | string | Campaign ID. | ### cloudtalk\_replace\_campaign\_associations Set a campaign's sources and assignees. One write covers all three kinds and always sends all three: a kind you pass replaces its current set in full (an empty array clears it), and a kind you omit is preserved. **Asks for confirmation.** | Parameter | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`campaign_id`** | string | Campaign ID. | | `target_tag` | array | Contact-source tags. Replaces the set in full; an empty array clears it; omit to preserve. Tags owned by a CRM connection are ignored and reported back in `crm_owned_ignored`. | | `queue_group` | array | Agent-group IDs. Replaces the set in full; an empty array clears it; omit to preserve. | | `agent` | array | Agent IDs. Replaces the set in full; an empty array clears it; omit to preserve. | | `expected_digest` | string | Optional. A token the tool computes from the associations it read for the preview; CloudTalk does not store it. Pass it back with your confirmation and the tool re-reads, compares, and refuses the write if the associations changed in between. The check lives in this tool alone — campaign resources carry no version or ETag — so it guards the gap between preview and confirmation, and nothing after that. | ## Connection ### cloudtalk\_health\_check Check that CloudTalk is reachable and see which company and user your API key resolved to. Run this first when something is failing: it separates an authentication or wrong-account problem from a data problem. No parameters. ## Account lookups The reference data other tools need: agent, group, number and tag ids. Included in every profile. ### cloudtalk\_list\_agents Agents: names, emails, extensions, availability, default number. | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `id` | integer | One specific agent. | | `limit` | integer | Results per page, up to 1000. Default `200`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_list\_groups Agent groups (queues and teams). | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `limit` | integer | Results per page, up to 1000. Default `200`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_list\_numbers Your phone numbers with friendly names and caller IDs. | Parameter | Type | Description | | -------------- | ------- | ----------------------------------------------- | | `id` | integer | One specific number. | | `country_code` | string | Numeric calling code, e.g. `44`. | | `area_code` | string | Area code prefix. | | `is_free` | boolean | Only numbers not yet assigned to a destination. | | `limit` | integer | Results per page, up to 1000. Default `200`. | | `page` | integer | Page number. Default `1`. | ### cloudtalk\_list\_contact\_tags Your contact tag catalog: the tags used on contacts and by `cloudtalk_bulk_tag_contacts`. Call tags live in a separate catalog; for those use `cloudtalk_list_call_tags`. | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `limit` | integer | Results per page, up to 1000. Default `200`. | | `page` | integer | Page number. Default `1`. | ## Related topics - [CloudTalk MCP](/guides/mcp/overview.md) - [CloudTalk REST API v1.7 — Complete Developer Reference](/api-reference/overview.md) - [MCP Recipes](/guides/mcp/recipes.md)