Voice API

The Voice API lets you create outboud calls, control in progress calls and get information about historical calls.

Download OpenAPI 3 Definition

Calls

Create and search calls

Create an outbound call

Create an outbound Call

POST https://api.nexmo.com/v1 /calls

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • to
    Required | array
    None

    Any one of the following:

    Connect to a Phone (PSTN) number
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be phone


      Must be one of: phone
      phone
      None
    • number
      string

      The phone number to connect to

      14155550100
      None
    • dtmfAnswer
      string

      Provide DTMF digits to send when the call is answered

      p*123#
      None
    Connect to a SIP Endpoint
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be sip


      Must be one of: sip
      sip
      None
    • uri
      string

      The SIP URI to connect to

      rebekka@sip.example.com
      None
    Connect to a Websocket
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be websocket


      Must be one of: websocket
      websocket
      None
    • uri
      string

      None

      wss://example.com/socket
      None
    • content-type
      string

      None


      Must be one of: audio/l16;rate=8000oraudio/l16;rate=16000
      audio/l16;rate=16000
      None
    • headers
      object
      None
      • Key
        Description
        Example
        Default
      • customer_id
        string

        This is an example header. You can provide any headers you may need

        ABC123
        None
  • from
    Required | array
    None

    Any one of the following:

    Connect to a Phone (PSTN) number
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be phone


      Must be one of: phone
      phone
      None
    • number
      string

      The phone number to connect to

      14155550100
      None
    • dtmfAnswer
      string

      Provide DTMF digits to send when the call is answered

      p*123#
      None
    Connect to a SIP Endpoint
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be sip


      Must be one of: sip
      sip
      None
    • uri
      string

      The SIP URI to connect to

      rebekka@sip.example.com
      None
    Connect to a Websocket
    • Key
      Description
      Example
      Default
    • type
      string

      The type of connection. Must be websocket


      Must be one of: websocket
      websocket
      None
    • uri
      string

      None

      wss://example.com/socket
      None
    • content-type
      string

      None


      Must be one of: audio/l16;rate=8000oraudio/l16;rate=16000
      audio/l16;rate=16000
      None
    • headers
      object
      None
      • Key
        Description
        Example
        Default
      • customer_id
        string

        This is an example header. You can provide any headers you may need

        ABC123
        None
  • answer_url
    Required | array
    of string's

    The webhook endpoint where you provide the Nexmo Call Control Object that governs this call.

    ["https://example.com/answer"]
    None
  • answer_method
    string

    The HTTP method used to send event information to answer_url.


    Must be one of: POSTorGET
    None
    GET
  • event_url
    array
    of string's

    The webhook endpoint where call progress events are sent to. For more information about the values sent, see callback

    ["https://example.com/event"]
    None
  • event_method
    string

    The HTTP method used to send event information to event_url.


    Must be one of: POSTorGET
    None
    POST
  • machine_detection
    string

    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


    Must be one of: continueorhangup
    continue
    None
  • length_timer
    integer

    Set the number of seconds that elapse before Nexmo hangs up after the call state changes to in_progress.


    Must be between 1 and 7200
    None
    7200
  • ringing_timer
    integer

    Set the number of seconds that elapse before Nexmo hangs up after the call state changes to ‘ringing’.


    Must be between 1 and 120
    None
    60

View response field descriptions


201 HTTP response

{
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
  "status": "started",
  "direction": "outbound",
  "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22"
}

Get details of your calls

Get details of your calls

GET https://api.nexmo.com/v1 /calls

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Query Parameter

  • Key
    Description
    Example
    Default
  • status
    string

    Filter by call status


    Must be one of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelledorbusy
    started
    None
  • date_start
    string (date-time)

    Return the records that occurred after this point in time

    2016-11-14 07:45:14 UTC
    None
  • date_end
    string (date-time)

    Return the records that occurred before this point in time

    2016-11-14 07:45:14 UTC
    None
  • page_size
    integer

    Return this amount of records in the response

    None
    10
  • record_index
    integer

    Return calls from this index in the response

    None
    0
  • order
    string

    Either ascending or descending order.


    Must be one of: ascordesc
    None
    asc
  • conversation_uuid
    string (uuid)

    Return all the records associated with a specific conversation.

    CON-f972836a-550f-45fa-956c-12a2ab5b7d22
    None

View response field descriptions


200 HTTP response

{
  "count": 100,
  "page_size": 10,
  "record_index": 0,
  "_links": {
    "self": {
      "href": "/calls?page_size=10&record_index=20&order=asc"
    }
  },
  "_embedded": {
    "calls": [
      {
        "_links": {
          "self": {
            "href": "/calls/63f61863-4a51-4f6b-86e1-46edebcf9356"
          }
        },
        "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
        "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
        "to": [
          {
            "type": "phone",
            "number": "447700900000"
          }
        ],
        "from": [
          {
            "type": "phone",
            "number": "447700900001"
          }
        ],
        "status": "started",
        "direction": "outbound",
        "rate": "0.39",
        "price": "23.40",
        "duration": "60",
        "start_time": "2020-01-01 12:00:00",
        "end_time": "2020-01-01 12:00:00",
        "network": "65512"
      }
    ]
  }
}

Call

Manage a specfic call

Get detail of a specific call

Get detail of a specific call

GET https://api.nexmo.com/v1 /calls/:uuid

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

View response field descriptions


200 HTTP response

{
  "_links": {
    "self": {
      "href": "/calls?page_size=10&record_index=20&order=asc"
    }
  },
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
  "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
  "to": [
    {
      "type": "phone",
      "number": "447700900000"
    }
  ],
  "from": [
    {
      "type": "phone",
      "number": "447700900001"
    }
  ],
  "status": "started",
  "direction": "outbound",
  "rate": "0.39",
  "price": "23.40",
  "duration": "60",
  "start_time": "2020-01-01 12:00:00",
  "end_time": "2020-01-01 12:00:00",
  "network": "65512"
}

Modify an in progress call

Modify an in progress call

PUT https://api.nexmo.com/v1 /calls/:uuid

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • action
    Required | string

    None


    Must be one of: hangup, mute, unmute, earmuff, unearmuffortransfer
    mute
    None
  • destination
    object
    None
    • Key
      Description
      Example
      Default
    • type
      string

      None


      Must be one of: ncco
      ncco
      None
    • url
      array
      of string's

      None

      ["https://example.com/ncco.json"]
      None

204 HTTP response

No content

Stream

Stream audio to an active call

Play an audio file into a call

Play an audio file into a call

PUT https://api.nexmo.com/v1 /calls/:uuid/stream

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • stream_url
    array
    of string's

    None

    ["https://example.com/waiting.mp3"]
    None
  • loop
    integer

    the number of times to play the file, 0 for infinite

    None
    1

View response field descriptions


200 HTTP response

{
  "message": "Stream started",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Stop playing an audio file into a call

Stop playing an audio file into a call

DELETE https://api.nexmo.com/v1 /calls/:uuid/stream

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

View response field descriptions


200 HTTP response

{
  "message": "Stream stopped",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Talk

Send a synthesized speech message to an active call

Play text to speech into a call

Play text to speech into a call

PUT https://api.nexmo.com/v1 /calls/:uuid/talk

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • text
    string

    The text to read

    Hello. How are you today?
    None
  • voiceName
    string

    None


    Must be one of: 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, MizukiorSeoyeon
    None
    Kimberly
  • loop
    integer

    The number of times to repeat the text the file, 0 for infinite

    None
    1

View response field descriptions


200 HTTP response

{
  "message": "Talk started",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Stop text to speech in a call

Stop text to speech in a call

DELETE https://api.nexmo.com/v1 /calls/:uuid/talk

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

View response field descriptions


200 HTTP response

{
  "message": "Talk stopped",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

DTMF

Send Dual-tone multi-frequency (DTMF) tones to an active call

Play DTMF tones into a call

Play DTMF tones into a call

PUT https://api.nexmo.com/v1 /calls/:uuid/dtmf

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Path Parameters

  • Key
    Description
    Example
    Default
  • uuid
    Required | string

    UUID of the Call

    63f61863-4a51-4f6b-86e1-46edebcf9356
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • digits
    string

    The digits to send

    1713
    None

View response field descriptions


200 HTTP response

{
  "message": "DTMF sent",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}