Documentation
Documentation
https://developers.cloudtalk.io/
Authentication
https://raw.githubusercontent.com/api-evangelist/cloudtalk/refs/heads/main/authentication/cloudtalk-authentication.yml
OpenAPI Specification
openapi: 3.0.1
info:
title: CloudTalk Agents API
description: "# Introduction\nWelcome to CloudTalk API reference! Many of these businesses use the CloudTalk API to automate and enhance their customer support with CloudTalk Support. With CloudTalk we are re-building telco industry from the ground and taking it to the next level with first-class customer support system. Please find below the full documenation to CloudTalk.\n\n# API Overview\n\nThe API is organized around the following resources:\n\nAPI Area | Description\n----------------|-------------\nCalls | Browse your call history, download recordings and access all your calls data.\nContacts | Create and update Contacts. Use filters to get lists of Contacts, or access their profiles individually.\nNumbers | Automate Numbers modifications. List all your numbers.\nAgents | Create or update your Agents, access their settings.\nConversation Intelligence | Get Conversation Intelligence data about your calls.\nVoiceAgent | Initiate VoiceAgent calls\n\n\n[JSON](http://www.json.org/) is returned in all responses. XML is not supported.\n\nThe API also uses common approaches for the following:\n\nFunction | Description\n----------------|-------------\nData | API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.\nErrors | 4xx and 5xx responses returning JSON with error codes\nRate Limiting | Controls how many requests can be made in a time window\nHTTP | Methods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.\n\n\n## Authentication\n\nThis is an HTTPS-only API. Authentication is based on API Access Key ID and Access Key Secret. The API Access Key ID and Access Key Secret is passed via HTTP Basic Authentication.\n\n Basic Auth credentials are used to determine on which project should this request be executed on. List of all Basic Auth credentials for the project can be found by Administrators in the Cloudtalk Dashboard Account → Settings → API keys tab.\n\nTo try the API via curl on the command-line, the general form used would be:\n```\ncurl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET API_URL\n```\n\nFor instance, you would execute:\n```\ncurl -u ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An https://my.cloudtalk.io/api/calls/index.json\n```\n\n## Usage\n\nThe API may rate limit submission of requests for your application. Such limits are managed as an allowed number of operations per time window, where an operation might be read or an update. In that case a **'429 Too Many Requests'** response code will be returned along with the following headers -\n\nHeader name | Description\n----------------|-------------\nX-CloudTalkAPI-Limit | Maximum number of API requests allowed in the current time window.\nX-CloudTalkAPI-Remaining | Number of API requests left in the current window.\nX-CloudTalkAPI-ResetTime | Time when rate limit window will be reset as a Unix timestamp.\n\nNote that the default rate limit is **60 operations per minute per company**. If you need to make more requests, please contact our support with detailed explanation of your use case.\n\n## Response Envelopes\n\n**Note:** Conversation Intelligence doesn't follow envelopes.\n\nThe API returns one of three envelopes depending upon the request issued:\n\n1. Single Item Envelope\n2. Collections Envelope\n3. Error Envelope\n\n### Single Item Envelope\n\nAll dates/times are returned in ISO8601 format and in UTC timezone.\n\n```\nStatus: 200 OK\n{\n \"responseData\": {\n \"id\": 123,\n ...\n \"created\": \"2018-01-10 12:34:56\"\n }\n}\n```\n\n### Collections Envelope\n\nAll dates/times are returned in ISO8601 format and in UTC timezone.\n\n```\nStatus: 200 OK\n{\n \"responseData\": {\n \"itemsCount\": 65,\n \"pageCount\": 3,\n \"pageNumber\": 1,\n \"limit\": 30,\n \"data\": [\n {\n \"id\": 123,\n ...\n \"created\": \"2018-01-10 12:34:56\"\n },\n {\n \"id\": 456,\n ...\n \"created\": \"2017-10-19 09:21:29\"\n },\n ...\n ]\n }\n}\n```\n\n### Error Envelope\n\n```\nStatus: 404 Not Found\n{\n \"responseData\": {\n \"status\": 404,\n \"message\": \"Not Found\"\n }\n}\n```\n\n## Encoding\n\nData is encoded as defined by JSON in [RFC4627](http://www.ietf.org/rfc/rfc4627.txt). The default encoding for APIs is UTF-8.\n\nSome query parameters may need to be [url encoded](https://www.wikiwand.com/en/Percent-encoding) when sending - for example, the email parameter value used to query users should be encoded.\n\n## Use of HTTP\n\nRequest methods are used in accordance with HTTP -\n\n- `GET` is used to access resources and perform queries. The API does not allow modifications (creates, updates, deletes) to occur via GET.\n- `PUT` is used to create resources.\n- `POST` is used to update resources. PATCH is not currently used by the API.\n- `DELETE` is used to delete resources.\n\nResponses use standard HTTP codes. Where there are client or server errors, a list of of one or more errors in JSON format is returned in the body.\n\nThe `Accept` header must be used by a client used to indicate a preferred response for `GET/HEAD` requests. Requests without an `Accept` header of `application/json` may be rejected with a client error of 404 or 406. The `Content-Type` header should be used by clients to indicate the submitted format for `POST/PUT` requests."
contact:
name: CloudTalk API Support
url: https://www.cloudtalk.io/contact
version: '1.7'
x-logo:
url: https://my.cloudtalk.io/img/logo-cloudtalk-color.png
servers:
- url: https://my.cloudtalk.io/api
tags:
- name: Agents
description: All data you can get about your agents.
paths:
/agents/index.json:
get:
tags:
- Agents
summary: List agents
parameters:
- name: id
in: query
description: Filter by agent ID
schema:
type: integer
- name: limit
in: query
description: Max. number of items in response data.
schema:
maximum: 1000
minimum: 1
type: integer
- name: page
in: query
description: Number of page to return.
schema:
minimum: 1
type: integer
- name: associated_number
in: query
description: Filters agents by their assigned number. Please enter a valid number in e164 format
schema:
type: string
responses:
'200':
description: Agents data
content:
application/json:
schema:
type: object
properties:
itemsCount:
$ref: '#/components/schemas/PaginationData/properties/itemsCount'
pageCount:
$ref: '#/components/schemas/PaginationData/properties/pageCount'
pageNumber:
$ref: '#/components/schemas/PaginationData/properties/pageNumber'
limit:
$ref: '#/components/schemas/PaginationData/properties/limit'
data:
type: array
items:
type: object
properties:
Agent:
$ref: '#/components/schemas/Agent'
example:
responseData:
itemsCount: 3
pageCount: 1
pageNumber: 1
limit: 3
data:
- Agent:
id: '99'
name: '123456'
firstname: John
lastname: Doe
email: joh.doe@phoonio.com
is_daily_limit_ok: true
status_outbound: true
availability_status: online
extension: '1001'
call_number_id: 36
default_number: '+421123456789'
associated_numbers:
- '+421123456789'
- '+421987654321'
/agents/add.json:
put:
tags:
- Agents
summary: Add an agent
requestBody:
content:
application/json:
schema:
required:
- email
- firstname
- lastname
- pass
type: object
properties:
firstname:
$ref: '#/components/schemas/Agent/properties/firstname'
lastname:
$ref: '#/components/schemas/Agent/properties/lastname'
email:
$ref: '#/components/schemas/Agent/properties/email'
pass:
$ref: '#/components/schemas/Agent/properties/pass'
status_outbound:
$ref: '#/components/schemas/Agent/properties/status_outbound'
daily_price_limit:
$ref: '#/components/schemas/Agent/properties/daily_price_limit'
extension:
$ref: '#/components/schemas/Agent/properties/extension'
call_number_id:
$ref: '#/components/schemas/Agent/properties/call_number_id'
required: true
responses:
'201':
description: No error
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/StatusCode/properties/status'
data:
type: object
properties:
id:
$ref: '#/components/schemas/Agent/properties/id'
example:
responseData:
status: 201
data:
id: '12345'
'403':
description: Max. number of agents reached
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
example:
responseData:
status: 403
message: Max. number of agents reached.
'406':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInvalidData'
example:
responseData:
status: 406
message: Invalid input data.
data:
email:
- Please supply a valid email address.
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
example:
responseData:
status: 500
message: Something went wrong.
x-codegen-request-body-name: body
/agents/edit/{agentId}.json:
post:
tags:
- Agents
summary: Edit an agent
parameters:
- name: agentId
in: path
description: Agent ID to edit
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
required:
- email
- firstname
- lastname
type: object
properties:
firstname:
$ref: '#/components/schemas/Agent/properties/firstname'
lastname:
$ref: '#/components/schemas/Agent/properties/lastname'
email:
$ref: '#/components/schemas/Agent/properties/email'
status_outbound:
$ref: '#/components/schemas/Agent/properties/status_outbound'
daily_price_limit:
$ref: '#/components/schemas/Agent/properties/daily_price_limit'
call_number_id:
$ref: '#/components/schemas/Agent/properties/call_number_id'
required: true
responses:
'200':
description: No error
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/StatusCode/properties/status'
example:
responseData:
status: 200
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
example:
responseData:
status: 404
message: Not found.
'406':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInvalidData'
example:
responseData:
status: 406
message: Invalid input data.
data:
email:
- Please supply a valid email address.
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
example:
responseData:
status: 500
message: Something went wrong.
x-codegen-request-body-name: body
/agents/delete/{agentId}.json:
delete:
tags:
- Agents
summary: Delete an agent
parameters:
- name: agentId
in: path
description: Agent ID to delete
required: true
schema:
type: integer
responses:
'200':
description: No error
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessGeneralData'
example:
responseData:
status: 200
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
example:
responseData:
status: 404
message: Not found.
components:
schemas:
PaginationData:
properties:
pageNumber:
type: integer
description: current page in the response
format: int64
limit:
type: integer
description: number of objects sent per page
format: int64
pageCount:
type: integer
description: number of pages found
format: int64
itemsCount:
type: integer
description: number of resources in the response
format: int64
Agent:
type: object
properties:
id:
type: integer
description: Agent ID
name:
type: string
description: Agent\'s Voice ID
firstname:
type: string
description: First name
lastname:
type: string
description: Last name
email:
type: string
description: Email
format: email
pass:
type: string
description: Password
daily_price_limit:
maximum: 200
minimum: 1
type: integer
description: Daily price limit for all calls in EUR. Usually allowed values are from 1 to 200 EUR. Leave empty for using default value.
is_daily_limit_ok:
type: boolean
description: Is daily price limit OK? If not, agent cannot make new calls
status_outbound:
type: boolean
description: Does agent have outbound calls allowed?
availability_status:
type: string
description: Current availability status of the agent
enum:
- online
- offline
- paused
- calling
extension:
maximum: 9999
minimum: 1000
type: integer
description: Extension of an agent. Extension must be four digits long and be unique across whole company.
call_number_id:
minimum: 1
type: integer
description: Default outbound number ID
default_number:
type: string
description: Default outbound number in E164 format
associated_numbers:
type: array
description: array of e164 numbers that the agent has assigned
items:
type: string
description: Agent data
ErrorInvalidData:
type: object
properties:
status:
type: string
description: Status code
message:
type: string
description: The error message
data:
type: object
properties: {}
description: More data explaining the error
StatusCode:
properties:
status:
type: string
description: Status code
ErrorData:
type: object
properties:
status:
type: string
description: Status code
message:
type: string
description: The error message
SuccessGeneralData:
type: object
properties:
status:
type: string
description: Status code