CloudTalk Conversation Intelligence API

openapi: 3.2.0
info:
  title: CloudTalk Conversation Intelligence API
  description: '# Introduction

    Welcome 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. # API Overview


    The API is organized around the following resources:


    API Area | Description

    ----------------|-------------

    Calls | Browse your call history, download recordings and access all your calls data. Contacts | Create and update Contacts. Use filters to get lists of Contacts, or access their profiles individually. Numbers | Automate Numbers modifications. List all your numbers. Agents | Create or update your Agents, access their settings. Conversation Intelligence | Get Conversation Intelligence data about your calls. VoiceAgent | Initiate VoiceAgent calls


    JSON is returned in all responses. XML is not supported. The API also uses common approaches for the following:


    Function | Description

    ----------------|-------------

    Data | API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects. Errors | 4xx and 5xx responses returning JSON with error codes

    Rate Limiting | Controls how many requests can be made in a time window

    HTTP | 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. ## Authentication


    This 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. 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 under Account → Settings → API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys). To try the API via curl on the command-line, the general form used would be:

    ```

    curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET API_URL

    ```


    For instance, you would execute:

    ```

    curl -u ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An https://my.cloudtalk.io/api/calls/index.json

    ```


    ## Usage


    The 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 -


    Header name | Description

    ----------------|-------------

    X-CloudTalkAPI-Limit | Maximum number of API requests allowed in the current time window. X-CloudTalkAPI-Remaining | Number of API requests left in the current window. X-CloudTalkAPI-ResetTime | Time when rate limit window will be reset as a Unix timestamp. Note 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. ## Response Envelopes


    **Note:** Conversation Intelligence doesn''t follow envelopes. The API returns one of three envelopes depending upon the request issued:


    1. Single Item Envelope

    2. Collections Envelope

    3. Error Envelope


    ### Single Item Envelope


    All dates/times are returned in ISO8601 format and in UTC timezone. ```

    Status: 200 OK

    {

    "responseData": {

    "id": 123,

    ... "created": "2018-01-10 12:34:56"

    }

    }

    ```


    ### Collections Envelope


    All dates/times are returned in ISO8601 format and in UTC timezone. ```

    Status: 200 OK

    {

    "responseData": {

    "itemsCount": 65,

    "pageCount": 3,

    "pageNumber": 1,

    "limit": 30,

    "data": [

    {

    "id": 123,

    ... "created": "2018-01-10 12:34:56"

    },

    {

    "id": 456,

    ... "created": "2017-10-19 09:21:29"

    },

    ...'
  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
security:
- basicAuth: []
tags:
- name: Conversation Intelligence
  description: Conversation Intelligence data about your calls.
paths:
  /ai/calls/{callId}/summary:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Summary
      description: 'Returns the AI-generated summary of a completed call.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      responses:
        '200':
          description: Information about a given call's summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  callId:
                    type: number
                    description: ID of the call
                  summary:
                    type: string
                    description: Summary of the call
                required:
                - callId
                - summary
              example:
                callId: 12345
                summary: This is a summary of the call.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdSummary
      x-operation-id-source: derived
  /ai/calls/{callId}/overall-sentiment:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Overall sentiment
      description: 'Returns the sentiment scored across a completed call as a whole — one of `very negative`, `negative`, `neutral`, `positive` or `very positive`.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      responses:
        '200':
          description: Information about a given call's overall sentiment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallOverallSentiment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdOverallSentiment
      x-operation-id-source: derived
  /ai/calls/{callId}/talk-listen-ratio:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Talk-listen ratio
      description: 'Returns how much each participant spoke during a completed call: talking time in seconds and a talk-to-listen percentage per caller, alongside the list of callers the identifiers refer to.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      responses:
        '200':
          description: Information about a given call's talk-listen ratio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTalkListenRatio'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdTalkListenRatio
      x-operation-id-source: derived
  /ai/calls/{callId}/topics:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Topics
      description: 'Returns the topics detected in a completed call, each with a weight and the transcript spans it was drawn from. Page through the result with `limit` and `offset`.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      - $ref: '#/components/parameters/paginationLimit'
      - $ref: '#/components/parameters/paginationOffset'
      responses:
        '200':
          description: Information about a given call's topics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTopics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdTopics
      x-operation-id-source: derived
  /ai/calls/{callId}/transcription:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Transcription
      description: 'Returns the transcript of a completed call as time-stamped segments, each attributed to a caller, together with the detected language. Page through the segments with `limit` and `offset`.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      - $ref: '#/components/parameters/paginationLimit'
      - $ref: '#/components/parameters/paginationOffset'
      responses:
        '200':
          description: Information about a given call's transcription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTranscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdTranscription
      x-operation-id-source: derived
  /ai/calls/{callId}/smart-notes:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Smart notes
      description: 'Returns the structured notes generated for a completed call — call details, action items, decisions made, open questions and any dates or deadlines mentioned.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      responses:
        '200':
          description: Information about a given call's smart notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallSmartNotes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdSmartNotes
      x-operation-id-source: derived
  /ai/calls/{callId}/details-link:
    get:
      servers:
      - url: https://api.cloudtalk.io/v1
      tags:
      - Conversation Intelligence
      summary: Call details link
      description: 'Returns a link to the call''s detail page in CloudTalk analytics.


        Conversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API''s `responseData` envelope.'
      parameters:
      - $ref: '#/components/parameters/callId'
      responses:
        '200':
          description: Link to the details of the call in the analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    description: Link to the details of the call in the analytics
                required:
                - link
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: getAiCallsByCallIdDetailsLink
      x-operation-id-source: derived
components:
  schemas:
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of items to return
          example: 10
        offset:
          type: integer
          description: Offset of the returned items
          example: 0
        total:
          type: integer
          description: Total number of items
          example: 100
      required:
      - limit
      - offset
      - total
    CallSmartNotes:
      type: object
      properties:
        callId:
          type: number
          description: ID of the call
        smartNotes:
          type: object
          description: Smart notes of the call
          properties:
            callDetails:
              $ref: '#/components/schemas/CallDetailsNote'
            actionItems:
              type: array
              description: Specific tasks assigned during the call
              items:
                type: string
            decisionsMade:
              type: array
              description: Important decisions agreed upon during the call
              items:
                type: string
            openQuestions:
              type: array
              description: Questions that need to be addressed after the call
              items:
                type: string
            importantDatesAndDeadlines:
              $ref: '#/components/schemas/ImportantDatesAndDeadlinesNotes'
            risksAndIssues:
              type: array
              description: Identify potential risks or issues discussed during the call
              items:
                type: string
            customerFeedback:
              type: array
              description: Highlight feedback from customers that can inform product development or service improvement
              items:
                type: string
          required:
          - callDetails
      required:
      - callId
      - smartNotes
      example:
        callId: 12345
        smartNotes:
          callDetails:
            callDateTime: '2024-01-01T21:00:00Z'
            participants:
            - name: Jone Smith
              jobPosition: Job position
              company: Company
              callerType: agent
            - name: Tatiana Rogers
              callerType: contact
            callMetadata: Reservation number
          actionItems:
          - Determine the final price
          decisionsMade:
          - Make an order
          openQuestions:
          - Final price
          importantDatesAndDeadlines:
          - dateMention: '2024-01-11T10:00:00Z'
            eventDescription: Repeat the call
          risksAndIssues:
          - Concern about the cost of the services
          customerFeedback:
          - Good service
    CallTopicSpan:
      type: object
      properties:
        end:
          type: number
          description: End time of the span in seconds
        text:
          type: string
          description: Transcription of the span
        start:
          type: number
          description: Start time of the span in seconds
        caller:
          type: string
          description: Caller local identifier
      required:
      - end
      - text
      - start
      - caller
    ImportantDatesAndDeadlinesNotes:
      type: array
      description: Capture significant dates mentioned, with clickable links to add them directly to the calendar
      items:
        type: object
        properties:
          dateMention:
            type: string
            description: Date and time of the event
            format: date-time
          eventDescription:
            type: string
            description: Description of the event
        required:
        - dateMention
        - eventDescription
    CallTopics:
      type: object
      properties:
        data:
          type: object
          properties:
            callId:
              type: number
              description: ID of the call
            topics:
              type: array
              items:
                $ref: '#/components/schemas/CallTopic'
            callers:
              type: array
              items:
                $ref: '#/components/schemas/Caller'
          required:
          - callId
          - topics
          - callers
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
      example:
        data:
          callId: 12345
          topics:
          - spans:
            - end: 3.182
              text: Let's start the discussion in this group.
              start: 1.867
              caller: caller1
            topic: Group Call
            weight: 0.5
          callers:
          - id: 5000
            type: contact
            localIdentifier: caller1
          - id: 1000
            type: agent
            localIdentifier: caller2
        pagination:
          limit: 1
          offset: 0
          total: 10
    CallDetailsNote:
      type: object
      description: Significant updates discussed during the call
      properties:
        callDateTime:
          type: string
          description: Date and time of the call
          format: date-time
        participants:
          type: array
          description: Name, position and company of participants of the call
          items:
            type: object
            properties:
              name:
                type: string
                description: First and last name
              jobPosition:
                type: string
                description: Job position
              company:
                type: string
                description: Company name
              callerType:
                type: string
                description: Caller type
                enum:
                - agent
                - contact
            required:
            - callerType
        callMetadata:
          type: string
          description: Metadata such as location, reservation number, etc
      required:
      - callDateTime
      - participants
    CallTopic:
      type: object
      properties:
        spans:
          type: array
          items:
            $ref: '#/components/schemas/CallTopicSpan'
        topic:
          type: string
          description: Topic of the call
        weight:
          type: number
          description: Weight of the topic
      required:
      - spans
      - topic
      - weight
    DialerError:
      type: object
      description: Error envelope returned by every Dialer API endpoint. Note it differs from the legacy API's error format.
      properties:
        statusCode:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
        error:
          type: string
          description: HTTP error name
        correlationId:
          type: string
          description: Request correlation ID — include it when contacting support
          example: YevPQs
        subErrors:
          type: array
          items:
            type: string
          description: Field-level validation messages, present on validation failures
          example:
          - incorrect email
      required:
      - statusCode
      - message
      - error
      - correlationId
    CallTranscription:
      type: object
      properties:
        data:
          type: object
          properties:
            callId:
              type: number
              description: ID of the call
            segments:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: number
                    description: Start time of the segment in seconds
                  end:
                    type: number
                    description: End time of the segment in seconds
                  caller:
                    type: string
                    description: Caller local identifier
                  text:
                    type: string
                    description: Transcription text of the segment
                required:
                - start
                - end
                - caller
                - text
            callers:
              type: array
              items:
                $ref: '#/components/schemas/Caller'
            language:
              type: string
              description: Language of the transcription
          required:
          - callId
          - segments
          - callers
          - language
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
      example:
        data:
          callId: 12345
          segments:
          - start: 1.501
            end: 4.599
            caller: caller2
            text: Hello, I would like to ask for help.
          - start: 5.173
            end: 8.599
            caller: caller1
            text: Hi. What's your issue?
          callers:
          - id: 5000
            type: contact
            localIdentifier: caller1
          - id: 1000
            type: agent
            localIdentifier: caller2
          language: en
        pagination:
          limit: 2
          offset: 0
          total: 10
    CallTalkListenRatio:
      type: object
      properties:
        callId:
          type: number
          description: ID of the call
        talkListenRatio:
          type: array
          items:
            type: object
            properties:
              caller:
                type: string
                description: Caller local identifier
              talkingTime:
                type: number
                description: Talking time of the caller in seconds
              ratio:
                type: number
                description: Talk to listen ratio of the caller in percentage
            required:
            - caller
            - talkingTime
            - ratio
        callers:
          type: array
          items:
            $ref: '#/components/schemas/Caller'
      required:
      - callId
      - talkListenRatio
      - callers
      example:
        callId: 12345
        talkListenRatio:
        - caller: caller1
          talkingTime: 120
          ratio: 60
        - caller: caller2
          talkingTime: 80
          ratio: 40
        callers:
        - id: 5000
          type: contact
          localIdentifier: caller1
        - id: 1000
          type: agent
          localIdentifier: caller2
    CallOverallSentiment:
      type: object
      properties:
        callId:
          type: number
          description: ID of the call
        overallSentiment:
          type: string
          description: Overall sentiment of the call
          enum:
          - very negative
          - negative
          - neutral
          - positive
          - very positive
      required:
      - callId
      - overallSentiment
      example:
        callId: 12345
        overallSentiment: positive
    Caller:
      type: object
      properties:
        type:
          type: string
          enum:
          - agent
          - contact
          description: Type of caller
        id:
          type:
          - integer
          - 'null'
          description: Caller ID if exists in the system
        localIdentifier:
          type: string
          description: Local identifier of the caller
      required:
      - id
      - type
      - localIdentifier
      example:
        id: 1000
        type: agent
        localIdentifier: caller1
  parameters:
    callId:
      name: callId
      in: path
      required: true
      description: Call ID
      schema:
        type: number
    paginationLimit:
      name: limit
      in: query
      description: Maximum number of items to return
      required: false
      schema:
        type: integer
        minimum: 1
    paginationOffset:
      name: offset
      in: query
      description: Offset the list of returned items by this amount
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DialerError'
          example:
            statusCode: 404
            message: Not Found
            error: Not Found
            correlationId: YevPQs
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DialerError'
          example:
            statusCode: 400
            message: Validation error
            error: Bad Request
            correlationId: YevPQs
            subErrors:
            - incorrect email
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            description: Error envelope returned by the authentication layer in front of the `api.cloudtalk.io/v1` surface. It differs from the per-service error shapes used for other statuses.
            properties:
              code:
                type: string
                description: Error code
                example: UNAUTHORIZED
              message:
                type: string
                description: Error message
                example: You are not authorized to access this resource.
            required:
            - code
            - message
          example:
            code: UNAUTHORIZED
            message: You are not authorized to access this resource.
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DialerError'
          example:
            statusCode: 500
            message: Internal Server Error
            error: Internal Server Error
            correlationId: YevPQs
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).
x-provenance:
  method: harvested
  publisher: CloudTalk
  source: https://help.cloudtalk.io/api-reference/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)