_README.md

Record a call

Specification

A building block that shows how to handle an inbound call that joins a conference call

• You must specify one endpoint must be on the path /webhooks/answer

• Your endpoint must be accessible on GET and on POST requests

• Your endpoint must listen on port 3000

• Your response should return a 200 status code

• The eventURL should be like http://127.0.0.1:3000/webhooks/recording or https://demo.ngrok.io/webhooks/recording and should be dynamically made up of:

  • The request protocol
  • The request hostname
  • The request port (only if present)
  • /webhooks/recording

• Your response should be JSON NCCO with the the following or equivalent body:

  • GET request

  $ curl "http://127.0.0.1:3000/webhooks/answer"
  

  • POST request

  $ curl -X "POST" "http://127.0.0.1:3000/webhooks/answer"
  

  Should both result in the response:

  [  
    {  
      "action": "talk",
      "text": "Please leave a message after the tone, then press pound."
    },
    {  
      "action": "record",
      "endOnKey": "#",
      "beepStart": "true",
      "eventUrl":[  
        "http://127.0.0.1:3000/webhooks/recording"
      ]
    },
    {  
      "action": "talk",
      "text": "Thank you for your message."
    }
  ]

• The following requests should log out https://example.com and return a 204 status code:

  • GET request

  $ curl "http://127.0.0.1:3000/webhooks/recording?recording_url=https://example.com"
  

  • POST request

  $ curl -X "POST" "http://127.0.0.1:3000/webhooks/recording?recording_url=https://example.com"
  

  • POST + JSON request

  $ curl -X "POST" "http://127.0.0.1:3000/webhooks/recording" \
   -H 'Content-Type: application/json; charset=utf-8' \
   -d $'{"recording_url": "https://example.com"}'
  

• Code examples should include a GitHub link to the file

• Code examples should include the line numbers used from the linked file

• All code examples must be present in the master branch of the relevant quickstart repo

• All code examples must be tested to work (manual testing is fine)

Instructions

1. Fork this gist
2. Edit the gist and the building block files to match the specification
3. Return Gist as a comment in the original issue

record-a-call.md

Record a call

Recording calls with Nexmo is easy. In this example we'll accept an inbound call and start recording. The a URL to the audio file will then be sent to another webhook.

Implement a webhook

// GITHUB: https://github.com/nexmo-community/nexmo-java-quickstart/blob/master/src/main/java/com/nexmo/quickstart/voice/RecordCall.java
// Lines: 36-90

public static void main(String[] args) throws Exception {
    ObjectMapper nccoMapper = new ObjectMapper();

    /*
     * Route to answer incoming calls with an NCCO response.
     */
    Route answerRoute = (req, res) -> {
        String recordingUrl = String.format("%s://%s/webhooks/recording", req.scheme(), req.host());

        TalkNcco intro = new TalkNcco("Please leave a message after the tone, then press pound.");
        RecordNcco record = new RecordNcco();
        record.setEndOnKey('#');
        record.setBeepStart(true);
        record.setEventUrl(recordingUrl);
        TalkNcco thanks = new TalkNcco("Thank you for your message.");
        Ncco[] nccos = new Ncco[]{intro, record, thanks};
        res.type("application/json");
        return nccoMapper.writer().writeValueAsString(nccos);
    };

    /**
     * Webhook Route which prints out the recording URL it is given to stdout.
     */
    Route recordingWebhookRoute = (req, res) -> {
        System.out.printf("Recording URL = %s\n", extractRecordingUrl(req));

        res.status(204);
        return "";
    };

    port(3000);

    get("/webhooks/answer", answerRoute);
    post("/webhooks/answer", answerRoute);

    get("/webhooks/recording", recordingWebhookRoute);
    post("/webhooks/recording", recordingWebhookRoute);
}

/**
 * Extract the provided recording_url either from the request params, or JSON body.
 */
private static String extractRecordingUrl(Request req) throws IOException {
    String recordingUrl = req.queryParams("recording_url");
    if ("GET".equals(req.requestMethod())) {
        return recordingUrl;
    } else {
        if (recordingUrl != null) {
            return recordingUrl;
        } else {
            RecordingPayload payload = RecordingPayload.fromJson(req.bodyAsBytes());
            return payload.getRecordingUrl();
        }
    }
}

Run your server

Add the following dependencies to your project:

compile 'com.nexmo:client:3.1.0'
compile "com.sparkjava:spark-core:2.6.0"

Then run your class in whichever way you find easiest.

You'll need to expose your server to the open internet. During development you can use a tool like Ngrok to do that.

Associate an application to your webhook

To link your number to the endpoint you've just created we'll need an Application.

$ nexmo app:create demo <YOUR_HOSTNAME>/webhooks/answer <YOUR_HOSTNAME>/webhooks/event
$ nexmo link:app <NEXMO_NUMBER> <NEXMO_APPLICATION_ID>

Call your number

When you call your Nexmo number you should hear the text-to-speech message, can record a message and then the recording will be logged to your console.