Vonage Calls API

openapi: 3.2.0
info:
  title: Vonage Calls API
  version: 1.10.0
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com/
  x-metaDescription: Our Voice API Reference provides developers with quick answers to questions about the Vonage Voice API. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Voice API Reference | Vonage API Documentation
  description: 'Operations tagged Calls across 2 of this provider''s published API definitions: vonage-voice-openapi.json, vonage-voice-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nexmo.com/v1/calls
tags:
- name: Calls
  description: Fetch, Create and Modify voice calls
paths:
  /:
    get:
      tags:
      - Calls
      security:
      - bearerAuth: []
      summary: 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 available after this point in time. Please use [Reports API](https://developer.vonage.com/en/reports/overview) for older call information.
        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:
                $ref: '#/components/schemas/GetCallsResponse'
    post:
      tags:
      - Calls
      security:
      - bearerAuth: []
      summary: Create an outbound call
      description: Create an outbound Call
      operationId: createCall
      requestBody:
        description: Call Details
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreateCallRequestNcco'
              - $ref: '#/components/schemas/CreateCallRequestAnswerUrl'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCallResponse'
    servers:
    - url: https://api.nexmo.com/v1/calls
  /{uuid}:
    parameters:
    - in: path
      name: uuid
      schema:
        type: string
      required: true
      description: UUID of the Call
      example: 63f61863-4a51-4f6b-86e1-46edebcf9356
    get:
      tags:
      - Calls
      security:
      - bearerAuth: []
      summary: Get detail of a specific call
      operationId: getCall
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCallResponse'
    put:
      tags:
      - Calls
      security:
      - bearerAuth: []
      summary: Modify an in progress call
      operationId: updateCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/UpdateCallRequestTransferNcco'
              - $ref: '#/components/schemas/UpdateCallRequestTransferAnswerUrl'
              - $ref: '#/components/schemas/UpdateCallRequestHangup'
              - $ref: '#/components/schemas/UpdateCallRequestMute'
              - $ref: '#/components/schemas/UpdateCallRequestUnmute'
              - $ref: '#/components/schemas/UpdateCallRequestEarmuff'
              - $ref: '#/components/schemas/UpdateCallRequestUnearmuff'
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '404':
          description: Not Found
    servers:
    - url: https://api.nexmo.com/v1/calls
components:
  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. This is only sent if `status` is `completed`.
      type: string
      title: 'The Network ID of the destination '
      example: '65512'
    UpdateCallRequestTransferNcco:
      title: Transfer with NCCO
      type: object
      required:
      - action
      - destination
      properties:
        action:
          $ref: '#/components/schemas/RequestTransferActionParam'
        destination:
          type: object
          required:
          - type
          - ncco
          properties:
            type:
              type: string
              example: ncco
              description: Always `ncco`
              x-nexmo-developer-collection-description-shown: true
            ncco:
              type: array
              example:
              - action: talk
                text: Hello World
              items:
                type: object
              description: Refer to the [NCCO Guide](https://developer.nexmo.com/voice/voice-api/ncco-reference) for a description of possible NCCO parameters.
              x-nexmo-developer-collection-description-shown: true
    RequestTransferActionParam:
      description: Transfer the call to a new NCCO
      type: string
      example: transfer
      enum:
      - transfer
    CreateCallRequestNcco:
      allOf:
      - $ref: '#/components/schemas/CreateCallRequestBase'
      - type: object
        title: With NCCO
        required:
        - ncco
        properties:
          ncco:
            description: '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
    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'
    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: date-time
      title: 'The End Time of the call '
      example: '2020-01-01 12:00:00'
    UpdateCallRequestHangup:
      title: Hangup
      properties:
        action:
          type: string
          example: hangup
          enum:
          - hangup
          description: End the call for the specified UUID
    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 Vonage. You use the UUID in all requests for individual live calls
    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'
    UpdateCallRequestEarmuff:
      title: Earmuff
      properties:
        action:
          type: string
          example: earmuff
          enum:
          - earmuff
          description: Prevent the specified UUID from hearing audio
    EndpointPhoneFrom:
      type: object
      description: 'Connect to a Phone (PSTN) number. This property is mutually exclusive with `random_from_number`: you must specify one (`from`) or the other (`random_from_number: true`).'
      required:
      - number
      - type
      properties:
        type:
          type: string
          example: phone
          description: The type of connection. Must be `phone`.
        number:
          type: string
          example: '14155550100'
          description: The phone number to connect to. It can be either an E.164 formatted number or a SIP URI.
    EndpointPhoneTo:
      type: object
      description: Connect to a Phone (PSTN) number
      required:
      - number
      - 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/concepts/dtmf) to send when the call is answered
          type: string
          example: p*123#
        shaken:
          description: For Vonage customers who are required by the FCC to sign their own calls to the USA, we allow you to place Voice API calls with your own signature. This feature is available by request only. Please be aware calls with an invalid signature will be rejected. For more information please contact us. In this option, you must place the STIR/SHAKEN Identity Header content that Vonage must use for this call. Expected format is composed of the JWT with the header, payload and signature, an info parameter with a link for the certificate, the algorithm (alg) parameter indicating which encryption type was used and the passport type (ppt) which should be shaken.
          type: string
          example: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"
    direction:
      type: string
      description: Possible values are `outbound` or `inbound`
      example: outbound
      enum:
      - outbound
      - inbound
    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.
    GetCallsResponse:
      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
            first:
              type: object
              properties:
                href:
                  type: string
                  title: Link to the object
                  example: /calls?page_size=10&record_index=20&order=asc
            last:
              type: object
              properties:
                href:
                  type: string
                  title: Link to the object
                  example: /calls?page_size=10&record_index=20&order=asc
            next:
              type: object
              properties:
                href:
                  type: string
                  title: Link to the object
                  example: /calls?page_size=10&record_index=20&order=asc
            prev:
              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:
                $ref: '#/components/schemas/GetCallResponse'
    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`. This is only sent if `status` is `completed`.'
      type: string
      format: date-time
      title: 'The Start Time of the call '
      example: '2020-01-01 12:00:00'
    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
          - audio/l16;rate=24000
        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
        authorization:
          description: Optional configuration defining how the Authorization HTTP header is set in the WebSocket opening handshake.
          type: object
          properties:
            type:
              type: string
              default: vonage
              example: vonage
              description: Defines the authorization mode. "vonage" – the Voice API includes the same JWT used for signed webhooks in the Authorization header ('Bearer {JWT}'). "custom" – a developer-supplied Authorization header value is sent verbatim.
              enum:
              - vonage
              - custom
            value:
              type: string
              example: Bearer abc123
              description: Required only when authorization.type = "custom". The raw header value to include, e.g. "Bearer abc123" or "ApiKey X9Z...". Ignored when authorization.type = "vonage".
    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'
    CreateCallRequestAnswerUrl:
      allOf:
      - $ref: '#/components/schemas/CreateCallRequestBase'
      - type: object
        title: With Answer URL
        required:
        - answer_url
        properties:
          answer_url:
            description: '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
            items:
              type: string
              format: uri
              example: https://example.com/answer
          answer_method:
            description: The HTTP method used to send event information to answer_url.
            type: string
            default: GET
            enum:
            - POST
            - GET
    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'
    UpdateCallRequestUnearmuff:
      title: Unearmuff
      properties:
        action:
          type: string
          example: unearmuff
          enum:
          - unearmuff
          description: Allow the specified UUID to hear audio
    UpdateCallRequestMute:
      title: Mute
      properties:
        action:
          type: string
          example: mute
          enum:
          - mute
          description: Mute the specified UUID
    status:
      type: string
      title: The State of the call
      example: completed
      description: The status of the call. [See possible values](https://developer.nexmo.com/voice/voice-api/guides/call-flow#event-objects)
    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
    AddressE164:
      description: The phone number to connect to
      type: string
      minLength: 7
      maxLength: 15
      example: '14155550100'
      pattern: \d{7,15}
    UpdateCallRequestUnmute:
      title: Unmute
      properties:
        action:
          type: string
          example: unmute
          enum:
          - unmute
          description: Unmute the specified UUID
    from:
      type: object
      description: The endpoint you called from. Possible values are the same as `to`.
      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'
    CreateCallRequestBase:
      type: object
      required:
      - to
      properties:
        to:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/EndpointPhoneTo'
            - $ref: '#/components/schemas/EndpointSip'
            - $ref: '#/components/schemas/EndpointWebsocket'
            - $ref: '#/components/schemas/EndpointVBCExtension'
            - $ref: '#/components/schemas/EndpointApp'
            discriminator:
              propertyName: type
              mapping:
                phone: '#/components/schemas/EndpointPhoneTo'
                sip: '#/components/schemas/EndpointSip'
                websocket: '#/components/schemas/EndpointWebsocket'
                vbc: '#/components/schemas/EndpointVBCExtension'
                app: '#/components/schemas/EndpointApp'
        from:
          $ref: '#/components/schemas/EndpointPhoneFrom'
        random_from_number:
          description: 'Set to `true` to use random phone number as `from`. The number will be selected from the list of the numbers assigned to the current application. This property is mutually exclusive with `from`: you must specify one (`random_from_number: true`) or the other (`from`).'
          type: boolean
          default: false
        event_url:
          description: '**Required** unless `event_url` is configured at the application

            level, see [Create an Application](/api/application.v2#createApplication)


            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
          items:
            type: string
            format: uri
            example: https://example.com/event
        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 Vonage detects that the call is answered by voicemail. If `continue`, Vonage sends an HTTP request to `event_url` with the Call event machine. If `hangup`, Vonage ends the call.
          type: string
          enum:
          - continue
          - hangup
          example: continue
        advanced_machine_detection:
          description: Configure the behavior of Vonage's advanced machine detection. Overrides `machine_detection` if both are set. Note that this is a beta feature which will be chargeable; exact rates can be found on the [Voice API Pricing](https://www.vonage.co.uk/communications-apis/voice/pricing/) page under 'Programmable Features'.
          type: object
          properties:
            behavior:
              description: When `hangup` is used, the call will be terminated if a machine is detected. When `continue` is used, the call will continue even if a machine is detected.
              type: string
              enum:
              - continue
              - hangup
            mode:
              description: 'Detect if machine answered and sends a human or machine status in the webhook payload. The modes are as follows:


                * `default` - async mode, the next NCCO action will be processed immediately in parallel with machine detection, the application will receive both machine detection status and beep events and can reply with new NCCO to any of them;


                * `detect` - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only machine detection status event;


                * `detect_beep` - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only a beep event.

                '
              type: string
              default: detect
              enum:
              - default
              - detect
              - detect_beep
            beep_timeout:
              description: Maximum time in seconds Vonage should wait for a machine beep to be detected. A machine event with `sub_state` set to `beep_timeout` will be sent if the timeout is exceeded.
              type: integer
              minimum: 30
              maximum: 120
        length_timer:
          description: Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.
          minimum: 1
          maximum: 86400
          default: 7200
          type: integer
        ringing_timer:
          description: Set the number of seconds that elapse before Vonage hangs up after the call state changes to ‘ringing’.
          minimum: 1
          maximum: 120
          default: 60
          type: integer
    GetCallResponse:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  title: 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:
          type: object
          description: The single or mixed collection of endpoint types you connected to
          oneOf:
          - $ref: '#/components/schemas/EndpointPhoneTo'
          - $ref: '#/components/schemas/EndpointSip'
          - $ref: '#/components/schemas/EndpointWebsocket'
          - $ref: '#/components/schemas/EndpointVBCExtension'
          - $ref: '#/components/schemas/EndpointApp'
          discriminator:
            propertyName: type
            mapping:
              phone: '#/components/schemas/EndpointPhoneTo'
              sip: '#/components/schemas/EndpointSip'
              websocket: '#/components/schemas/EndpointWebsocket'
              vbc: '#/components/schemas/EndpointVBCExtension'
              app: '#/components/schemas/EndpointApp'
        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'
    CreateCallResponse:
      type: object
      properties:
        uuid:
          $ref: '#/components/schemas/uuid'
        status:
          $ref: '#/components/schemas/status'
        direction:
          $ref: '#/components/schemas/direction'
        conversation_uuid:
          $ref: '#/components/schemas/conversation_uuid'
    EndpointSip:
      type: object
      description: Connect to a SIP Endpoint
      required:
      - type
      - uri
      properties:
        type:
          description: The type of connection. Must be `sip`
          type: string
          example: sip
        uri:
          $ref: '#/components/schemas/AddressSip'
        headers:
          description: 'Metadata to include in the request. The headers are transmitted as part of the SIP INVITE as `X-key: value` headers.'
          type: object
          example:
            location: New York City
            occupation: developer
        standard_headers:
          description: Standard SIP INVITE headers. Unlike the `headers` property, these are not prepended with `X-`.
          type: object
          required:
          - User-to-User
          properties:
            User-to-User:
              description: Transmit user-to-user information if supported by the CC / PBX vendor, as per [RFC 7433](https://datatracker.ietf.org/doc/html/rfc7433).
              type: string
    AddressWebsocket:
      type: string
      minLength: 1
      example: wss://example.com/socket
    UpdateCallRequestTransferAnswerUrl:
      title: Transfer with Answer URL
      type: object
      required:
      - action
      - destination
      properties:
        action:
          $ref: '#/components/schemas/RequestTransferActionParam'
        destination:
          type: object
          required:
          - type
          - url
          properties:
            type:
              type: string
              description: Always `ncco`
              example: ncco
              x-nexmo-developer-collection-description-shown: true
            url:
              type: array
              example:
              - https://example.com/ncco.json
              items:
                type: string
              description: The URL that Vonage makes a request to. Must return an NCCO.
              x-nexmo-developer-collection-description-shown: true
    AddressSip:
      description: The SIP URI to connect to
      type: string
      minLength: 1
      maxLength: 50
      example: sip:rebekka@sip.example.com
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- vonage-voice-openapi.json
- vonage-voice-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one