---
openapi: 3.0.0
info:
  version: 1.2.4
  title: Voice API
  description: The Voice API lets you create outbound calls, control in-progress calls
    and get information about historical calls. More information about the Voice API
    can be found at <https://developer.nexmo.com/voice/voice-api/overview>.
  contact:
    name: Nexmo DevRel
    email: devrel@nexmo.com
    url: 'https://developer.nexmo.com/'
servers:
- url: https://api.nexmo.com/v1/calls
paths:
  "/":
    post:
      security:
      - bearerAuth: []
      summary: Create an outbound call
      description: Create an outbound Call
      operationId: createCall
      requestBody:
        description: Call Details
        content:
          application/json:
            schema:
              required:
                - to
                - from
                - event_url
              properties:
                to:
                  type: array
                  items:
                    oneOf:
                    - "$ref": "#/components/schemas/EndpointPhone"
                    - "$ref": "#/components/schemas/EndpointSip"
                    - "$ref": "#/components/schemas/EndpointWebsocket"
                    - "$ref": "#/components/schemas/EndpointVBCExtension"
                from:
                  "$ref": "#/components/schemas/EndpointPhone"
                ncco:
                  description: |
                    **Required** unless `answer_url` is provided.

                    The [Nexmo Call Control Object](/voice/voice-api/ncco-reference) to use for this call.
                  type: array
                  x-nexmo-developer-collection-description-shown: true
                  example: |
                      [
                        {
                          "action":"talk",
                          "text": "Hello World"
                        }
                      ]
                  items:
                    type: object
                answer_url:
                  description: |
                    **Required** unless `ncco` is provided.

                    The webhook endpoint where you provide the [Nexmo Call Control Object](/voice/voice-api/ncco-reference) that governs this call.
                  type: array
                  x-nexmo-developer-collection-description-shown: true
                  example: '["https://example.com/answer"]'
                  items:
                    type: string
                answer_method:
                  description: The HTTP method used to send event information to answer_url.
                  type: string
                  default: GET
                  enum:
                  - POST
                  - GET
                event_url:
                  description: The webhook endpoint where call progress events are
                    sent to. For more information about the values sent, see [Event webhook](/voice/voice-api/webhook-reference#event-webhook).
                  type: array
                  x-nexmo-developer-collection-description-shown: true
                  example: '["https://example.com/event"]'
                  items:
                    type: string
                    format: uri
                event_method:
                  description: The HTTP method used to send event information to event_url.
                  type: string
                  default: POST
                  enum:
                  - POST
                  - GET
                machine_detection:
                  description: Configure the behavior when Nexmo detects that the
                    call is answered by voicemail. If Continue Nexmo sends an HTTP
                    request to event_url with the Call event machine. hangup  end
                    the call
                  type: string
                  enum:
                  - continue
                  - hangup
                  example: continue
                length_timer:
                  description: Set the number of seconds that elapse before Nexmo
                    hangs up after the call state changes to in_progress.
                  minimum: 1
                  maximum: 7200
                  default: 7200
                  type: integer
                ringing_timer:
                  description: Set the number of seconds that elapse before Nexmo
                    hangs up after the call state changes to ‘ringing’.
                  minimum: 1
                  maximum: 120
                  default: 60
                  type: integer
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                properties:
                  uuid:
                    $ref: '#/components/schemas/uuid'
                  status:
                    $ref: '#/components/schemas/status'
                  direction:
                    $ref: '#/components/schemas/direction'
                  conversation_uuid:
                    $ref: '#/components/schemas/conversation_uuid'
    get:
      security:
      - bearerAuth: []
      summary: Get details of your calls
      description: Get details of your calls
      operationId: getCalls
      parameters:
      - name: status
        in: query
        description: Filter by call status
        schema:
          type: string
          example: started
          enum:
          - started
          - ringing
          - answered
          - machine
          - completed
          - busy
          - cancelled
          - failed
          - rejected
          - timeout
          - unanswered
      - name: date_start
        in: query
        description: Return the records that occurred after this point in time
        schema:
          type: string
          format: date-time
          example: 2016-11-14T07:45:14Z
      - name: date_end
        in: query
        description: Return the records that occurred before this point in time
        schema:
          type: string
          format: date-time
          example: 2016-11-14T07:45:14Z
      - name: page_size
        in: query
        description: Return this amount of records in the response
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
      - name: record_index
        in: query
        description: Return calls from this index in the response
        schema:
          type: integer
          default: 0
      - name: order
        in: query
        description: Either ascending or  descending order.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: conversation_uuid
        in: query
        description: Return all the records associated with a specific conversation.
        schema:
          $ref: '#/components/schemas/conversation_uuid'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    title: The total number of records returned by your request.
                    example: 100
                  page_size:
                    type: integer
                    title: The amount of records returned in this response.
                    example: 10
                  record_index:
                    type: integer
                    title: The `record_index` used in your request.
                    example: 0
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                            title: Link to the object
                            example: "/calls?page_size=10&record_index=20&order=asc"
                  _embedded:
                    description: >-
                        A list of call objects. See the
                        [get details of a specific call](#getCall)
                        response fields for a description of the nested objects
                    type: object
                    properties:
                      calls:
                        type: array
                        items:
                          type: object
                          properties:
                            _links:
                              type: object
                              properties:
                                self:
                                  type: object
                                  properties:
                                    href:
                                      type: string
                                      title: The Link to the Call Object
                                      example: "/calls/63f61863-4a51-4f6b-86e1-46edebcf9356"
                            uuid:
                              $ref: '#/components/schemas/uuid'
                            conversation_uuid:
                              $ref: '#/components/schemas/conversation_uuid'
                            to:
                              $ref: '#/components/schemas/to'
                            from:
                              $ref: '#/components/schemas/from'
                            status:
                              $ref: '#/components/schemas/status'
                            direction:
                              $ref: '#/components/schemas/direction'
                            rate:
                              $ref: '#/components/schemas/rate'
                            price:
                              $ref: '#/components/schemas/price'
                            duration:
                              $ref: '#/components/schemas/duration'
                            start_time:
                              $ref: '#/components/schemas/start_time'
                            end_time:
                              $ref: '#/components/schemas/end_time'
                            network:
                              $ref: '#/components/schemas/network'
  "/{uuid}":
    parameters:
    - in: path
      name: uuid
      schema:
        type: string
      required: true
      description: UUID of the Call
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
    get:
      security:
      - bearerAuth: []
      summary: Get detail of a specific call
      description: Get detail of a specific call
      operationId: getCall
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                            title: Link to the object
                            example: "/calls?page_size=10&record_index=20&order=asc"
                  uuid:
                    $ref: '#/components/schemas/uuid'
                  conversation_uuid:
                    $ref: '#/components/schemas/conversation_uuid'
                  to:
                    $ref: '#/components/schemas/to'
                  from:
                    $ref: '#/components/schemas/from'
                  status:
                    $ref: '#/components/schemas/status'
                  direction:
                    $ref: '#/components/schemas/direction'
                  rate:
                    $ref: '#/components/schemas/rate'
                  price:
                    $ref: '#/components/schemas/price'
                  duration:
                    $ref: '#/components/schemas/duration'
                  start_time:
                    $ref: '#/components/schemas/start_time'
                  end_time:
                    $ref: '#/components/schemas/end_time'
                  network:
                    $ref: '#/components/schemas/network'
    put:
      security:
      - bearerAuth: []
      summary: Modify an in progress call
      description: Modify an in progress call
      operationId: updateCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - action
              properties:
                action:
                  type: string
                  example: mute
                  enum:
                  - hangup
                  - mute
                  - unmute
                  - earmuff
                  - unearmuff
                  - transfer
                  description: The action to apply to the in-progress call
                destination:
                  type: object
                  description: Required when `action` is `transfer`
                  x-nexmo-developer-collection-description-shown: true
                  properties:
                    type:
                      type: string
                      example: ncco
                      description: Always `ncco`
                      x-nexmo-developer-collection-description-shown: true
                    url:                      
                      example: '["https://example.com/ncco.json"]'
                      type: array
                      items:
                        type: string
                      description: The URL that Nexmo makes a request to. Must return an NCCO.
                      x-nexmo-developer-collection-description-shown: true
                    ncco:
                      example: '[{"action": "talk", "text": "hello world"}]'
                      type: array
                      items:
                        type: object
                      description: Can be used instead of `url` for the `transfer` action only.
                      x-nexmo-developer-collection-description-shown: true
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  "/{uuid}/stream":
    parameters:
    - in: path
      name: uuid
      schema:
        type: string
      required: true
      description: UUID of the Call Leg
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
    put:
      security:
      - bearerAuth: []
      summary: Play an audio file into a call
      description: Play an audio file into a call
      operationId: startStream
      requestBody:
        description: action to perform
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - stream_url
              properties:
                stream_url:
                  x-nexmo-developer-collection-description-shown: true
                  example: '["https://example.com/waiting.mp3"]'
                  type: array
                  items:
                    type: string
                loop:
                  type: integer
                  description: the number of times to play the file, 0 for infinite
                  default: 1
                level:
                  type: string
                  description: Set the audio level of the stream in the range `-1 >= level <= 1` with a precision of 0.1. The default value is 0.
                  example: "0.4"
                  default: "0"
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Description of the action taken
                    type: string
                    example: Stream started
                  uuid:
                    $ref: '#/components/schemas/uuid'
    delete:
      security:
      - bearerAuth: []
      summary: Stop playing an audio file into a call
      description: Stop playing an audio file into a call
      operationId: stopStream
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Description of the action taken
                    type: string
                    example: Stream stopped
                  uuid:
                    $ref: '#/components/schemas/uuid'
  "/{uuid}/talk":
    parameters:
    - in: path
      name: uuid
      schema:
        type: string
      required: true
      description: UUID of the Call Leg
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
    put:
      security:
      - bearerAuth: []
      summary: Play text to speech into a call
      description: Play text to speech into a call
      operationId: startTalk
      requestBody:
        description: Action to perform
        content:
          application/json:
            schema:
              required:
                - text
              properties:
                text:
                  type: string
                  description: The text to read
                  example: Hello. How are you today?
                voice_name:
                  $ref: "#/components/schemas/voice_name"
                loop:
                  type: integer
                  description: The number of times to repeat the text the file, 0
                    for infinite
                  default: 1
                level:
                  type: string
                  description: The volume level that the speech is played. This can be any value between `-1` to `1` in `0.1` increments, with `0` being the default.
                  example: "0.4"
                  default: "0"
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Description of the action taken
                    type: string
                    example: Talk started
                  uuid:
                    $ref: '#/components/schemas/uuid'
    delete:
      security:
      - bearerAuth: []
      summary: Stop text to speech in a call
      description: Stop text to speech in a call
      operationId: stopTalk
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Description of the action taken
                    type: string
                    example: Talk stopped
                  uuid:
                    $ref: '#/components/schemas/uuid'
  "/{uuid}/dtmf":
    parameters:
    - in: path
      name: uuid
      schema:
        type: string
      required: true
      description: UUID of the Call Leg
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
    put:
      security:
      - bearerAuth: []
      summary: Play DTMF tones into a call
      description: Play DTMF tones into a call
      operationId: startDTMF
      requestBody:
        description: action to perform
        required: true
        content:
          application/json:
            schema:
              properties:
                digits:
                  type: string
                  example: 1713
                  description: The digits to send
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Description of the action taken
                    type: string
                    example: DTMF sent
                  uuid:
                    $ref: '#/components/schemas/uuid'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    network:
      description: >-
          The Mobile Country Code Mobile Network Code
          ([MCCMNC](https://en.wikipedia.org/wiki/Mobile_country_code)) for
          the carrier network used to make this call.
      type: string
      title: 'The Network ID of the destination '
      example: '65512'
    start_time:
      description: 'The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For example, `2020-01-01 12:00:00`.'
      type: string
      format: timestamp
      title: 'The Start Time of the call '
      example: '2020-01-01 12:00:00'
    end_time:
      description: 'The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For xample, `2020-01-01 12:00:00`. This is only sent if `status` is `completed`.'
      type: string
      format: timestamp
      title: 'The End Time of the call '
      example: '2020-01-01 12:00:00'
    duration:
      description: The time elapsed for the call to take place in seconds. This is only sent if `status` is `completed`.
      type: string
      title: 'The Duration of the call '
      example: '60'
    price:
      description: The total price charged for this call. This is only sent if `status` is `completed`.
      type: string
      title: 'The total price of the call '
      example: '23.40'
    rate:
      description: The price per minute for this call. This is only sent if `status` is `completed`.
      type: string
      title: The Price per minute of the called destination
      example: '0.39'
    direction:
     type: string
     description: Possible values are `outbound` or `inbound`
     example: outbound
     enum:
     - outbound
     - inbound
    uuid:
      type: string
      format: uuid
      title: The UUID of the Call Leg
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
      description: >-
          The unique identifier for this call leg. The UUID is created when
          your call request is accepted by Nexmo. You use the UUID in all
          requests for individual live calls
    conversation_uuid:
      type: string
      format: uuid
      title: The UUID of the Conversation
      example: CON-f972836a-550f-45fa-956c-12a2ab5b7d22
      description: The unique identifier for the conversation this call leg is part of.
    from:
      type: array
      description: The endpoint you called from. Possible values are the same as `to`.
      title: The number or address that has been called
      items:
          type: object
          properties:
            type:
              type: string
              title: The type of Endpoint that made the call
              example: phone
            number:
              type: string
              title: The number that made the call
              example: '447700900001'
    to:
      type: array
      description: The single or mixed collection of endpoint types you connected to
      title: The number or address to call
      items:
          type: object
          properties:
            type:
              type: string
              title: The Type of Endpoint Called
              example: phone
            number:
              type: string
              title: The number of the endpoint called
              example: '447700900000'
    status:
      type: string
      title: The State of the call
      example: started
      description: The status of the call. [See possible values](https://developer.nexmo.com/voice/voice-api/guides/call-flow#event-objects)

    name_user:
      type: string
      example: my_user_name
      description: Unique name for a user

    EndpointApp:
      type: object
      description: Connect to an App User
      required:
        - type
        - user
      properties:
        type:
          type: string
          example: app
          description: The type of connection. Must be `app`
        user:
          type: string
          example: jamie
          description: The username to connect to
    EndpointPhone:
      type: object
      description: Connect to a Phone (PSTN) number
      required:
        - type
      properties:
        type:
          type: string
          example: phone
          description: The type of connection. Must be `phone`
        number:
          "$ref": "#/components/schemas/AddressE164"
        dtmfAnswer:
          description: Provide [DTMF digits](https://developer.nexmo.com/voice/voice-api/guides/dtmf) to send when the call is answered
          type: string
          example: p*123#
    EndpointWebsocket:
      type: object
      description: Connect to a Websocket
      required:
        - type
        - content-type
      properties:
        type:
          description: The type of connection. Must be `websocket`
          type: string
          example: websocket
        uri:
          "$ref": "#/components/schemas/AddressWebsocket"
        content-type:
          type: string
          example: audio/l16;rate=16000
          enum:
            - audio/l16;rate=8000
            - audio/l16;rate=16000
        headers:
          description: Details of the Websocket you want to connect to
          type: object
          properties:
            customer_id:
              type: string
              example: ABC123
              description: This is an example header. You can provide any headers you may need
    EndpointSip:
      type: object
      description: Connect to a SIP Endpoint
      required:
        - type
      properties:
        type:
          description: The type of connection. Must be `sip`
          type: string
          example: sip
        uri:
          "$ref": "#/components/schemas/AddressSip"
    EndpointVBCExtension:
      type: object
      description: Connect to a VBC extension
      required:
        - type
        - extension
      properties:
        type:
          type: string
          example: vbc
          description: The type of connection. Must be `vbc`
        extension:
          type: string
          example: '1234'         
    AddressE164:
      description: The phone number to connect to
      type: string
      minLength: 7
      maxLength: 15
      example: '14155550100'
      pattern: "\\d{7,15}"
    AddressSip:
      description: The SIP URI to connect to
      type: string
      minLength: 1
      maxLength: 50
      example: sip:rebekka@sip.example.com
    AddressWebsocket:
      type: string
      minLength: 1
      maxLength: 50
      example: wss://example.com/socket

    callEvent:
      type: object
      required:
      - conversation_uuid
      - to
      - from
      - uuid
      - status
      properties:
        conversation_uuid:
          description: The UUID of the Conversion that the event relates to
          type: string
          format: uuid
          example: CON-171b3991-49b0-4dfa-badd-2bc6e68b57b4
        to:
          $ref: '#/components/schemas/from'
        from:
          $ref: '#/components/schemas/from'
        uuid:
          description: The UUID of the call leg that the event relates to
          type: string
          format: uuid
          example: 63f61863-4a51-4f6b-86e1-46edebcf9356
        timestamp:
          type: string
          format: date-time
          example: 2018-01-12T15:01:55.315Z
        status:
          type: string
          example: started
          enum:
          - started
          - ringing
          - answered
          - machine
          - completed
          - timeout
          - failed
          - rejected
          - cancelled
          - busy
        direction:
          type: string
          enum:
          - inbound
          - outbound
    voice_name:
      description: The voice & language to use
      type: string
      default: Kimberly
      enum:
      - Salli
      - Joey
      - Naja
      - Mads
      - Marlene
      - Hans
      - Nicole
      - Russell
      - Amy
      - Brian
      - Emma
      - Geraint
      - Gwyneth
      - Raveena
      - Chipmunk
      - Eric
      - Ivy
      - Jennifer
      - Justin
      - Kendra
      - Kimberly
      - Conchita
      - Enrique
      - Penelope
      - Miguel
      - Chantal
      - Celine
      - Mathieu
      - Dora
      - Karl
      - Carla
      - Giorgio
      - Liv
      - Lotte
      - Ruben
      - Agnieszka
      - Jacek
      - Ewa
      - Jan
      - Maja
      - Vitoria
      - Ricardo
      - Cristiano
      - Ines
      - Carmen
      - Maxim
      - Tatyana
      - Astrid
      - Filiz
      - Mizuki
      - Seoyeon
