NiCE Phone Calls API

openapi: 3.2.0
info:
  title: Nice Phone Calls API
  version: v1
  description: 'Operations tagged PhoneCalls across 2 of this provider''s published API definitions: nice-phonecalls.json, nice-phonecalls-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: PhoneCalls
  description: ': Phone Call Management'
paths:
  /agent-sessions/{sessionId}/dial-agent:
    post:
      tags:
      - PhoneCalls
      summary: Dials an agent's personal queue
      description: 'Used to initiate a transfer of a call to another agent.


        The sending agent must have a single holding call in order to dial another agent, or the API will respond with a 409 status code. (409 means that the state of things will not allow the API call to be made.)


        If the business unit has "multi-party conferencing" enabled, and the sending agent''s security profile allows multi-party conferencing, this API call will succeed if there are multiple active calls that are conferenced. If multi-party conferencing is disabled for the business unit, or for the sending agent''s security profile, attempting to dial another agent while two calls are conferenced will generate a 403 status code (insufficient privileges).


        The target agent user name is required (e.g. "user@example.com"). In future releases this will be changed to use agentId.


        If the target agent is "Unavailable", or is handling an inbound or outbound phone call, or is logged into an outbound dialer campaign, the dial-agent request is queued to the target agent''s "personal queue", and will be delivered to the target agent when the target agent becomes available. If the target agent is already available when the dial-agent request is made, the call will immediately be routed to the target agent.


        Attempting to dial an agent that is not logged in will result in a 409 (invalid state) HTTP status result.


        You can retrieve a list of agent states to provide logic that guides the agent to know whether or not a target agent is logged in, and whether or not a dial request will be delivered immediately or queued to the target agent''s personal queue (see documentation on the Admin API). It is a good practice to regularly request the states of other agents so you can make them available to your application, and for display to the sending agent.'
      operationId: agentTransfer
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - name: dialAgent
        in: body
        required: true
        description: Dial agent
        schema:
          type: object
          properties:
            targetAgentId:
              type: string
              description: Agent to dial.
            parentContactId:
              type: string
              description: ParentContactId that the new ContactId will be elevated from
      responses:
        '202':
          description: <p>Accepted</p>
        '400':
          description: <p><p>Invalid TargetAgentId </p> <p>Invalid ParentContactId .</p></p>
        '403':
          description: <p>Multi-Conference not enabled for user.</p><p>Invalid Security User.</p>
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: access_denied
                  error_description:
                    type: string
                    description: Forbidden
        '404':
          description: <p><p>InvalidAgentSession </p> InvalidParentContactId </p></p>
        '409':
          description: <p><p>Invalid state. </p> <p>Invalid Target State.</p> <p>Multi-Conference max limit reached.</p></p>
      requestBody:
        required: true
        description: Dial agent
        content:
          application/json:
            schema:
              type: object
              properties:
                targetAgentId:
                  type: string
                  description: Agent to dial.
                parentContactId:
                  type: string
                  description: ParentContactId that the new ContactId will be elevated from
  /agent-sessions/{sessionId}/dial-phone:
    post:
      tags:
      - PhoneCalls
      summary: Dials an outbound call
      description: This method is used to place an outbound phone call. You must include an "outbound skill id" to place a phone call.
      operationId: dialPhone
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - name: Dial Phone
        in: body
        required: true
        description: Dial phone
        schema:
          type: object
          properties:
            phoneNumber:
              type: string
              description: Phone Number to be dialed.
            skillId:
              type: integer
              format: int32
              description: Id of an outbound skill to dial.
            parentContactId:
              type: integer
              description: ParentContactId that the new ContactId will be elevated from
            customerId:
              type: string
              description: Customer identifier for the outbound call.
            zipCode:
              type: string
              description: Zip code or postal code associated with the customer.
      responses:
        '202':
          description: Accepted
        '400':
          description: <p><p> Phone Number is not valid.</p> <p> Invalid skillId </p></p>
        '401':
          description: Unauthorized
        '403':
          description: <p>Multi-Conference not enabled for user.</p><p>Invalid Security User.</p>
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: access_denied
                  error_description:
                    type: string
                    description: Forbidden
        '404':
          description: Invalid sessionId
        '409':
          description: <p><p>Invalid state </p><p> Multi-Conference max limit reached.</p></p>
      requestBody:
        required: true
        description: Dial phone
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                  description: Phone Number to be dialed.
                skillId:
                  type: integer
                  format: int32
                  description: Id of an outbound skill to dial.
                parentContactId:
                  type: integer
                  description: ParentContactId that the new ContactId will be elevated from
                customerId:
                  type: string
                  description: Customer identifier for the outbound call.
                zipCode:
                  type: string
                  description: Zip code or postal code associated with the customer.
  /agent-sessions/{sessionId}/dial-skill:
    post:
      tags:
      - PhoneCalls
      summary: Dials a skill
      description: Used to create an outbound phone call and place it into the named skill’s queue. The skillName parameter is required.
      operationId: dialSkill
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - name: dialSkill
        in: body
        required: true
        description: Dial skill
        schema:
          type: object
          properties:
            skillId:
              type: integer
              format: int32
              description: Id of an outbound skill to dial.
            parentContactId:
              type: integer
              description: ParentContactId that the new ContactId will be elevated from
      responses:
        '202':
          description: Accepted
        '400':
          description: <p>Invalid skillId <p/>
        '403':
          description: <p>Multi-Conference not enabled for user.</p><p>Invalid Security User.</p>
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: access_denied
                  error_description:
                    type: string
                    description: Forbidden
        '404':
          description: <p>Invalid sessionId </br> Invalid parentContactId </p>
        '409':
          description: <p>Invalid state.</p><p>Multi-Conference max limit reached.</p>
      requestBody:
        required: true
        description: Dial skill
        content:
          application/json:
            schema:
              type: object
              properties:
                skillId:
                  type: integer
                  format: int32
                  description: Id of an outbound skill to dial.
                parentContactId:
                  type: integer
                  description: ParentContactId that the new ContactId will be elevated from
  /agent-sessions/{sessionId}/send-dtmf:
    post:
      tags:
      - PhoneCalls
      summary: Send DTMF tones
      description: This method is used to send specific DTMF tones to non-agent parties in the active session.
      operationId: SendDtmfTone
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - name: dtmfSequence
        in: query
        required: true
        description: Set of numbers to be sent
        schema:
          type: string
      - name: toneDurationMS
        in: query
        required: true
        description: How long each tone lasts. Valid range is 61 - 15000
        schema:
          type: integer
          format: int32
      - name: toneSpacingMS
        in: query
        description: Time between dtmf tones. Valid range is 61 - 15000
        schema:
          type: integer
          format: int32
        required: false
      responses:
        '202':
          description: Accepted.
        '400':
          description: Bad Parameter.
        '401':
          description: Unauthorized.
        '404':
          description: Not Found.
  /agent-sessions/{sessionId}/consult-agent:
    post:
      tags:
      - PhoneCalls
      summary: Dial agent consult
      description: 'Used to call another agent as a "consultation". Dialing an agent as a consultation differs from dialing the target agent’s "personal queue" in that consultations are tracked and reported.


        The agent user name is required (e.g. "user@example.com").


        Note that you may not request a consult with an agent that is logged out, or that is handling an inbound or outbound call, or that is logged into an outbound dialer campaign. It is a good practice to prevent the user from attempting to consult an agent that is in any of these states. Attempting to consult another agent who is handling a call or logged into an outbound dialer campaign results in a 409 error response from the API.


        You retrieve a list of agent states to provide logic that guides the agent to know whether or not a consultation with another agent is possible (see documentation on the Admin API). It is a good practice to regularly request the states of other agents so you can make them available to your application, and for display to the agent.


        Request current agent states this way:


        GET /agents/state


        See the Admin API documentation for details.'
      operationId: dialAgentConsult
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - name: consultAgent
        in: body
        required: true
        description: Consult agent
        schema:
          type: object
          properties:
            targetAgentId:
              type: string
              description: Agent to dial.
            parentContactId:
              type: string
              description: ParentContactId that the new ContactId will be elevated from
      responses:
        '202':
          description: Accepted
        '400':
          description: Invalid targetAgentId
        '403':
          description: Multi-Conference not enabled for user.<p>Invalid Security User.</p>
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: access_denied
                  error_description:
                    type: string
                    description: Forbidden
        '404':
          description: <p>Invalid sessionId </p>
        '409':
          description: <p><p>Invalid State </p> <p>Invalid Target State.</p> <p> Multi-Conference max limit reached.</p></p>
      requestBody:
        required: true
        description: Consult agent
        content:
          application/json:
            schema:
              type: object
              properties:
                targetAgentId:
                  type: string
                  description: Agent to dial.
                parentContactId:
                  type: string
                  description: ParentContactId that the new ContactId will be elevated from
  /agent-sessions/{sessionId}/interactions/transfer-calls:
    post:
      tags:
      - PhoneCalls
      summary: Transfer call
      description: 'In order to transfer a call, you must have two calls active or holding.


        When the transfer API method is called, the contact states are set to "Disconnected" for the agent, and the agent is moved into their "next state" by the platform. The two calls will be connected, and the agent will be disconnected from both calls.'
      operationId: transferCall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: Invalid agent session id.
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/conference-calls:
    post:
      tags:
      - PhoneCalls
      summary: Conference calls together
      description: 'In order to conference two calls, you simply make the Conference Call API Request. You must have two calls in the Active or Holding state in order to conference them.


        By simply making the Conference Call API request, both calls will be conferenced. You do not need to identify either of the calls using their contact ID.


        When two calls are conferenced, the agent remains a party to the conference, and the contact is NOT disconnected.'
      operationId: conferenceCall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: Invalid agent session Id.
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/accept-consult:
    post:
      tags:
      - PhoneCalls
      summary: Accept consult request
      description: 'When one agent attempts to "consult" with another (by dialling an agent consult), the target agent receives an event indicating that a consult request is pending.


        The target agent must either let the consult request time out (effectively "rejecting" the request), or indicate that the consult request is accepted by calling this API call.


        Note that there is not an API call to explicitly and immediately "reject" a consult request.


        The Agent API currently does not provide a way to actively reject a consult request. The target agent simply must ignore the consult request until it times out. The requesting agent will be notified that the consult request was rejected.'
      operationId: acceptConsultRequest
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid Agent Session Id.</p><p>Invalid Contact ID.</p>
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/hold:
    post:
      tags:
      - PhoneCalls
      summary: Places a contact on hold
      description: 'Use this API to place an active call on hold. You must have the "contact ID" of the active call.


        The "contact ID" is delivered when the call is first active, in a "CallContactEvent". You will want to keep track of this ID so you can use it in API requests like "hold call".


        When the call is successfully put on hold by the platform, a "CallContactEvent" will be delivered, indicating that the call’s status is "Holding". Keep the contact ID for use in the "Resume Call" API request.'
      operationId: holdCall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id.</p><p>Invalid contact ID.</p>
        '409':
          description: Cannot put the contact on hold at this time.
  /agent-sessions/{sessionId}/interactions/{contactId}/resume:
    post:
      tags:
      - PhoneCalls
      summary: Resume call
      description: 'Use this API request to "resume" a holding call. You must use the contact ID of a holding call. When a call is placed on hold, a "CallContactEvent" is generated. This event will contain the "contact ID" of the call.


        Use this contact ID in the Resume Call API request. When the platform "resumes" the call (i.e. takes it off hold), another CallContactEvent will be generated indicating that the contact’s state is now "Active".'
      operationId: resumeCall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id.</p><p>Invalid contact ID.</p>
        '409':
          description: Cannot resume the contact at this time.
  /agent-sessions/{sessionId}/interactions/{contactId}/end:
    post:
      tags:
      - PhoneCalls
      summary: End call
      description: 'Use this API request to end a phone call. When a phone call becomes "active", a "CallContactEvent" is generated that indicates the call’s status is "Active". This event contains the call’s "contact ID".


        Use this contact ID in the End Call API request to end the call.


        Note that you cannot end a call that is "Holding". It must be "Active". Attempting to end a "holding" call will result in an error response from the API.'
      operationId: endCall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session.</p><p>Invalid contact ID.</p>
        '409':
          description: Cannot end the contact at this time.
  /agent-sessions/{sessionId}/interactions/{contactId}/amd-override:
    post:
      tags:
      - PhoneCalls
      summary: Override AMD on a call
      description: This method allows you to pre-empt the platform AMD process and label the contact as either an answering machine or a fax machine and moves the contact to it's next state.
      operationId: AmdOverride
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      - name: type
        in: query
        required: true
        description: One of either faxMachine or answeringMachine
        schema:
          type: string
          enum:
          - faxMachine
          - answeringMachine
          default: answeringMachine
      responses:
        '202':
          description: Accepted
        '400':
          description: Invalid type.
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session.</p><p>Invalid Contact Id.</p>
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/record:
    post:
      tags:
      - PhoneCalls
      summary: Record a call
      description: 'Calls can be recorded on the inContact platform through three different methods:


        An administrator can begin recording a call from an administrative application, such as the inContact Central web site.


        An IVR script can execute the "LOGCALL" action at any time, which will begin recording the call.


        An agent can request that the call be recorded by clicking on the "record" icon in an agent application.


        The Agent API "record a call" method facilitates the ability for an agent to request that a call be recorded.


        When call recording is requested by an agent, an event will be generated and delivered by the platform to indicate that the call is being recorded. This event will be sent to all agent applications that are connected to the agent session.'
      operationId: recordACall
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id</p><p>Invalid Contact Id.</p>
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/mask:
    post:
      tags:
      - PhoneCalls
      summary: Masks a recording with white noise
      description: 'Whether a call is being recorded through an agent-initiated request, through an admin-initiated request, or through the LOGCALL action in an IVR script, the agent may need to "mask" the recording in order to protect patron privacy, or ensure compliance with regulations (such as PCI).


        This API method allows the agent to introduce white noise while the call is being recorded. The API call can be requested whether the call is actually being recorded or not. Agents may be trained to "mask" a call during the gathering of sensitive data or for other reasons, regardless of whether it appears to them that the call is actually being recorded. This is because any given call may be recorded (through an Admin-initiated request, or the use of the LOGCALL action in an IVR script) without the agent''s knowledge.


        You should pair a "mask" request with an "unmask" request.'
      operationId: maskACallRecording
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      - $ref: '#/components/parameters/maskRecordingMedia'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id.</p><p>Invalid Contact Id.</p>
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/unmask:
    post:
      tags:
      - PhoneCalls
      summary: Stop masking a call recording
      description: This API call will end the masking of a call recording. See "Mask a Call Recording" for details on masking.
      operationId: stopMaskingACallRecording
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      - $ref: '#/components/parameters/maskRecordingMedia'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id</p><p>Invalid Contact Id.</p>
        '409':
          description: Invalid state.
  /agent-sessions/{sessionId}/interactions/{contactId}/independent-dial:
    post:
      tags:
      - PhoneCalls
      summary: Dial an Independent call
      description: This method is used for outbound phone contacts that will be made on an independent telephony system. This call updates the contact state and allows subsequent calls to update the outcome status of the contact. The contact should have been routed to the Agent in a dialing state.
      operationId: IndependentDialed
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session Id.</p><p>Invalid contact ID.</p>
        '409':
          description: Contact not able to be dialed
  /agent-sessions/{sessionId}/interactions/{contactId}/independent-dial-outcome:
    post:
      tags:
      - PhoneCalls
      summary: Disposition an Independent call
      description: This method will update the outcome value of an independent call contact after the call is placed in a separate telephony system. This should only be called a single time on a contact to indicate the final outcome for the call.
      operationId: IndependentDialOutcome
      parameters:
      - $ref: '#/components/parameters/sessionId'
      - $ref: '#/components/parameters/contactId'
      - name: outcome
        in: query
        description: The Outcome description
        schema:
          type: string
          enum:
          - Answered
          - Busy
          - Fax
          - Intercept
          - No Answer
          default: Answered
        required: false
      responses:
        '202':
          description: Accepted
        '400':
          description: Invalid outcome.
        '401':
          description: Unauthorized
        '404':
          description: <p>Invalid agent session.</p><p>Invalid Contact ID.</p>
        '409':
          description: Invalid state.
components:
  parameters:
    maskRecordingMedia:
      name: maskRecordingMedia
      in: query
      description: Target to mask the recording as Voice, Screen, All.
      schema:
        type: string
      required: false
    contactId:
      name: contactId
      in: path
      required: true
      description: Contact Id
      schema:
        type: integer
        format: int64
    sessionId:
      name: sessionId
      in: path
      required: true
      description: Agent Session Id
      schema:
        type: string
x-refined-from:
- nice-phonecalls.json
- nice-phonecalls-openapi.yml