Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Record calls and conversations

Recordings are contextual, they are attached to the UUID of each leg in a Call or a Conversation. Different NCCOs are used to record in the two different contexts.

  • Calls - you set the record action at the start of your NCCO so everything is recorded. Recording starts when the record action is executed in the NCCO and finishes when the synchronous condition in the action is met. That is, endOnSilence, timeOut or endOnKey. If you do not set a synchronous condition, the Voice API immediately executes the next NCCO without recording.
  • Conversations - you set the record option in the conversation action. For standard conversations, recordings start when one or more attendee connects to the conversation and terminate when the last attendee disconnects. For moderated conversations, recordings start when the moderator joins. That is, when an NCCO is executed for the named conversation where ‘startOnEnter’ is set to true. When the recording is terminated, the URL you download the recording from is sent to the event URL.

The workflow to create a recording is:

  1. Use the record NCCO action to record an active Call or Conversation:

    [
      {
          "action": "talk",
          "text": "Please leave a message after the tone, then press #. We will get back to you as soon as we can",
          "voiceName": "Emma"
      },
      {
          "action": "record",
          "eventUrl": [
              "http://myrecordings/voicemails"
          ],
          "endOnSilence": "3",
          "endOnKey" : "#",
          "beepStart": "true"
      },
      {
          "action": "talk",
          "text": "Thank you for your message. Goodbye"
      }
    ]
    

    By default audio is recorded in MP3 format.

  2. When the Call or Conversation is complete, information about the recording is sent to the webhook URL you set in the eventUrl option.

    {
      "start_time": "2016-09-14T13:21:55Z",
      "recording_url": "https://api.nexmo.com/media/download?id=5345cf0-345c-34b3-a23b-ca6ccfe144b0",
      "size": 84413,
      "recording_uuid": "53383284-b36d-498c-b733-aa0234c2234",
      "end_time": "2016-09-14T13:22:17Z",
      "conversation_uuid": "aa5c81cb-78ef-4e28-234-801c0ea234"
    }
    

    Note: recording_uuid is not the same as the file uuid in recording_url. See the parameters sent to eventURL.

  3. Make a GET request using your JWT for authentication in order to retrieve the recording from recording_url.

    #!/bin/bash
    #This script assumes you have already installed Nexmo CLI
    #1. Set the recording_url that you recieved at eventURL
    recording_url="https://api.nexmo.com/v1/files/17cb9958-3878-4562-b6a7-f67a0adsfsdfd"
    #2. Set a Generic file name for the file holding the private key for this Application.
    private_key_file="./tts_application.key"
    #3. Check that you have the id and private_key for the Voice API application
    #   associated with the recording
    if [ -f "./application_id" ];
    then
    application_id=`cat ./application_id`
    echo "  Using application: " $application_id
    else
    echo "  You need the application_id and private_key for the application tied to this recording."
    exit 1
    fi
    APP_JWT="$(nexmo jwt:generate $private_key_file iat=`date +%s` application_id=$application_id)"
    JWT=${APP_JWT#*"T:"}
    #4. Download the recording.
    curl $recording_url \
    -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json"
    

    Note: After your recording is complete, it is stored by Nexmo for 30 days.