_README.md

Handle user input with DTMF

Specification

A building block that shows how to handle an user input with DTMF

• 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 answer endpoint response should return a 200 status code

• Your endpoint should handle both query string parameters and JSON on both GET and POST methods.

• Your endpoints should handle query string parameters on GET and POST

• Your endpoint should handle JSON on POST

• When /webhooks/dtmf is called a 200 OK repsonse should be returned.

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

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

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

  • GET

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

  • POST

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

Should all return:

[
  {
    "action": "talk",
    "text": "Please enter a digit"
  },
  {
    "action": "input",
    "eventUrl": [
      "http://127.0.0.1:3000/webhooks/dtmf"
    ]
  }
]

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

  • GET + Query

    curl "http://127.0.0.1:3000/webhooks/dtmf?dtmf=7"

  • POST + Query

    curl -X "POST" "http://127.0.0.1:3000/webhooks/dtmf?dtmf=7"

  • POST + JSON

    curl -X "POST" "http://127.0.0.1:3000/webhooks/dtmf" \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d $'{ "dtmf": "7" }'

Should all return:

[
  {
    "action": "talk",
    "text": "You pressed 7"
  }
]

• 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

handle-user-input-with-dtmf.md

Handle user input with DTMF

Handling user input with Nexmo is easy. You just need to provide an NCCO to start listenting for input and provide a webhook endpoint for handling the event when it happens.

Prerequisites

• Rent a virtual number

Implement a webhook

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

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 dtmfUrl = String.format("%s://%s/webhooks/dtmf", req.scheme(), req.host());

        TalkNcco intro = new TalkNcco("Please enter a digit");
        InputNcco input = new InputNcco();
        input.setEventUrl(dtmfUrl);
        Ncco[] nccos = new Ncco[]{intro, input,};

        res.type("application/json");
        return nccoMapper.writer().writeValueAsString(nccos);
    };

    /*
     * Webhook Route which returns NCCO saying which DTMF code was received.
     */
    Route dtmfWebhookRoute = (req, res) -> {
        TalkNcco intro = new TalkNcco(String.format("You pressed %s", extractDtmf(req)));
        Ncco[] nccos = new Ncco[]{intro};

        res.type("application/json");
        return nccoMapper.writer().writeValueAsString(nccos);
    };

    port(3000);

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

    get("/webhooks/dtmf", dtmfWebhookRoute);
    post("/webhooks/dtmf", dtmfWebhookRoute);
}

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

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 be asked to enter a number that is then repeated back to you.