8x8 Phone calls API

openapi: 3.2.0
info:
  version: '1'
  title: 8x8 Contact Center Call API Reference Phone calls API
  description: 'The 8x8 Contact Center Call API facilitates contact center management of agent calls. Using the Call API you can designate a specific agent to either respond to or join a call. The Call API manages and assigns phone contacts along with transaction codes and interaction IDs.


    The Call API enables you to:

    * Create an agent assigned outbound phone interaction for calling a desired number

    * Amend the transaction codes for an interaction

    * End a phone call based on the **`interactionId`**


    * Hang up the call for an agent (If the call is a conference or call was transferred it will not hang up for the other participants.)

    * Free up a telephone line for the specified agent or agents in preparation for the next call'
  contact:
    name: VCC Engineering Team
    email: vcc-dev@8x8.com
servers:
- description: NA30
  url: https://vcc-na30.8x8.com/api/v1/
- description: NA6
  url: https://vcc-na6.8x8.com/api/v1/
- description: NA38
  url: https://vcc-na38.8x8.com/api/v1/
- description: EU7
  url: https://vcc-eu7.8x8.com/api/v1/
- description: NA39
  url: https://vcc-na39.8x8.com/api/v1/
- description: NA4
  url: https://vcc-na4.8x8.com/api/v1/
- description: EU10
  url: https://vcc-eu10.8x8.com/api/v1/
- description: NA17
  url: https://vcc-na17.8x8.com/api/v1/
- description: NA29
  url: https://vcc-na29.8x8.com/api/v1/
- description: NA14
  url: https://vcc-na14.8x8.com/api/v1/
- description: NA2
  url: https://vcc-na2.8x8.com/api/v1/
- description: EU3
  url: https://vcc-eu3.8x8.com/api/v1/
- description: NA3
  url: https://vcc-na3.8x8.com/api/v1/
- description: EU6
  url: https://vcc-eu6.8x8.com/api/v1/
- description: NA8
  url: https://vcc-na8.8x8.com/api/v1/
- description: NA13
  url: https://vcc-na13.8x8.com/api/v1/
- description: NA28
  url: https://vcc-na28.8x8.com/api/v1/
- description: NA1
  url: https://vcc-na1.8x8.com/api/v1/
- description: NA12
  url: https://vcc-na12.8x8.com/api/v1/
- description: NA9
  url: https://vcc-na9.8x8.com/api/v1/
- description: NA37
  url: https://vcc-na37.8x8.com/api/v1/
- description: EU4
  url: https://vcc-eu4.8x8.com/api/v1/
- description: NA16
  url: https://vcc-na16.8x8.com/api/v1/
- description: NA20
  url: https://vcc-na20.8x8.com/api/v1/
- description: EU2
  url: https://vcc-eu2.8x8.com/api/v1/
- description: AP1
  url: https://vcc-ap1.8x8.com/api/v1/
- description: CA2
  url: https://vcc-ca2.8x8.com/api/v1/
- description: NA19
  url: https://vcc-na19.8x8.com/api/v1/
- description: NA27
  url: https://vcc-na27.8x8.com/api/v1/
- description: EU11
  url: https://vcc-eu11.8x8.com/api/v1/
- description: AU1
  url: https://vcc-au1.8x8.com/api/v1/
- description: NA7
  url: https://vcc-na7.8x8.com/api/v1/
- description: NA11
  url: https://vcc-na11.8x8.com/api/v1/
- description: NA40
  url: https://vcc-na40.8x8.com/api/v1/
- description: NA10
  url: https://vcc-na10.8x8.com/api/v1/
- description: EU5
  url: https://vcc-eu5.8x8.com/api/v1/
- description: NA15
  url: https://vcc-na15.8x8.com/api/v1/
- description: NA18
  url: https://vcc-na18.8x8.com/api/v1/
- description: NA5
  url: https://vcc-na5.8x8.com/api/v1/
- description: EU12
  url: https://vcc-eu12.8x8.com/api/v1/
- description: CA1
  url: https://vcc-ca1.8x8.com/api/v1/
- description: EU9
  url: https://vcc-eu9.8x8.com/api/v1/
tags:
- name: Phone calls
  description: Manages and assigns phone contacts along with transaction codes and interaction IDs
paths:
  /tenants/{tenantId}/calls:
    post:
      tags:
      - Phone calls
      operationId: placePhoneCall
      summary: Creates an agent assigned outbound phone interaction for calling the desired number.
      description: Creates an agent assigned outbound phone interaction for calling the desired number.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneInteraction'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/CallResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/CallFaultResponse'
  /tenants/{tenantId}/calls/{interactionId}/agent/{agentId}/transaction-codes:
    put:
      tags:
      - Phone calls
      operationId: addTransactionCodes
      summary: Ammends the transaction codes for both an interaction and the associated agent.
      description: Ammends the transaction codes for both an interaction and the associated agent.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/InteractionId'
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionCodes'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/TransactionCodesResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/TransactionCodesFaultResponse'
  /tenants/{tenantId}/calls/{interactionId}:
    delete:
      tags:
      - Phone calls
      operationId: deletePhoneInteraction
      summary: Ends a phone call based on the interactionId.
      description: Ends a phone call based on the interactionId.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/InteractionId'
      - $ref: '#/components/parameters/EndPostProcessing'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/DeleteCallResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '410':
          description: Interaction is already terminated.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/DeleteCallFaultResponse'
  /tenants/{tenantId}/calls/{interactionId}/agent/{agentId}:
    delete:
      tags:
      - Phone calls
      operationId: hangupAgentHandlingInteraction
      summary: Hangs up the call for an agent. If the call is a conference or call was transferred it will not hang up for the other participants.
      description: Hangs up the call for an agent. If the call is a conference or call was transferred it will not hang up for the other participants.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/InteractionId'
      - $ref: '#/components/parameters/AgentId'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/DeleteCallResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '410':
          description: Interaction is already terminated.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/DeleteCallFaultResponse'
  /tenants/{tenantId}/agents/{agentId}/calls:
    delete:
      tags:
      - Phone calls
      operationId: hangupAgentLines
      summary: Frees up the agent lines in preparation to take the next call.
      description: Frees up the agent lines in preparation to take the next call.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/AgentId'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/DeleteCallResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '410':
          description: Interaction is already terminated.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/DeleteCallFaultResponse'
  /tenants/{tenantId}/agents/{agentId}/calls/line/{lineNo}:
    delete:
      tags:
      - Phone calls
      operationId: hangupAgentLine
      summary: Frees up a telephone line for the specified agent in preparation for the next call.
      description: Frees up a telephone line for the specified agent in preparation for the next call.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/LineNo'
      security:
      - BasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/DeleteCallResponse'
        '400':
          description: There was an error accepting the request.
        '401':
          description: Authentication or authorization failed for this request.
        '403':
          description: You are not authorized to access this tenant.
        '410':
          description: Interaction is already terminated.
        '500':
          description: There was a server error.
        default:
          $ref: '#/components/responses/DeleteCallFaultResponse'
components:
  schemas:
    PhoneInteraction:
      type: object
      description: The telephone interaction payload.
      required:
      - agentId
      - prefix
      - number
      - callerId
      properties:
        agentId:
          description: The agent identified for taking the call.
          type: string
          example: cmalutan
        prefix:
          description: The calling phone number prefix.
          type: number
          example: 1
        number:
          description: The calling phone number.
          type: number
          example: 9162471753
        callerId:
          description: The caller ID for making the outbound call.
          type: number
          example: 9162471753
        dialplanId:
          description: The dial plan ID that is applied to the phone number.
          type: number
          example: 1
        queueId:
          description: The outbound queue ID used to make a call. The agent is listed as busy when the call is established in the queue. The corresponding TCL is applied along with the queue.
          type: number
          example: 101
        extTransactionData:
          description: The exTransactionData allows a tenant to pass in an associated record ID, record, and record type that the click-to-dial call is triggered from. The extRecordId and extRecordType are usually supplied to link the call log generated by the ctlAction automatically. Please refer to section 'Create Action' for an example. However, the association can only applied for tenant using Enhanced SFDC integration.
          type: array
          items:
            $ref: '#/components/schemas/UserParam'
        ctlUserData:
          description: The ctlUserData allows a tenant to pass in any user data or system data to the trigger supported click-to-dial related action. The design of ctlUserData allows any combination of name/value data.
          type: array
          items:
            $ref: '#/components/schemas/UserParam'
        forceCall:
          description: If an agent has one line available but is busy on the other line, or has both lines available but busy on chat, this flag can be set to true so the agent is offered the call regardless. If the agent is busy on both lines, on break, or logged out, this flag will not help as the call is rejected.
          type: boolean
          example: false
    TransactionCodesList:
      type: object
      description: Transaction code list.
      properties:
        id:
          type: number
        codes:
          type: array
          description: List of codes selected.
          items:
            oneOf:
            - $ref: '#/components/schemas/TransactionCodesItem'
    CallResponse:
      type: object
      description: Call API response
      properties:
        id:
          type: string
          description: The interaction GUID of the call that was placed, used for later amendment, or terminated.
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Call successfully initiated
            - type: string
              example: Agent is handling other interactions
              description: In addition to a successful reason, if the call was placed but the agent was busy and force parameter was sent
        message:
          type: string
    TransactionCodesResponse:
      type: object
      description: Call API set transaction codes response
      properties:
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Transaction codes successfully set
        message:
          type: string
    UserParam:
      type: object
      properties:
        name:
          description: The property name.
          type: string
          example: customerAvailableAt
        value:
          description: The property value.
          type: string
          example: 1584957922065
    TransactionCodesFaultResponse:
      type: object
      description: Call API set transaction codes response
      properties:
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Invalid transaction codes, lists=[listId, listId] are not supporting multiple choice
              description: Not supporting multiple choice
            - type: string
              example: Invalid transaction code, listId=[listId] itemId=[itemId]
              description: Invalid transaction codes
        message:
          type: string
    CallFaultResponse:
      type: object
      description: Call API faulty response
      properties:
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Agent=[agentId] not available to handle interaction, already on busy phone interaction
            - type: string
              example: Agent=[agentId] not available to handle interaction
              description: Agent with both lines busy, on break, or logged out
        message:
          type: string
    TransactionCodesItem:
      type: object
      description: Transaction code item.
      properties:
        id:
          type: number
    DeleteCallResponse:
      type: object
      description: Call API delete response
      properties:
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Hangup all calls for agent [agentId] was successful.
            - type: string
              example: Hangup for agent [agent-phone-leg] leg on line [line-number] assigned to interaction [interactionId] was successful.
        message:
          type: string
    DeleteCallFaultResponse:
      type: object
      description: Call API delete faulty response
      properties:
        reasons:
          type: array
          items:
            anyOf:
            - type: string
              example: Interaction [interactionId] for agent [agentId] was not found
              description: Interaction Id was not found for agent
            - type: string
              example: Interaction [interactionId] was not found.
              description: Using an invalid interaction ID, one that does not exists
            - type: string
              example: Agent [agentId] has no phone interactions in progress.
              description: No interaction in progress for agent
            - type: string
              example: Failed to find any interaction on line [line-number] for agent [agentId].
              description: No phone interaction on specific line
            - type: string
              example: Interaction is already terminated interactionId
              description: When trying to terminate an interaction that has already closed
        message:
          type: string
    TransactionCodes:
      type: object
      description: Transaction codes to be set for this interaction.
      properties:
        selections:
          type: array
          description: List of transaction codes lists and their selections.
          items:
            oneOf:
            - $ref: '#/components/schemas/TransactionCodesList'
      example:
        selections:
        - id: 1
          codes:
          - id: 1
        - id: 2
          codes:
          - id: 3
          - id: 4
  parameters:
    TenantId:
      name: tenantId
      in: path
      description: The tenant's unique name or identification.
      required: true
      schema:
        type: string
        format: string
      example: wavecell
    EndPostProcessing:
      name: endPostProcessing
      in: query
      description: If present, the deleted interaction completes the assigned post processing.
      required: false
      schema:
        type: boolean
      example: true
    InteractionId:
      name: interactionId
      in: path
      description: The interaction identification.
      required: true
      schema:
        type: string
        format: string
      example: int-16efa80e7b2-889c0dfeb04f4b97948bc10c373cd71d-chat-01-wavecell
    AgentId:
      name: agentId
      in: path
      description: The agent identification.
      required: true
      schema:
        type: string
        format: string
      example: agb7CaTIXvQPWmPKmTu1rJjw
    LineNo:
      name: lineNo
      in: path
      description: The line number on which the call terminates.
      required: true
      schema:
        type: number
        format: number
      example: 1
  responses:
    DeleteCallResponse:
      description: Delete call response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeleteCallResponse'
    CallResponse:
      description: Make call API response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallResponse'
    DeleteCallFaultResponse:
      description: Delete call faulty response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeleteCallFaultResponse'
    TransactionCodesFaultResponse:
      description: Update transaction codes faulty response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionCodesFaultResponse'
    TransactionCodesResponse:
      description: Update transaction codes response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionCodesResponse'
    CallFaultResponse:
      description: Make call API faulty response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallFaultResponse'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: The username is the tenantId and the password is the VCC action-token. These values are used for the Agent Status API.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true