canonical: https://jentic.com/apis/cloudtalk.io/cloudtalk

# CloudTalk API

Jentic publishes the only available OpenAPI specification for CloudTalk API, keeping it validated and agent-ready. The CloudTalk API is the integration surface for the CloudTalk cloud call centre platform: it covers calls, contacts, agents, phone numbers, campaigns, conversation intelligence, and the VoiceAgent product. Endpoints let teams browse and download call recordings, create and update contacts and agents, manage outbound campaigns, push live cue cards to agents during calls, and initiate VoiceAgent calls. Authentication is HTTP Basic with an Access Key ID and Access Key Secret, all responses are JSON, and the default rate limit is 60 operations per minute per company.

## For AI agents

Run a cloud call centre programmatically - list calls and recordings, manage agents and contacts, drive outbound campaigns, push live cue cards, and start VoiceAgent calls.

## Scope

Does not handle SMS, email delivery, or video conferencing - use for CloudTalk cloud call centre operations including voice calls, agents, contacts, and campaigns only.

## Capabilities

- Browse call history and download call recordings via /calls endpoints
- Create, update, tag, and delete contacts and attach notes and activities
- Add, edit, and remove agents and assign them to groups
- List, create, and edit outbound campaigns and their associated numbers
- Push live cue cards to an agent's screen during an active call
- Initiate VoiceAgent calls and access conversation intelligence data on completed calls

## Use cases

### CRM Sync of Calls and Contacts

Sales and support teams using CloudTalk alongside a CRM need every call, note, and tag mirrored back into the system of record. The CloudTalk API exposes `/contacts/index.json` and /calls endpoints to pull contact and call data, plus /notes and /activity for follow-up records, so a sync job can keep CRM contact timelines current without manual exports. The 60-requests-per-minute default rate limit means most accounts can sync a few thousand contacts per hour with simple pagination.

Example prompt: List contacts created in the last 24 hours via `/contacts/index.json`, then for each contact fetch their call notes via /notes and write the summary into the linked CRM record

### Agent and Group Provisioning

Operations and IT teams onboarding new support reps need to create CloudTalk agents and assign them to the right skill groups in bulk. `/agents/add.json` creates the agent, `/groups/add.json` assigns them to a group, and the corresponding edit and delete endpoints handle role changes and offboarding. Running this through the API removes click-by-click setup in the dashboard and makes the joiner-mover-leaver flow scriptable from an HRIS feed.

Example prompt: Create a new agent for new.hire@example.com via PUT `/agents/add.json` then assign them to group ID 7 via PUT `/groups/add.json`

### Live Agent Assist with Cue Cards

When a call comes in, customer support agents benefit from a real-time cue card showing the customer's order, recent tickets, and recommended next action. The /cuecards POST endpoint accepts an agent identifier and structured card content, which CloudTalk renders inside the agent app for the duration of the active call. This replaces tab-switching to a CRM during the call and gives agents context driven from any backend system.

Example prompt: When a call from +14155551234 connects to agent 42, POST /cuecards with the customer's last order ID, ticket count, and a 'Offer renewal discount' suggestion

### AI Agent Operating CloudTalk via Jentic

AI agents can run CloudTalk operations through Jentic to automate customer outreach, after-call summarisation, and contact hygiene. The agent expresses an intent like 'add a contact' or 'list recent calls', and Jentic loads the matching CloudTalk operation and supplies the Basic Auth credentials from the vault. Results return as structured JSON, so the agent can take the next step without parsing the CloudTalk response envelope manually.

Example prompt: Through Jentic, search for 'add a contact', load the cloudtalk.io `/contacts/add.json` operation, and execute it with the customer's name, phone number, and email

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/contacts/index.json` | List contacts |
| PUT | `/contacts/add.json` | Add a contact |
| GET | `/agents/index.json` | List agents |
| PUT | `/agents/add.json` | Add an agent |
| POST | `/cuecards` | Push a cue card to an agent during a call |
| GET | `/campaigns/index.json` | List outbound campaigns |
| GET | `/notes/index.json` | List notes attached to contacts |

## Key resources

- **Calls** — Browse call history, fetch call details, and download recordings
- **Contacts** — Create, update, tag, and delete contacts; manage notes and activities
- **Agents** — Manage call centre agents and their group assignments
- **Numbers** — List and configure phone numbers attached to the account
- **Campaigns** — Create, edit, and manage outbound calling campaigns
- **CueCards** — Push live context cards to agents during active calls
- **Conversation Intelligence** — Access transcripts and intelligence data for completed calls
- **VoiceAgent** — Initiate AI VoiceAgent calls programmatically

## Why Jentic

- **Setup:** Wiring CloudTalk by hand means encoding its Basic auth access key and secret, targeting my.cloudtalk.io/api, and handling paging and retries across its call-centre endpoints yourself. Through Jentic you install once, import the CloudTalk API from the API Directory, store the access key and secret once, and your agent calls it.
- **Permission scoping:** CloudTalk identifies contacts and agents in the request body rather than the URL path, so scope the agent to the operations it needs, such as listing contacts or adding a contact. You choose that set, so write operations like adding an agent or pushing a cue card are not included unless you add them.
- **Credential handling:** Your CloudTalk access key ID and secret are stored once, encrypted, by your own Jentic One instance and combined into the Basic auth header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a contact', 'push a cue card', or 'list calls', and Jentic returns the matching CloudTalk operation with its input schema so the agent calls the right endpoint without browsing the CloudTalk reference docs.

## Related APIs

- **Twilio API** — Twilio offers programmable voice and a similar set of telephony primitives at a different abstraction level
- **Aircall API** — Aircall is a directly comparable cloud call centre with calls, contacts, and agent management
- **HubSpot API** — HubSpot CRM holds the contact and deal records that CloudTalk call data is synced into

## FAQ

### Why is there no official OpenAPI spec for CloudTalk API?

CloudTalk does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CloudTalk API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the CloudTalk API use?

The CloudTalk API uses HTTP Basic Authentication with an Access Key ID and Access Key Secret. Administrators issue keys from the CloudTalk dashboard under Account > Settings > API keys. Through Jentic the key pair is stored encrypted in the vault and applied as the Authorization header at execution time, so the agent never sees the secret.

### Can I download call recordings with the CloudTalk API?

Yes. Browse calls via `/calls/index.json` to identify the call ID, then use the call detail endpoint to fetch the recording URL. Recordings are returned as audio files referenced in the call resource and can be archived to your own storage.

### What are the rate limits for the CloudTalk API?

The default rate limit is 60 operations per minute per company. Responses include X-CloudTalkAPI-Limit, X-CloudTalkAPI-Remaining, and X-CloudTalkAPI-ResetTime headers, and a 429 Too Many Requests response is returned when the limit is hit. Higher limits are available by contacting CloudTalk support with the use case.

### How do I add a contact with the CloudTalk API through Jentic?

Install the SDK with pip install jentic, search for 'add a contact', load the cloudtalk.io `/contacts/add.json` operation, and execute it with the contact's name, phone number, email, and any custom attributes. Jentic supplies the Basic Auth credentials automatically and returns the structured response.

### Can I push live cue cards to agents during a call?

Yes. POST /cuecards with the agent identifier and structured card content while the call is active. CloudTalk renders the card in the agent app, which is the standard pattern for surfacing CRM context, scripts, or recommended next actions during the conversation.

### Does the CloudTalk API support the VoiceAgent product?

Yes. The VoiceAgent endpoints initiate AI-driven voice calls and return references that can be used to retrieve the resulting recording and Conversation Intelligence data once the call completes.

### Can I limit what my agent is allowed to do with the CloudTalk API?

Yes. Because you run Jentic One yourself, your own rules decide which CloudTalk operations and credentials the agent can use. CloudTalk identifies contacts and agents in the request body rather than the URL path, so you scope the agent to just the operations it needs, such as listing contacts via `/contacts/index.json` or adding a contact via `/contacts/add.json.` Write operations like adding an agent through `/agents/add.json` or pushing a cue card via /cuecards stay out of reach unless you explicitly add them to that set.