Cisco Webex Call Controls API

openapi: 3.1.0
info:
  title: Cisco Webex Admin Audit Events Call Controls API
  description: Access admin audit events for tracking administrative actions performed in Webex Control Hub. Available to full administrators for compliance monitoring and security auditing purposes.
  version: 1.0.0
  contact:
    name: Cisco Webex Developer Support
    url: https://developer.webex.com/support
  license:
    name: Cisco Webex API Terms of Service
    url: https://developer.webex.com/terms-of-service
servers:
- url: https://webexapis.com/v1
  description: Webex Production API
security:
- bearerAuth: []
tags:
- name: Call Controls
  description: Operations for controlling active calls
paths:
  /telephony/calls/dial:
    post:
      operationId: dial
      summary: Cisco Webex Dial
      description: Initiates an outbound call from the authenticated user's device. The destination can be a phone number, SIP URI, or Webex person ID.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination
              properties:
                destination:
                  type: string
                  description: Destination to dial (phone number, SIP URI, or person ID).
      responses:
        '200':
          description: Call initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallSession'
        '400':
          description: Bad request - invalid destination.
        '401':
          description: Unauthorized - invalid or missing access token.
  /telephony/calls/answer:
    post:
      operationId: answer
      summary: Cisco Webex Answer
      description: Answers an incoming call on the authenticated user's device. The call ID must be provided to identify which call to answer.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to answer.
      responses:
        '204':
          description: Call answered successfully.
        '400':
          description: Bad request - invalid call ID.
  /telephony/calls/reject:
    post:
      operationId: reject
      summary: Cisco Webex Reject
      description: Rejects an incoming call. The caller will hear a busy tone or be redirected to voicemail depending on configuration.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to reject.
      responses:
        '204':
          description: Call rejected successfully.
        '400':
          description: Bad request - invalid call ID.
  /telephony/calls/hangup:
    post:
      operationId: hangup
      summary: Cisco Webex Hangup
      description: Ends an active call. Both parties are disconnected when the call is terminated.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to hang up.
      responses:
        '204':
          description: Call ended successfully.
        '400':
          description: Bad request - invalid call ID.
  /telephony/calls/hold:
    post:
      operationId: hold
      summary: Cisco Webex Hold
      description: Places an active call on hold. The other party hears hold music while the call is held.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to hold.
      responses:
        '204':
          description: Call placed on hold successfully.
        '400':
          description: Bad request - invalid call ID.
  /telephony/calls/resume:
    post:
      operationId: resume
      summary: Cisco Webex Resume
      description: Resumes a held call. The call returns to an active state with both parties connected.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to resume.
      responses:
        '204':
          description: Call resumed successfully.
        '400':
          description: Bad request - invalid call ID.
  /telephony/calls/transfer:
    post:
      operationId: transfer
      summary: Cisco Webex Transfer
      description: Transfers an active call to another destination. Supports blind transfer and consultative transfer when two calls are active.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId1
              properties:
                callId1:
                  type: string
                  description: The first call ID.
                callId2:
                  type: string
                  description: The second call ID for consultative transfer.
                destination:
                  type: string
                  description: Destination for blind transfer.
      responses:
        '204':
          description: Call transferred successfully.
        '400':
          description: Bad request - invalid parameters.
  /telephony/calls/park:
    post:
      operationId: park
      summary: Cisco Webex Park
      description: Parks an active call at a call park extension. The call can be retrieved from any device by dialing the park extension.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callId
              properties:
                callId:
                  type: string
                  description: The call ID to park.
                destination:
                  type: string
                  description: Park extension destination.
                isGroupPark:
                  type: boolean
                  description: Whether to use group call park.
      responses:
        '200':
          description: Call parked successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  callId:
                    type: string
                  parkedAgainst:
                    type: string
        '400':
          description: Bad request - invalid parameters.
  /telephony/calls/retrieve:
    post:
      operationId: retrieve
      summary: Cisco Webex Retrieve
      description: Retrieves a parked call by providing the park destination. The call is connected to the authenticated user's device.
      tags:
      - Call Controls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination
              properties:
                destination:
                  type: string
                  description: Park extension to retrieve the call from.
      responses:
        '200':
          description: Call retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallSession'
        '400':
          description: Bad request - invalid parameters.
  /telephony/calls:
    get:
      operationId: listCalls
      summary: Cisco Webex List Calls
      description: Lists all active calls for the authenticated user. Returns call details including state, direction, and connected parties.
      tags:
      - Call Controls
      responses:
        '200':
          description: Successful response with list of active calls.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallSession'
        '401':
          description: Unauthorized - invalid or missing access token.
  /telephony/calls/{callId}:
    get:
      operationId: getCallDetails
      summary: Cisco Webex Get Call Details
      description: Shows details for an active call by call ID. Returns the current call state, parties, and duration.
      tags:
      - Call Controls
      parameters:
      - name: callId
        in: path
        required: true
        description: Unique identifier for the call.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with call details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallSession'
        '404':
          description: Call not found.
components:
  schemas:
    CallSession:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the call.
        callId:
          type: string
          description: The call ID.
        state:
          type: string
          description: Current state of the call.
          enum:
          - connecting
          - alerting
          - connected
          - held
          - remoteHeld
          - disconnected
        callType:
          type: string
          description: Type of call.
          enum:
          - location
          - organization
          - external
          - emergency
          - repair
          - other
        personality:
          type: string
          description: The role of the authenticated user in the call.
          enum:
          - originator
          - terminator
          - clickToDialOriginator
        appearance:
          type: integer
          description: The call appearance value.
        remoteParty:
          type: object
          description: Information about the remote party.
          properties:
            name:
              type: string
            number:
              type: string
            personId:
              type: string
            sipAddress:
              type: string
            callType:
              type: string
        startTime:
          type: string
          format: date-time
          description: Time the call started.
        answerTime:
          type: string
          format: date-time
          description: Time the call was answered.
        duration:
          type: integer
          description: Call duration in seconds.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Webex API access token. Obtain via OAuth 2.0 authorization flow. Requires audit:events_read scope.