openapi: 3.0.3
info:
  title: Voiso API
  description: 'The Voiso APIs follow a conventional REST architecture, making it
    compatible with any programming language.


    Use these APIs for secure and reliable data access and the ability to manage features,
    settings, and entities within a contact center.

    '
  version: 1.0.0
  contact:
    name: Support
    email: support@voiso.com
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: "{cluster_id}.voiso.com"

  - url: https://cc-ams03.voiso.com
  - url: https://cc-ams04.voiso.com
  - url: https://cc-ams05.voiso.com
  - url: https://cc-rtm01.voiso.com
  - url: https://cc-sng01.voiso.com
tags:
- name: WhatsApp Messaging
- name: User Management
- name: Conversations
- name: Scheduled Callback
- name: Number Management
- name: Campaigns
- name: CDR
- name: Inbound Routing
- name: Agent Application
- name: SMS
- name: Click2Call
- name: Balance
paths:
  /api/v3/messages/whatsapp:
    post:
      operationId: sendWhatsAppMessages
      tags:
      - WhatsApp Messaging
      description: 'Initiate outbound conversations through WhatsApp.


        A maximum of 50 requests per second and 100 messages per second
        are allowed.

        '
      security:
      - callcenterApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  description: The originating WhatsApp phone number used by your
                    contact center.
                  type: string
                  format: phone
                  example: '18885658889'
                template_uuid:
                  description: The unique identifier assigned to the message template.
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                recipients:
                  description: An array of phone numbers and account IDs for the message
                    recipients.
                  type: array
                  items:
                    type: object
                    properties:
                      to:
                        description: The WhatsApp phone number for the message recipient.
                        type: string
                        format: phone
                        example: '18885658889'
                      account_id:
                        description: An identifier assigned to the contact in an external
                          application such as a CRM.
                        type: string
                        example: AC001
                      template_data:
                        description: 'An array of data to be substituted for placeholders
                          in the template.


                          If the template does not require any params, the `template_data`
                          section can be omitted.

                          '
                        type: array
                        items:
                          type: object
                          properties:
                            body:
                              type: array
                              items:
                                type: object
                                properties:
                                  placeholders:
                                    type: array
                                    items:
                                      type: string
                                    example:
                                    - John Doe
                                    - $100.00
                                    - Jan 12, 2025
                                required:
                                - placeholders
                          required:
                          - body
                    required:
                    - to
                agent:
                  description: The agent's contact center phone extension to
                    tell Voiso who to assign the interaction to.


                    If you intend to automatically archive this message after sending
                    it, this field can be ommited.

                    '
                  type: string
                  example: '101'
              required:
              - from
              - template_uuid
              - recipients
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: The 'sent' status of the message.
                    type: array
                    items:
                      oneOf:
                      - type: object
                        description: The message was successfully sent.
                        properties:
                          to:
                            description: The message recipient's WhatsApp phone number.
                            type: string
                            format: phone
                            example: '18885658889'
                          success:
                            description: Indicates whether the message was sent successfully.
                            type: boolean
                            default: true
                            example: true
                          uuid:
                            description: The conversation identifier.
                            type: string
                            format: uuid
                            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      - type: object
                        description: The message failed to send.
                        properties:
                          to:
                            description: The message recipient's WhatsApp phone number.
                            type: string
                            format: phone
                            example: '18885658889'
                          success:
                            description: Indicates that message sending failed.
                            type: boolean
                            default: false
                            example: false
                          errors:
                            type: array
                            items:
                              type: string
                              enum:
                              - Invalid destination
                              - The message to this destination already exists
                              - 'Parameter mismatch: the specified template requires
                                %<placeholders_count>s parameters, but request contains
                                %<parameters_count>s parameters.

                                '
                              example: Invalid destination
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: An array of error messages.
                    type: array
                    items:
                      type: string
                      enum:
                      - Invalid sender
                      - Invalid message template UUID
                      - Invalid 'template_uuid' for specified 'from' option
                      - Provide at least one destination number
                      - Invalid agent extension
                      - The agent settings for sending WhatsApp messages are incorrect
                      - The API key specified is invalid
                      - WhatsApp Outbound Messaging is disabled for your contact
                        center. Please contact support@voiso.com to enable this function
                      - API message rate limit exceeded
                      - API rate limit exceeded
                      example: Invalid sender
      summary: Send WhatsApp messages
  /api/v3/messages/whatsapp/templates:
    get:
      operationId: listWhatsAppTemplates
      tags:
      - WhatsApp Messaging
      description: 'Obtain a list of all your contact center WhatsApp message template
        names and details.


        A maximum of 50 requests per second is allowed.

        '
      security:
      - callcenterApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    description: An array of all your WhatsApp message templates.
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          description: 'The unique ID number of the template.


                            Use this value to populate the `template_uuid` field when
                            sending messages.

                            '
                          type: string
                          format: uuid
                          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        name:
                          description: The name of the template.
                          type: string
                          example: greetings_001
                        category:
                          description: The WhatsApp template category name.
                          type: string
                          example: MARKETING
                        language:
                          description: The two- or four-letter language code indicating
                            the template language.
                          type: string
                          example: en_US
                        body:
                          description: The message text of the template
                          type: string
                          example: Hello {{1}}. Thank you for contacting us! Please reply
                            to this message if you want to continue the conversation.
                        number:
                          description: The business phone number associated with the
                            template.
                          type: string
                          format: phone
                          example: '18885658889'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: An array of error messages.
                    type: array
                    items:
                      type: string
                      enum:
                      - Your contact center has no associated message templates
                      - The API key specified is invalid
                      - WhatsApp Outbound Messaging is disabled for your contact
                        center. Please contact support@voiso.com to enable this function
                      - API rate limit exceeded
                      example: Your contact center has no associated message templates
      summary: List WhatsApp templates
  /api/user_management/v1/users:
    get:
      operationId: listUsers
      tags:
      - User Management
      description: Obtain a list of all users in your contact center.
      security:
      - callcenterBearerToken: []
      parameters:
      - name: id
        in: query
        description: The list of comma-separated user IDs.
        schema:
          type: string
          example: 13567,13568,13864
      - name: name
        in: query
        description: A comma-separated list of user names.
        schema:
          type: string
          example: John Doe,Jane Smith,Alice Johnson
      - name: email
        in: query
        description: A comma-separated list of user email addresses.
        schema:
          type: string
          example: john@contactcenter.com,jane@contactcenter.com,alice@contactcenter.com
      - name: sip_account
        in: query
        description: A comma-separated list of user SIP addresses.
        schema:
          type: string
          example: john@contactcenter.com,jane@contactcenter.com,alice@contactcenter.com
      - name: sag
        in: query
        description: A comma-separated list of Security Access Group names.
        schema:
          type: string
          example: Agents,Supervisors,Managers
      - name: extension
        in: query
        description: A comma-separated list of user extensions.
        schema:
          type: string
          example: 100,101,112
      - name: caller_id
        in: query
        description: A comma-separated list of Caller ID group names.
        schema:
          type: string
          example: 18885658889,18885658890,18885658954
      - name: timezone
        in: query
        description: A comma-separated list of time zone names.
        schema:
          type: string
          example: America/New_York,America/Los_Angeles,UTC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the user.
                      type: integer
                      example: 13567
                    name:
                      description: The name of the user.
                      type: string
                      example: John Doe
                    email:
                      description: The email address of the user.
                      type: string
                      format: email
                      example: john@contactcenter.com
                    sip_account:
                      description: The SIP address of the user.
                      type: string
                      format: email
                      example: john@contactcenter.com
                    sag:
                      description: The name of the Security Access Group to which
                        the user is assigned.
                      type: string
                      example: Supervisors
                      nullable: true
                    extension:
                      description: The contact center extension used to route calls
                        to the user.
                      type: string
                      example: '101'
                      nullable: true
                    caller_id:
                      description: The name of the Caller ID group to which the user
                        is assigned.
                      type: string
                      format: phone
                      example: '18885658889'
                      nullable: true
                    timezone:
                      description: The name of the time zone specified for the user.
                      type: string
                      example: America/New_York
                    webrtc_ringtone:
                      description: The ringtone assigned to the user.
                      type: object
                      nullable: true
                      properties:
                        url:
                          type: string
                          example: /uploads/ringtone/file/13/original/telephone-ring-04.mp3
                        wav:
                          type: object
                          properties:
                            url:
                              type: string
                              example: /uploads/ringtone/file/13/audio.wav
                    assigned_teams:
                      description: A comma-separated list of the IDs of the Teams
                        to which the user is assigned.
                      type: string
                      example: 1081, 1241, 1245
                    supervisor_in_teams:
                      description: A comma-separated list of the IDs of the Teams
                        that the user supervises.
                      type: string
                      example: 1023, 1027
                    assigned_queues:
                      description: A comma-separated list of queue names.
                      type: string
                      example: Priority, Regular, Omnichannel
                    assigned_skills:
                      description: An array of the user's skills.
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            description: The name of the skill.
                            type: string
                            example: Sales
                          value:
                            description: The skill level. An integer from 1 to 10,
                              where 10 is the highest skill level.
                            type: integer
                            example: 3
                    assigned_channels:
                      description: An array of digital channels assigned to the user.
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            description: Digital channel type
                            type: string
                            enum:
                            - chat
                            - facebook
                            - instagram
                            - telegram
                            - viber
                            - whatsapp
                            example: whatsapp
                          name:
                            description: The name of the channel.
                            type: string
                            example: WhatsApp Main (18885658889)
                          value:
                            description: Phone number or Sender ID associated with
                              the channel
                            type: string
                            format: phone
                            example: '18885658889'
                            nullable: true
                    employee_id:
                      description: The value assigned to the user in the Employee
                        ID field of the user profile.
                      type: string
                      example: S1709
                      nullable: true
        '401':
          $ref: '#/components/responses/401'
      summary: List users
  /api/conversation/v1/conversations/{uuid}/messages:
    get:
      operationId: listConversationMessages
      tags:
      - Conversations
      description: Obtain a list of messages in a conversation.
      security:
      - userBearerToken: []
      parameters:
      - name: uuid
        in: path
        description: The unique identifier of the conversation.
        required: true
        schema:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      - name: limit
        in: query
        description: The maximum number of messages to return.
        schema:
          type: integer
          example: 50
          default: 25
          maximum: 500
          minimum: 0
      - name: offset
        in: query
        description: The number of messages to skip before starting to return messages.
        schema:
          type: integer
          example: 0
          default: 0
          minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          description: The unique identifier of the message or event.
                          type: string
                          format: uuid
                          example: bab03e86-a2b3-49fa-abb5-79d9b11367fe
                        conversation_id:
                          description: The unique identifier of the conversation.
                          type: string
                          format: uuid
                          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        activity:
                          description: The entity type.
                          type: string
                          enum:
                          - message
                          - event
                          example: message
                        activity_type:
                          description: The direction of the message or the event type.
                          type: string
                          enum:
                          - inbound
                          - outbound
                          - whisper
                          - accept
                          - forward_to_queue
                          - accept_forwarding
                          - intercept
                          - archive
                          - terminate
                          - disconnect
                          - start_monitoring
                          - stop_monitoring
                          - start_whispering
                          - stop_whispering
                          - start_barging_in
                          - stop_barging_in
                          - business_initiated_wait
                          - force_close
                          example: outbound
                        content_type:
                          description: The message content type. Blank for
                            events.
                          type: string
                          enum:
                          - audio
                          - callback
                          - document
                          - image
                          - template
                          - text
                          - video
                          - voice
                          - ''
                          example: text
                        content_data:
                          description: The message content.
                          oneOf:
                          - description: Text message.
                            type: object
                            properties:
                              text:
                                description: The text of the message.
                                type: string
                                example: Hello, how can I help you?
                          - description: Media message.
                            type: object
                            properties:
                              url:
                                description: The URL of the media file.
                                type: string
                                example: https://voiso.com/omni/media/ext/eyJhbGciOiJI/king_of_stephens.jpg
                              filename:
                                description: The filename of the media file.
                                type: string
                                example: king_of_stephens.jpg
                              size:
                                description: The size of the media file in bytes.
                                type: integer
                                example: 56775
                          - description: Callback message (click the button).
                            type: object
                            properties:
                              data:
                                description: The value of the callback button.
                                type: string
                                example: button-IVJvNReIwjgv-nm7cFttR
                              text:
                                description: The text of the button.
                                type: string
                                example: Option 1
                          - description: Template message.
                            type: object
                            properties:
                              id:
                                description: The unique identifier of the template.
                                type: string
                                format: uuid
                                example: 0194959c-1241-7289-88ae-1477c410e49b
                              whatsapp_template_id:
                                description: The unique identifier of the WhatsApp
                                  template.
                                type: string
                                format: uuid
                                example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                              body:
                                description: The message text of the template.
                                type: string
                                example: Hello John Doe. Thank you for contacting
                                  us! Please reply to this message if you want to continue
                                  the conversation.
                              category:
                                description: The WhatsApp template category name.
                                type: string
                                example: MARKETING
                              language:
                                description: The two- or four-letter language code indicating
                                  the template language.
                                type: string
                                example: en_US
                              components:
                                description: The array of placeholders in the template.
                                example:
                                  '1': John Doe
                                type: object
                        participant:
                          description: The conversation participant.
                          type: object
                          properties:
                            id:
                              description: The unique identifier of the participant
                                (user or contact).
                              type: integer
                              example: 13567
                            type:
                              description: The participant type.
                              type: string
                              enum:
                              - agent
                              - supervisor
                              - contact
                              example: agent
                        attributes:
                          description: Reserved for future use.
                          type: object
                        status:
                          description: The current message status.
                          type: string
                          enum:
                          - initial
                          - accepted
                          - uploading
                          - waiting
                          - ready
                          - sent
                          - delivered
                          - seen
                          - whispered
                          - failed
                          example: failed
                        error_message:
                          description: The error context if the outbound message failed
                            to send.
                          type: string
                          example: Unsupported message content
                        created_at:
                          description: The date and time the message was created.
                          type: string
                          format: date-time
                          example: '2025-01-01T12:00:00.216Z'
                        updated_at:
                          description: The date and time the message was last updated.
                          type: string
                          format: date-time
                          example: '2025-01-01T12:00:00.987Z'
                  metadata:
                    type: object
                    properties:
                      total:
                        description: The total number of messages in the conversation.
                        type: integer
                        example: 200
                      limit:
                        description: The maximum number of messages to return.
                        type: integer
                        example: 25
                      offset:
                        description: The number of messages to skip before starting
                          to return messages.
                        type: integer
                        example: 0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Specified parameters are not valid
                    example: Specified parameters are not valid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid API key
                    example: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - No access to API
                    example: No access to API
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Conversation not found
                    example: Conversation not found
      summary: Get conversation messages
    post:
      operationId: createConversationMessage
      tags:
      - Conversations
      description: Create a message in a conversation.
      deprecated: true
      x-readme:
        display: false
      security:
      - userBearerToken: []
      parameters:
      - name: uuid
        in: path
        description: The unique identifier of the conversation.
        required: true
        schema:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - description: Text message.
                type: object
                properties:
                  content_type:
                    description: The message content type.
                    type: string
                    enum:
                    - text
                    example: text
                  content_data:
                    description: The message content.
                    type: object
                    properties:
                      text:
                        description: The text of the message.
                        type: string
                        maxLength: 4096
                        example: Hello, how can I help you?
                    required:
                    - text
                required:
                - content_type
                - content_data
              - description: Media message.
                type: object
                properties:
                  content_type:
                    description: 'The message content type.


                      Supported media types depend on the conversation channel:

                      | Channel   | Types                                 |

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

                      | WhatsApp  | `image`, `video`, `audio`, `document` |

                      | Chat      | `image`, `document`                   |

                      | Facebook  | `image`, `video`, `audio`, `document` |

                      | Instagram | `image`                               |

                      | Telegram  | `image`, `video`, `audio`, `document` |

                      | Viber     | `image`, `document`                   |

                      '
                    type: string
                    enum:
                    - audio
                    - document
                    - image
                    - video
                    example: image
                  content_data:
                    description: The message content.
                    type: object
                    properties:
                      url:
                        description: 'The URL of the media file.


                          Supported mime types and maximum sizes of media files depend
                          on the conversation channel. The URL must be accessible
                          by Voiso servers.

                          '
                        type: string
                        example: https://yourwebsite.com/storage/king_of_stephens.jpg
                    required:
                    - url
                required:
                - content_type
                - content_data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The unique identifier of the message.
                    type: string
                    format: uuid
                    example: bab03e86-a2b3-49fa-abb5-79d9b11367fe
                  conversation_id:
                    description: The unique identifier of the conversation.
                    type: string
                    format: uuid
                    example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  activity:
                    description: The entity type.
                    type: string
                    enum:
                    - message
                    example: message
                  activity_type:
                    description: The direction of the message.
                    type: string
                    enum:
                    - outbound
                    example: outbound
                  content_type:
                    description: The message content type.
                    type: string
                    enum:
                    - audio
                    - document
                    - image
                    - text
                    - video
                    example: text
                  content_data:
                    description: The message content.
                    oneOf:
                    - description: Text message.
                      type: object
                      properties:
                        text:
                          description: The text of the message.
                          type: string
                          example: Hello, how can I help you?
                    - description: Media message.
                      type: object
                      properties:
                        url:
                          description: The URL of the media file.
                          type: string
                          example: https://voiso.com/omni/media/ext/eyJhbGciOiJI/king_of_stephens.jpg
                        filename:
                          description: The filename of the media file.
                          type: string
                          example: king_of_stephens.jpg
                        size:
                          description: The size of the media file in bytes.
                          type: integer
                          example: 56775
                  participant:
                    description: The conversation participant.
                    type: object
                    properties:
                      id:
                        description: The unique identifier of the agent.
                        type: integer
                        example: 13567
                      type:
                        description: The participant type.
                        type: string
                        enum:
                        - agent
                        example: agent
                  attributes:
                    description: Reserved for future use.
                    type: object
                  status:
                    description: The current message status.
                    type: string
                    enum:
                    - waiting
                    - ready
                    - failed
                    example: failed
                  error_message:
                    description: The error context if the outbound message failed
                      to send.
                    type: string
                    example: Unsupported message content
                  created_at:
                    description: The date and time the message was created.
                    type: string
                    format: date-time
                    example: '2025-01-01T12:00:00.216Z'
                  updated_at:
                    description: The date and time the message was last updated.
                    type: string
                    format: date-time
                    example: '2025-01-01T12:00:00.987Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: An array of error messages.
                    type: array
                    items:
                      type: string
                      enum:
                      - This interaction_id is invalid. Please try again.
                      - This agent is not assigned to this conversation. Please try
                        again.
                      - This message cannot exceed the maximum limit of 4096 characters.
                        Please try again.
                      - This filename is invalid. Please try again.
                      - This media type is not supported. Please try again.
                      - This file cannot exceed the maximum size of %<max_size>s MB.
                        Please try again
                      - Content data is invalid. Please try again.
                      - Provided url is invalid. Please try again.
                      example: The message cannot exceed the maximum limit of 4096
                        characters. Please try again.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid API key
                    example: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - No access to API
                    example: No access to API
      summary: Create conversation message
  /api/task/v1/scheduled_callbacks:
    post:
      operationId: createScheduledCallback
      tags:
      - Scheduled Callback
      description: Create a scheduled callback.
      security:
      - callcenterBearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_number:
                  description: Phone number for the callback.
                  type: string
                  format: phone
                  example: '18885658889'
                agent:
                  description: The email address of the agent handling the callback.
                  type: string
                  format: email
                  example: john@contactcenter.com
                scheduled_time:
                  description: 'The time of the scheduled callback.


                    The time must be specified in UTC and formatted according to ISO
                    8601 (`2025-01-01T10:30:00Z`).

                    Hours must be between 08 and 22 after converting to the specified
                    `time_zone`.

                    For most time zones, only 00 and 30 are accepted for minutes. For
                    time zones with a 15-minute offset (e.g., Asia/Kathmandu, Australia/Eucla,
                    Pacific/Chatham), only 15 and 45 are accepted.

                    Seconds must be 00.

                    '
                  type: string
                  format: date-time
                  example: '2025-01-01T12:30:00Z'
                time_zone:
                  description: 'The contact''s time zone.


                    If the `time_zone` is not specified, the contact''s time zone
                    is assumed to be the same as the agent''s time zone.

                    '
                  type: string
                  example: America/New_York
                context_notes:
                  description: Information about the call for the agent.
                  type: string
                  maxLength: 64
                  example: The new product launch
                cid_group:
                  description: 'The Caller ID group for the callback.


                    The default Caller ID for the contact center is used unless a different one is specified.

                    '
                  type: string
                  example: '18885657700'
                related_call_id:
                  description: The UUID of a call related to the callback.
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                external_contact_id:
                  description: The ID of the contact in an external CRM.
                  type: string
                  example: AC001
                external_system_id:
                  description: The name of the external CRM.
                  type: string
                  example: mycrm
              required:
              - contact_number
              - agent
              - scheduled_time
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The unique identifier of the scheduled callback.
                    type: integer
                    example: 13567
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Scheduled Callbacks feature is disabled
                    - Agent does not have access
                    example: Scheduled Callbacks feature is disabled
        '422':
          $ref: '#/components/responses/422'
      summary: Create scheduled callback
  /api/numbers/v1/numbers:
    get:
      operationId: listNumbers
      tags:
      - Number Management
      description: Retrieve a list of the phone numbers owned by your contact center.
      security:
      - callcenterBearerToken: []
      parameters:
      - name: page
        in: query
        description: The page number to return.
        schema:
          type: integer
          example: 1
          default: 1
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  numbers:
                    description: An array of all the numbers you own.
                    type: array
                    items:
                      type: object
                      properties:
                        number:
                          description: The phone number.
                          type: string
                          format: phone
                          example: '18885658889'
                        label:
                          description: The custom name your contact center applied
                            to the number.
                          type: string
                          example: Main Line
                        type:
                          description: The phone number type.
                          type: string
                          enum:
                          - mobile
                          - national
                          - toll_free
                          - shared_cost
                          - geographic
                          example: national
                        country:
                          description: The destination country of the number.
                          type: string
                          example: United States
                        city:
                          description: The desitnation city of the number.
                          type: string
                          example: New York
                        provider:
                          description: The name of the number source.
                          type: string
                          enum:
                          - Voiso
                          - 3rd party
                          example: Voiso
                        activation_fee:
                          description: The number activation fee.
                          type: string
                          format: number
                          example: '3.49'
                        monthly_fee:
                          description: The monthly fee to use the number.
                          type: string
                          format: number
                          example: '3.49'
                        script:
                          description: The script associated with the number.
                          type: object
                          nullable: true
                          properties:
                            id:
                              description: The unique identifier of the script.
                              type: integer
                              example: 13567
                            name:
                              description: The name of the script.
                              type: string
                              example: Main Script
                        flow:
                          description: The flow associated with the number.
                          type: object
                          nullable: true
                          properties:
                            id:
                              description: The unique identifier of the flow.
                              type: integer
                              example: 13567
                            name:
                              description: The name of the flow.
                              type: string
                              example: Main Flow
                        cid_groups:
                          description: The Caller ID groups associated with the number.
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                description: The unique identifier of the Caller ID
                                  group.
                                type: integer
                                example: 13567
                              name:
                                description: The name of the Caller ID group.
                                type: string
                                example: US1
                        created_at:
                          description: The date and time the number was first added.
                          type: string
                          format: date-time
                          example: '2025-01-01T12:00:00.216Z'
                  metadata:
                    description: Information about the request settings and response
                      content.
                    type: object
                    properties:
                      total:
                        description: The total number of phone numbers.
                        type: integer
                        example: 10
                      page:
                        description: The current page number.
                        type: integer
                        example: 1
                      page_size:
                        description: The number of phone numbers returned per page
                          in the response.
                        type: integer
                        default: 50
                        example: 50
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Bad request
                    example: Bad request
        '401':
          $ref: '#/components/responses/401'
      summary: List numbers
  /api/v1/{api_key}/campaigns/{campaign_id}/contacts:
    post:
      operationId: createCampaignContacts
      tags:
      - Campaigns
      description: 'Add new contacts to an existing live campaign.


        A maximum of 1000 contacts per minute is allowed. This limit is shared with
        the corresponding PUT request.

        '
      parameters:
      - name: api_key
        in: path
        description: User API key.
        required: true
        schema:
          type: string
          example: 9fdcd365a51432916f3a7569289d1f4363031e31ce12c589
      - name: campaign_id
        in: path
        description: The campaign ID.
        required: true
        schema:
          type: integer
          example: 16
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contacts:
                  type: array
                  items:
                    type: object
                    properties:
                      phoneNumber:
                        description: The contact's phone number in E.164 format.
                        type: string
                        format: phone
                        example: '18885658889'
                      contactName:
                        description: The contact's name is displayed on the agent's
                          softphone when the call is connected.
                        type: string
                        example: Robert Smith
                      contactSource:
                        description: Where the contact record was obtained.
                        type: string
                        example: crm_name
                      contactURL:
                        description: The URL for the CRM screen pop of the contact's
                          record.
                        type: string
                      priority:
                        description: The contact's priority for calling purposes.
                          Lower values equal higher priority. Low priority value contacts are called first. Contacts with no priority set are called last.
                        type: integer
                        minimum: 0
                        maximum: 1000
                        example: 50
                      isActive:
                        description: An indication of whether or not the contact should
                          be called for this campaign.
                        type: boolean
                        default: true
                        example: true
                    required:
                    - phoneNumber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  duplicate_numbers:
                    description: Phone numbers that already exist in the campaign
                      or that you are trying to add multiple times.
                    type: array
                    items:
                      type: string
                      format: phone
                      example: '18885658889'
                  invalid_numbers:
                    description: Phone numbers that are not in the E.164 format.
                    type: array
                    items:
                      type: string
                      example: '0011223355'
                  contacts:
                    description: Phone numbers successfully added to the campaign.
                    type: array
                    items:
                      type: string
                      format: phone
                      example: '18885658889'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - Invalid campaign. Campaign status should be active, paused, or
                      draft
                    - Campaign type should be live
                    - Required contacts field - phoneNumber
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid key
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Campaign not found
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: You have reached the limit of contacts created per minute
      summary: Add campaign contacts
    put:
      operationId: updateCampaignContacts
      tags:
      - Campaigns
      description: 'Update existing contacts in existing live campaign.


        A maximum of 1000 contacts per minute is allowed. This limit is shared with
        the corresponding POST request.

        '
      parameters:
      - name: api_key
        in: path
        description: User API key.
        required: true
        schema:
          type: string
          example: 9fdcd365a51432916f3a7569289d1f4363031e31ce12c589
      - name: campaign_id
        in: path
        description: The campaign ID.
        required: true
        schema:
          type: integer
          example: 16
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contacts:
                  type: array
                  items:
                    type: object
                    properties:
                      phoneNumber:
                        description: The contact's phone number in E.164 format.
                        type: string
                        format: phone
                        example: '18885658889'
                      contactName:
                        description: The name of the contact to be displayed on the agent's
                          softphone when the call is connected.
                        type: string
                        example: Robert Smith
                      contactSource: 
                        description: Where the contact record was obtained.
                        type: string
                        example: crm_name
                      contactURL:
                        description: The URL for the CRM screen pop of the contact's
                          record.
                        type: string
                      priority:
                        description: The contact's priority for calling purposes.
                          Lower values equal higher priority. Low priority value contacts are called first. Contacts with no priority set are called last.
                        type: integer
                      isActive:
                        description: An indication of whether or not the contact should
                          be called for this campaign.
                        type: boolean
                        default: true
                        example: true
                    required:
                    - phoneNumber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  numbers_not_found:
                    description: Phone numbers that do not exist in the campaign or
                      that you are trying to update more than once.
                    type: array
                    items:
                      type: string
                      format: phone
                      example: '18885658889'
                  invalid_numbers:
                    description: Phone numbers that are not in the E.164 format.
                    type: array
                    items:
                      type: string
                      example: '0011223355'
                  contacts:
                    description: Phone numbers successfully updated in campaign.
                    type: array
                    items:
                      type: string
                      format: phone
                      example: '18885658889'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - Invalid campaign. Campaign status should be active, paused, or
                      draft
                    - Campaign type should be live
                    - Required contacts field - phoneNumber
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid key
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Campaign not found
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: You have reached the limit of contacts created per minute
      summary: Update campaign contacts
  /api/dialer/v1/campaigns:
    get:
      operationId: listCampaigns
      tags:
      - Campaigns
      description: List of all contact center campaigns and data based on the callcenter API key.
      security:
      - callcenterBearerToken: []
      parameters:
      - name: name
        in: query
        description: A campaign name.
        schema:
          type: string
          example: Campaign (154)
      - name: strategy
        in: query
        description: Single or multiple campaign strategy types, separated by commas.
        schema:
          type: string
          example: simple
          enum:
          - advanced
          - predictive_ai
          - simple
      - name: status
        in: query
        description: Single or multiple statuses of the campaign, separated by commas.
        schema:
          type: string
          example: active
          enum:
          - active
          - auto_paused
          - auto_pausing
          - completed
          - draft
          - import_error
          - paused
          - pausing
          - processing
          - stopped
          - stopping
      - name: method
        in: query
        description: Single or multiple methods of uploading numbers to the campaign,
          separated by commas.
        schema:
          type: string
          example: csv
          enum:
          - bitrix_crm
          - csv
          - dynamics_crm
          - falcon_crm
          - hubspot_crm
          - panda_crm
          - popcorn_crm
          - proftit_crm
          - puma_crm
          - salesforce_crm
          - zoho_crm
      - name: live
        in: query
        description: Whether or not the campaign type is live.
        schema:
          type: boolean
          example: true
      - name: limit
        in: query
        description: The maximum number of campaigns to return.
        schema:
          type: integer
          example: 50
          default: 25
          maximum: 500
          minimum: 0
      - name: offset
        in: query
        description: The number of campaigns to skip before starting to return campaigns.
        schema:
          type: integer
          example: 0
          default: 0
          minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    description: Campaigns data.
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          description: The unique identifier of the campaign.
                          type: integer
                          example: 27
                        name:
                          description: The name of the campaign.
                          type: string
                          example: Campaign (154)
                        status:
                          description: The current status of the campaign.
                          type: string
                          enum:
                          - active
                          - auto_paused
                          - auto_pausing
                          - completed
                          - draft
                          - import_error
                          - paused
                          - pausing
                          - processing
                          - stopped
                          - stopping
                          example: active
                        strategy:
                          description: The campaign strategy type.
                          type: string
                          enum:
                          - advanced
                          - predictive_ai
                          - simple
                          example: simple
                        method:
                          description: The method for uploading numbers to the campaign.
                          type: string
                          enum:
                          - bitrix_crm
                          - csv
                          - dynamics_crm
                          - falcon_crm
                          - hubspot_crm
                          - panda_crm
                          - popcorn_crm
                          - proftit_crm
                          - puma_crm
                          - salesforce_crm
                          - zoho_crm
                          example: csv
                        created_at:
                          description: The date and time that the campaign was created.
                          type: string
                          format: date-time
                          example: '2025-01-01T12:00:00.216Z'
                        live:
                          description: Whether or not the campaign type is live.
                          type: boolean
                          example: true
                  metadata:
                    description: Information about the request settings and response
                      content.
                    type: object
                    properties:
                      total:
                        description: The total number of campaigns.
                        type: integer
                        example: 200
                      limit:
                        description: The maximum number of campaigns to return.
                        type: integer
                        example: 25
                      offset:
                        description: The number of campaigns to skip before starting
                          to return campaigns.
                        type: integer
                        example: 0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: A set of error messages.
                    type: object
                    additionalProperties:
                      description: An array of error messages.
                      type: array
                      items:
                        type: string
                    example:
                      parameter1:
                      - is not a number
                      parameter2:
                      - is not included in the list
        '401':
          $ref: '#/components/responses/401'
      summary: List campaigns
  /api/v2/cdr:
    get:
      operationId: listCdrs
      tags:
      - CDR
      description: The Voiso CDR API enables you to query call detail records from
        your account using various query parameters.
      security:
      - userApiKey: []
      parameters:
      - name: agent_ids
        in: query
        description: 'Single or multiple agent IDs, separated by commas.

          These can be obtained using the `/api/v2/cdr/agents` method.

          '
        schema:
          type: string
          example: 1,6,12
      - name: campaign_ids
        in: query
        description: 'Single or multiple campaign IDs, separated by commas.

          These can be obtained using the `/api/dialer/v1/campaigns` method.

          '
        schema:
          type: string
          example: '16'
      - name: cli
        in: query
        description: The call line identity (CLI) calling number. A 'starting with'
          search of the ANI/From field.
        schema:
          type: integer
          example: 714
      - name: conversation_score
        in: query
        description: Score assigned to the conversation.
        schema:
          type: number
          example: 1.7
      - name: deleted_agent_ids
        in: query
        description: 'Single or multiple deleted agent IDs, separated by commas.

          These can be obtained using the `/api/v2/cdr/deleted_agents` method.

          '
        schema:
          type: string
          example: 1,7,8
      - name: destination_country
        in: query
        description: The name of the destination country. Valid for outbound calls only.
        schema:
          type: string
          example: Germany
      - name: dialing_time_from
        in: query
        description: Calls which have a dialing time longer than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: dialing_time_to
        in: query
        description: Calls which have a dialing time shorter than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: disposition
        in: query
        description: Retrieved call outcome.
        schema:
          type: string
          example: waiting
          enum:
          - abandoned
          - active
          - answered
          - answered_by_vm
          - archived
          - busy
          - delivered
          - dialer_abandoned
          - failed
          - initiated
          - machine_answered
          - missed
          - no_answer
          - not_delivered
          - not_sent
          - rejected
          - route_unavailable
          - sent
          - system_abandoned
          - system_reject
          - waiting
      - name: duration_from
        in: query
        description: Calls which have a duration longer than the specified value (in
          seconds).
        schema:
          type: integer
          example: 10
      - name: duration_to
        in: query
        description: Calls which have a duration shorter than the specified value (in
          seconds).
        schema:
          type: integer
          example: 10
      - name: end_date
        in: query
        description: Include only records on or before this date. Must be in the 'YYYY-MM-DD'
          format.
        schema:
          type: string
          format: date
          example: '2021-12-30'
      - name: end_datetime
        in: query
        description: Include only records on or before this datetime. Must be in the
          ISO 8601 format ('YYYY-MM-DD'T'HH:MM:SS').
        schema:
          type: string
          format: date-time
          example: '2021-12-30T12:30:45'
      - name: end_reason
        in: query
        description: Standard call end reasons.
        schema:
          type: string
          example: customer
          enum:
          - agent
          - customer
          - machine
          - manager
          - remote_party
          - system reject
          - timeout
      - name: event
        in: query
        description: Standard call events.
        schema:
          type: string
          example: intercept
          enum:
          - all_transfers
          - barge_in
          - blind_transfer
          - call_score
          - conference
          - consult_transfer
          - forward
          - intercept
          - monitor
          - terminate
          - whisper
      - name: first_seen
        in: query
        description: Set to true to get only new numbers that have never been dialed
          before.
        schema:
          type: boolean
          example: true
      - name: hold_time_from
        in: query
        description: Calls which have a hold time longer than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: hold_time_to
        in: query
        description: Calls which have a hold time shorter than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: ivr_time_from
        in: query
        description: Calls which have a pre-queue (IVR) time longer than the specified
          value (in seconds).
        schema:
          type: integer
          example: 10
      - name: ivr_time_to
        in: query
        description: Calls which have a pre-queue (IVR) time shorter than the specified
          value (in seconds).
        schema:
          type: integer
          example: 10
      - name: lead_source
        in: query
        description: 'Calls with a specified lead source type.

          Available only for dialer campaigns with a specified lead source.

          '
        schema:
          type: string
          example: crm_name
      - name: number
        in: query
        description: The called number. A 'starting with' search of the DNIS/To field.
        schema:
          type: string
          format: phone
          example: '18885658889'
      - name: page
        in: query
        description: The page number to return.
        schema:
          type: integer
          example: 1
          default: 1
          minimum: 1
      - name: per_page
        in: query
        description: The number of call records returned per page in the response.
        schema:
          type: integer
          example: 50
          default: 1000
      - name: queue_ids
        in: query
        description: 'Single or multiple queue IDs, separated by commas.

          These can be obtained using the `/api/v2/cdr/queues` method.

          '
        schema:
          type: string
          example: 1,7,8
      - name: queue_time_from
        in: query
        description: Calls which have a queue time longer than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: queue_time_to
        in: query
        description: Calls which have a queue time shorter than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: related_call_uuid
        in: query
        description: UUID of the parent call if a callback was requested from the
          queue.
        schema:
          type: string
          format: uuid
          example: 0b97ce11-b6e0-49b4-8f92-68040aa324bf
      - name: ring_time_from
        in: query
        description: Calls which have a ring time longer than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: ring_time_to
        in: query
        description: Calls which have a ring time shorter than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: search_token
        in: query
        description: Parameter used to query more then 10000 records.
        schema:
          type: string
          example: dkeouof13kjhk4HHH59
      - name: start_date
        in: query
        description: Include only records on or after this date. Must be in the 'YYYY-MM-DD'
          format.
        schema:
          type: string
          format: date
          example: '2021-12-30'
      - name: start_datetime
        in: query
        description: Include only records on or after this datetime. Must be in the
          ISO 8601 format ('YYYY-MM-DD'T'HH:MM:SS').
        schema:
          type: string
          format: date-time
          example: '2021-12-30T12:30:45'
      - name: talk_time_from
        in: query
        description: Calls which have a talk time longer than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: talk_time_to
        in: query
        description: Calls which have a talk time shorter than the specified value
          (in seconds).
        schema:
          type: integer
          example: 10
      - name: team_ids
        in: query
        description: 'Single or multiple agent team IDs, separated by commas.

          These can be obtained using the `/api/v2/cdr/teams` method.

          '
        schema:
          type: string
          example: 1,7,8
      - name: type
        in: query
        description: Direction or type of the interaction.
        schema:
          type: string
          example: outbound_sms
          enum:
          - callback
          - campaign
          - inbound
          - outbound
          - outbound_sms
          - hlr_lookup
          - queue-callback
          - scheduled-callback
          - chat
          - facebook
          - instagram
          - telegram
          - viber
          - whatsapp
      - name: uuid
        in: query
        description: UUID of CDR.
        schema:
          type: string
          format: uuid
          example: 7f076a6b-1fa7-494b-8e28-4ea899fbe086
      - name: wildcard_cli
        in: query
        description: The call line identity (CLI) calling number. An 'includes' search
          of the ANI/From field.
        schema:
          type: string
          example: '765'
      - name: wildcard_number
        in: query
        description: The called number. An 'includes' search of the DNIS/To field.
        schema:
          type: string
          example: '765'
      - name: wrapup_codes
        in: query
        description: 'Single or multiple wrap-up code IDs, separated by commas.

          These can be obtained using the `/api/v2/cdr/wrapup_codes` method.

          '
        schema:
          type: string
          example: 1,7,8
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    description: The current page number.
                    type: integer
                    example: 1
                  total:
                    description: The total number of records.
                    type: integer
                    example: 10
                  records:
                    description: Records data.
                    type: array
                    items:
                      oneOf:
                      - type: object
                        description: Call record.
                        properties:
                          agent:
                            description: The name of the user (agent or supervisor)
                              who first handled the call.
                            type: string
                            example: John Smith
                          from:
                            description: The ANI of a call.
                            type: string
                            format: phone
                            example: '18885658889'
                          disposition:
                            description: The end-of-call status.
                            type: string
                            enum:
                            - abandoned
                            - answered
                            - answered_by_vm
                            - busy
                            - dialer_abandoned
                            - failed
                            - machine_answered
                            - missed
                            - no_answer
                            - rejected
                            - system_abandoned
                            - system_reject
                            example: machine_answered
                          duration:
                            description: The length of the call in time format ('HH:MM:SS').
                            type: string
                            format: time
                            example: '14:50:17'
                          queue_name:
                            description: The inbound queue that distributed the call.
                            type: string
                            example: Queue 1
                          to:
                            description: The DNIS of the call.
                            type: string
                            format: phone
                            example: '18885658889'
                          timestamp:
                            description: The date and time that the call ended.
                            type: string
                            format: date-time
                            example: '2025-03-07T07:04:48.000Z'
                          uuid:
                            description: UUID of call record.
                            type: string
                            format: uuid
                            example: 7f076a6b-1fa7-494b-8e28-4ea899fbe086
                          wrapup_code:
                            description: The Wrap-up code assigned by the agent at
                              the end of the call.
                            type: string
                            example: '0001'
                          type:
                            description: Direction or type of call.
                            type: string
                            enum:
                            - callback
                            - campaign
                            - inbound
                            - outbound
                            - queue-callback
                            - scheduled-callback
                            example: inbound
                          agent_id:
                            description: The identifier of the user.
                            type: integer
                            example: 76
                          cpc:
                            description: The cost per call.
                            type: number
                            example: 0.0081
                      - type: object
                        description: SMS record.
                        properties:
                          agent:
                            description: The name of the user who sent the SMS.
                            type: string
                            example: John Smith
                          disposition:
                            description: SMS outcome.
                            type: string
                            enum:
                            - delivered
                            - not_delivered
                            - not_sent
                            - route_unavailable
                            - sent
                            example: delivered
                          timestamp:
                            description: The date and time that the SMS was sent,
                              in the time zone of the current user.
                            type: string
                            format: date-time
                            example: '2025-03-07T07:04:48.000Z'
                          uuid:
                            description: UUID of call record.
                            type: string
                            format: uuid
                            example: 7f076a6b-1fa7-494b-8e28-4ea899fbe086
                          type:
                            description: Direction or type of record.
                            type: string
                            enum:
                            - outbound_sms
                            example: outbound_sms
                          agent_id:
                            description: The user's identifier.
                            type: integer
                            example: 76
                          sid:
                            description: The Sender ID.
                            type: string
                            format: phone
                            example: '18885658889'
                          to:
                            description: The name of the receiver of the SMS.
                            type: string
                            format: phone
                            example: '76756092468'
                          cpc:
                            description: SMS cost.
                            type: number
                            example: 0.0081
                          text:
                            description: The body of the SMS.
                            type: string
                            example: Hi! Thank you for contacting us. How can I help
                              you?
                          related_call:
                            description: The UUID of the interaction related to the
                              SMS.
                            type: string
                            format: uuid
                            example: d008e2c0-55a1-4d99-9a95-de37cb0e2622
                          template:
                            description: The name of the canned message used for the
                              SMS.
                            type: string
                            example: Greeting message
                      - type: object
                        description: Digital interaction record.
                        properties:
                          agent:
                            description: The name of the user (agent or supervisor)
                              who first handled the conversation.
                            type: string
                            example: John Smith
                          from:
                            description: The name of the digital channel.
                            type: string
                            example: Whatsapp 1
                          disposition:
                            description: Status of digital interaction.
                            type: string
                            enum:
                            - active
                            - archived
                            - initiated
                            - waiting
                            example: waiting
                          duration:
                            description: The length of digital interaction in time
                              format ('HH:MM:SS').
                            type: string
                            format: time
                            example: '14:50:17'
                          to:
                            description: The name of the contact or contact's social media account.
                            type: string
                            example: Alisa Smith
                          timestamp:
                            description: The date and time that the interaction started,
                              in the time zone of the current user.
                            type: string
                            format: date-time
                            example: '2025-03-07T07:04:48.000Z'
                          uuid:
                            description: UUID of the interaction record.
                            type: string
                            format: uuid
                            example: 7f076a6b-1fa7-494b-8e28-4ea899fbe086
                          wrapup_code:
                            description: The Wrap-up code assigned by the agent at
                              the end of the interaction.
                            type: string
                            example: '0001'
                          type:
                            description: The interaction type.
                            type: string
                            enum:
                            - chat
                            - facebook
                            - instagram
                            - telegram
                            - viber
                            - whatsapp
                            example: whatsapp
                          cpc:
                            description: The interaction cost.
                            type: number
                            example: 0.0081
                          sla:
                            description: Service Level Agreement parameters that indicate
                              the time to complete each metric.
                            type: object
                            properties:
                              time_to_first_response:
                                description: The duration before an interaction assigned to an agent reaches the maximum allowed time for a first response. In time format ('HH:MM:SS').
                                type: string
                                format: time
                                example: 00:01:17
                              time_to_resolution:
                                description: The maximum time that an agent has to archive an interaction.
                                  In time format ('HH:MM:SS').
                                type: string
                                format: time
                                example: 00:01:17
                              time_to_reply:
                                description: The duration before an interaction assigned to an agent reaches the maximum allowed time for a reply to each text message from a contact. In time
                                  format ('HH:MM:SS').
                                type: string
                                format: time
                                example: 00:01:17
                          queue:
                            description: The inbound queue that distributed the interaction.
                            type: string
                            example: Queue 1
                      - type: object
                        description: HLR lookup record.
                        properties:
                          agent:
                            description: The name of the user (agent or supervisor)
                              who requested HLR lookup.
                            type: string
                            example: John Smith
                          from:
                            description: The number from which HLR lookup was requested.
                            type: string
                            format: phone
                            example: '18885658889'
                          disposition:
                            description: HLR lookup outcome.
                            type: string
                            enum:
                            - absent
                            - available
                            example: available
                          to:
                            description: The number for which HLR lookup was requested.
                            type: string
                            format: phone
                            example: '76756092468'
                          timestamp:
                            description: Timestamp of HLR lookup, in the time zone
                              of the current user.
                            type: string
                            format: date-time
                            example: '2025-03-07T07:04:48.000Z'
                          uuid:
                            description: UUID of lookup record.
                            type: string
                            format: uuid
                            example: 7f076a6b-1fa7-494b-8e28-4ea899fbe086
                          type:
                            description: Direction or type of record.
                            type: string
                            enum:
                            - hlr_lookup
                            example: hlr_lookup
                          agent_id:
                            description: The user's identifier.
                            type: integer
                            example: 76
                          cpc:
                            description: HLR lookup cost.
                            type: number
                            example: 0.01
                          related_call_uuid:
                            description: UUID of the parent call after which HLR lookup
                              was requested.
                            type: string
                            format: uuid
                            example: d008e2c0-55a1-4d99-9a95-de37cb0e2622
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Requested data is out of the 10000 limit.
                    - Invalid CDR search query
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List CDRs
  /api/v2/cdr/agents:
    get:
      operationId: listAgents
      tags:
      - User Management
      deprecated: true
      x-readme:
        display: false
      description: Obtain a list of all users you may access based on your user API
        key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the user.
                      type: integer
                      example: 73
                    name:
                      description: The name of the user.
                      type: string
                      example: John Smith
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List agents
  /api/v2/cdr/campaigns:
    get:
      operationId: listCdrCampaigns
      tags:
      - Campaigns
      deprecated: true
      x-readme:
        display: false
      description: Obtain a list of all campaigns you may access based on your user
        API key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the campaign.
                      type: integer
                      example: 124
                    name:
                      description: The name of the campaign.
                      type: string
                      example: Campaign (154)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: Campaign list
  /api/v2/cdr/deleted_agents:
    get:
      operationId: listDeletedAgents
      tags:
      - User Management
      description: Obtain a list of all deleted users you may access based on your
        user API key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the user.
                      type: integer
                      example: 73
                    name:
                      description: The name of the user.
                      type: string
                      example: John Smith
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List deleted users
  /api/v2/cdr/queues:
    get:
      operationId: listQueues
      tags:
      - Inbound Routing
      description: Obtain a list of all queues you may access based on your user API
        key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the queue.
                      type: integer
                      example: 13
                    name:
                      description: The name of the queue.
                      type: string
                      example: Sales queue
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List queues
  /api/v2/cdr/teams:
    get:
      operationId: listTeams
      tags:
      - User Management
      description: Obtain a list of all teams you may access based on your user API
        key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: The unique identifier of the team.
                      type: integer
                      example: 13
                    name:
                      description: The name of the team.
                      type: string
                      example: Sales team (1)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List teams
  /api/v2/cdr/wrapup_codes:
    get:
      operationId: listWrapupCodes
      tags:
      - Agent Application
      description: Obtain a list of all wrap-up codes you may access based on your
        user API key.
      security:
      - userApiKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    description:
                      description: The wrap-up code number and its associated
                        code name.
                      type: string
                      example: '0100: Qualified Lead'
                    code:
                      description: The wrap-up code number.
                      type: string
                      example: '0100'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - CDR API is not allowed
                    example: CDR API is not allowed
      summary: List wrapup codes
  /api/v1/{api_key}/agents_status:
    get:
      operationId: listAgentsStatuses
      tags:
      - Agent Application
      description: Obtain a list of users with their email, extension, and current
        status.
      parameters:
      - $ref: '#/components/parameters/CallcenterApiKey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email:
                      description: The agent's email.
                      type: string
                      format: email
                      example: john@contactcenter.com
                    ext:
                      description: The agent's extension.
                      type: string
                      example: 0084
                    status:
                      description: Available agent status.
                      type: string
                      enum:
                      - available
                      - dialer
                      - inbound
                      - offline
                      - outbound
                      - postcall
                      - unavailable
                      example: offline
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid key
                    example: Invalid key
      summary: Agent status
  /api/v3/messages/sms/templates:
    get:
      operationId: listSMSTempaltes
      tags:
      - SMS
      description: Retrieve a list of canned messages allowed for sending SMS.
      security:
      - callcenterBearerToken: []
      parameters:
      - name: page
        in: query
        description: The page number to return.
        schema:
          type: integer
          example: 1
          default: 1
          minimum: 1
      - name: limit
        in: query
        description: The maximum number of canned messages to return.
        schema:
          type: integer
          example: 50
          default: 50
          maximum: 500
          minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    description: An array of SMS templates your contact center owns.
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          description: ID of the canned message.
                          type: integer
                          format: int32
                          example: 142
                        name:
                          description: Name of the canned message.
                          type: string
                          example: SMS template (6)
                        body:
                          description: Body of the canned message.
                          type: string
                          example: Hi {{contact_name}}! My name is {{agent_name}},
                            how can I help you?
                        assigned_teams:
                          description: List of teams assigned to the canned message.
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                description: ID of team.
                                type: integer
                                format: int32
                                example: 16
                              name:
                                description: Name of team.
                                type: string
                                example: Support Team 2
                  metadata:
                    description: Information about the request settings and response
                      content.
                    type: object
                    properties:
                      total:
                        description: The total number of canned messages allowed for
                          sending SMS.
                        type: integer
                        example: 10
                      page:
                        description: The current page number.
                        type: integer
                        default: 1
                        example: 1
                      page_size:
                        description: The number of canned messages returned per page
                          in the response.
                        type: integer
                        default: 50
                        example: 1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Bad request
                    example: Bad request
        '401':
          $ref: '#/components/responses/401'
      summary: SMS templates
  /api/v1/{api_key}/click2call:
    post:
      operationId: startClickToCall
      tags:
      - Click2Call
      description: Initiate calls for agents from external systems.
      parameters:
      - $ref: '#/components/parameters/CallcenterApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_id:
                  description: An identifier assigned to the contact in an external
                    application such as a CRM.
                  type: string
                  example: '123321'
                agent:
                  description: The agent's contact center phone extension or sign-in
                    email address.
                  type: string
                  example: '5151'
                caller_id:
                  description: The name of the Caller ID group to which the user is
                    assigned.
                  type: string
                  format: phone
                  example: '18885658889'
                crm:
                  description: The name of an external application, such as a CRM,
                    where contact information is managed.
                  type: string
                  example: zoho_crm
                get_call_id:
                  description: Specify whether to retrieve the UUID for the call.
                  type: boolean
                  default: false
                  example: true
                number:
                  description: The phone number to be dialed.
                  type: string
                  format: phone
                  example: '18885658889'
              required:
              - agent
              - number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Success request status.
                    type: string
                    enum:
                    - ok
                  call_id:
                    description: ID assigned to the initiated call.
                    type: string
                    format: uuid
                    example: 0b97ce11-b6e0-49b4-8f92-68040aa324bf
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Bad request status.
                    type: string
                    enum:
                    - bad_request
                    example: bad_request
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid agent extension
                    - Invalid destination number
                    - Rate limit exceeded
                    - Invalid agent's extension or agent login ID
                    - Agent logged off
                    - Agent in a call
                    - Agent click-to-call disabled
                    example: Invalid destination number
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid key
                    example: Invalid key
      summary: Start call
  /api/v1/{api_key}/click2call_hangup:
    post:
      operationId: stopClickToCall
      tags:
      - Click2Call
      description: End calls for agents from external systems.
      parameters:
      - $ref: '#/components/parameters/CallcenterApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent:
                  description: The agent's contact center phone extension.
                  type: string
                  example: '5151'
              required:
              - agent
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Bad request status.
                    type: string
                    enum:
                    - bad_request
                    example: bad_request
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid agent extension
                    - Rate limit exceeded
                    - No active calls
                    example: No active calls
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid key
                    example: Invalid key
      summary: Stop call
  /api/v1/{api_key}/sendsms:
    post:
      operationId: createSms
      tags:
      - SMS
      description: Send SMS through Voiso
      parameters:
      - $ref: '#/components/parameters/CallcenterApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              oneOf:
              - properties:
                  account_id:
                    description: An identifier assigned to the contact in an external
                      application such as a CRM.
                    type: string
                    example: '123321'
                  agent:
                    description: The agent's contact center phone extension.
                    type: string
                    example: '5151'
                  body:
                    description: The SMS message.
                    type: string
                    example: Hello.
                  crm:
                    description: The name of an external application, such as a CRM,
                      where contact information is managed.
                    type: string
                    example: zoho_crm
                  number:
                    description: The SMS recipient's phone number.
                    type: string
                    format: phone
                    example: '18885658889'
                  sender_id:
                    description: The originating phone number displayed to the recipient.
                    type: string
                    format: phone
                    example: '18885658880'
                required:
                - agent
                - body
                - number
              - properties:
                  account_id:
                    description: An identifier assigned to the contact in an external
                      application such as a CRM.
                    type: string
                    example: '123321'
                  agent:
                    description: The agent's contact center phone extension.
                    type: string
                    example: '5151'
                  crm:
                    description: The name of an external application, such as a CRM,
                      where contact information is managed.
                    type: string
                    example: zoho_crm
                  number:
                    description: The SMS recipient's phone number.
                    type: string
                    format: phone
                    example: '18885658889'
                  sender_id:
                    description: The originating phone number displayed to the recipient.
                    type: string
                    format: phone
                    example: '18885658880'
                  template:
                    description: Canned message data to be sent via SMS.
                    type: object
                    properties:
                      id:
                        description: The identifier of the canned message.
                        type: integer
                        example: 174
                      params:
                        description: Key-value object with canned message placeholders.
                        type: object
                        additionalProperties:
                          type: string
                        example:
                          contact_name: Tony
                          agent_name: John
                    required:
                    - id
                required:
                - agent
                - number
                - template
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  sms_id:
                    description: The UUID of the interaction stored in the Call Details
                      Record.
                    type: string
                    format: uuid
                    example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  segments:
                    description: The number of segments the message body was divided
                      into.
                    type: integer
                    example: 1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message
                    type: string
                    enum:
                    - SMS is not allowed
                    - SMS disabled for agent
                    - account_id must be used with crm
                    - SenderID is not available
                    - The request must include a valid `template_id` when using a
                      template-based message
                    - The provided `template_params` do not match the required placeholders
                      in the template.
                    - SMS body length must be 1-1600 chars
                    - Rate limit exceeded
                    - Invalid agent extension
                    - Invalid destination number
                    - No SenderID available
                    - Links are not allowed in message body
                    - Not sent. General error
                    - Route unavailable
                    example: SMS body length must be 1-1600 chars
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid key
                    example: Invalid key
      summary: Send SMS
  /api/v1/{api_key}/balance:
    get:
      operationId: showCallcenterBalance
      tags:
      - Balance
      description: Obtain the balance owed to Voiso for contact center services.
      parameters:
      - name: api_key
        in: path
        description: Callcenter API key.
        required: true
        schema:
          type: string
          example: 9fdcd365a51432916f3a7569289d1f4363031e31ce12c589
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    description: Contact center balance.
                    type: number
                    format: float
                    example: 1234.56
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Error message.
                    type: string
                    enum:
                    - Invalid key
                    example: Invalid key
      summary: Get balance
components:
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: Error message.
                type: string
                enum:
                - The API key specified is invalid
                example: The API key specified is invalid
    '422':
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                description: A set of error messages.
                type: object
                additionalProperties:
                  description: An array of error messages.
                  type: array
                  items:
                    type: string
                example:
                  parameter1:
                  - can't be blank
                  parameter2:
                  - is too long
  securitySchemes:
    callcenterApiKey:
      description: Contact center API key provided as a query parameter.
      type: apiKey
      name: key
      in: query
    callcenterBearerToken:
      description: Contact center API key provided as a Bearer token.
      type: http
      scheme: bearer
    userApiKey:
      description: User API key provided as a query parameter.
      type: apiKey
      name: key
      in: query
    userBearerToken:
      description: User API key provided as a Bearer token.
      type: http
      scheme: bearer
  parameters:
    CallcenterApiKey:
      name: api_key
      in: path
      description: Callcenter API key.
      required: true
      schema:
        type: string
        example: 9fdcd365a51432916f3a7569289d1f4363031e31ce12c589
