Call Routing Using Voice Input

In this tutorial, we will guide you through implementing a basic call routing application with FreeClimb that utilizes user DTMF (e.g. keypad) and voice input to route users. This system will perform the following actions:

  • Receive an incoming call via a FreeClimb application
  • Get DTMF (e.g. keypad) or speech input from a user
  • Redirect a user to the appropriate endpoint
You can also find the code for this sample app on GitHub

👍

You're ready for this tutorial if you have:

Followed the IVR sample app set-up instructions


Step 1: Create the express server

The server will provide endpoints where user input can be captured. Create an index.js
file in your project directory, import the needed dependencies, and create/configure the Express application:

require('dotenv-safe').config()
const express = require('express')
const bodyParser = require('body-parser')
const app = express()
app.use(bodyParser.urlencoded({ extended: true }))
app.use(bodyParser.json())
const freeclimbSDK = require('@freeclimb/sdk')

const port = process.env.PORT || 3000

Step 2: Handle an incoming call

The first step in our call routing application will be to handle incoming calls. To do this, add the following to index.js:

const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = freeclimbSDK(accountId, apiKey)
 
let mainMenuErrCount = 0
 
app.post('/incomingCall', (req, res) => {
    res
        .status(200)
        .json(
            freeclimb.percl.build(
                freeclimb.percl.say('Welcome to the node call router 2.0.'),
                freeclimb.percl.pause(100),
                freeclimb.percl.redirect(`${host}/mainMenuPrompt`)
            )
        )
})

Step 3: Collect speech and digits via a main menu

Next we'll collect input from the user to direct them to their next destination. To do this, we'll create endpoints for speech input, DTMF collection, and menu routing and add them to your index.js file:

app.post('/mainMenuPrompt', (req, res) => {
    res.status(200).json(
        freeclimb.percl.build(
            freeclimb.percl.getSpeech(`${host}/mainMenu`, `${host}/mainMenuGrammar`, {
                grammarType: freeclimb.enums.grammarType.URL,
                grammarRule: "option",
                prompts: [
                    freeclimb.percl.say(
                        'Say existing or press 1 for existing orders. Say new or press 2 for new orders, or Say operator or press 0 to speak to an operator'
                    )
                ]
            })
        )
    )
})

Next we'll add the logic for how the app will handle user input to index.js:

app.post('/mainMenu', (req, res) => {
  let menuOpts
  const getSpeechResponse = req.body
  const response = getSpeechResponse.recognitionResult

  if (req.body.reason === freeclimb.enums.getSpeechReason.DIGIT) {
    menuOpts = new Map([
      [
        '1',
        {
          script: 'Redirecting your call to existing orders.',
          redirect: `${host}/endCall`
        }
      ],
      [
        '2',
        {
          script: 'Redirecting your call to new orders.',
          redirect: `${host}/endCall`
        }
      ],
      [
        '0',
        {
          script: 'Redirecting you to an operator',
          redirect: `${host}/transfer`
        }
      ]
    ])
  } else if (req.body.reason === freeclimb.enums.getSpeechReason.RECOGNITION) {
    menuOpts = new Map([
      [
        'EXISTING',
        {
          script: 'Redirecting your call to existing orders.',
          redirect: `${host}/endCall`
        }
      ],
      [
        'NEW',
        {
          script: 'Redirecting your call to new orders.',
          redirect: `${host}/endCall`
        }
      ],
      [
        'OPERATOR',
        {
          script: 'Redirecting you to an operator',
          redirect: `${host}/transfer`
        }
      ]
    ])
  }

  if ((!response || !menuOpts.get(response)) && mainMenuErrCount < 3) {
    mainMenuErrCount++
    res
      .status(200)
      .json(
        freeclimb.percl.build(
          freeclimb.percl.say('Error, please try again'),
          freeclimb.percl.redirect(`${host}/mainMenuPrompt`)
        )
      )
  } else if (mainMenuErrCount >= 3) {
    mainMenuErrCount = 0
    res
      .status(200)
      .json(
        freeclimb.percl.build(
          freeclimb.percl.say('Max retry limit reached'),
          freeclimb.percl.pause(100),
          freeclimb.percl.redirect(`${host}/endCall`)
        )
      )
  } else {
    mainMenuErrCount = 0
    res
      .status(200)
      .json(
        freeclimb.percl.build(
          freeclimb.percl.say(menuOpts.get(response).script),
          freeclimb.percl.redirect(menuOpts.get(response).redirect)
        )
      )
  }
})

Step 4: Create a grammar file

Additionally, we'll also define a custom grammar file to validate any speech input from the user. To do so, create a file called mainMenuGrammar.xml in the root directory of your project with the following content:

<?xml version="1.0" encoding="UTF-8"?>
 
<grammar xml:lang="en-US" tag-format="semantics-ms/1.0" version="1.0" root="option" mode="voice" xmlns="http://www.w3.org/2001/06/grammar">
<rule id="option" scope="public">
    <item>
        <item repeat="0-1"><ruleref uri="#UMFILLER"/></item>
        <item>
            <one-of>
                <item>existing<tag>$._value = "EXISTING";</tag></item>
                <item>new<tag>$._value = "NEW";</tag></item>
                <item>operator<tag>$._value = "OPERATOR";</tag></item>
            </one-of>
        </item>
        <item repeat="0-1"><ruleref uri="#TRAILERS"/></item>
    </item>
</rule>
 
<rule id="UMFILLER">
    <one-of>
        <item> uh </item>
        <item> um </item>
        <item> hm </item>
        <item> ah </item>
        <item> er </item>
    </one-of>
</rule>
 
<rule id="TRAILERS">
    <one-of>
        <item> maam </item>
        <item> sir </item>
        </one-of>
</rule>
 
</grammar>

📘

Want to learn more about creating grammar files?

To learn more, check out our How to Write Grammars guide.

Step 5: Get the grammar file

We'll also add an endpoint used by the GetSpeech PerCL command to load our grammar file for use. To do this, add the following to index.js before /mainMenu:

app.get('/mainMenuGrammar', function (req, res) {
    const file = `${__dirname}/mainMenuGrammar.xml`
    res.download(file)
})

Step 6: Transfer and end call

Finally we'll add in appropriate endpoints for simulating a call transfer and ending a call. Do so by adding to following to index.js:

app.post('/transfer', (req, res) => {
  res
    .status(200)
    .json(
      freeclimb.percl.build(
        freeclimb.percl.say('Please wait while we transfer you to an operator'),
        freeclimb.percl.redirect(`${host}/endCall`)
      )
    )
})

app.post('/endCall', (req, res) => {
  res
    .status(200)
    .json(
      freeclimb.percl.build(
        freeclimb.percl.say(
          'Thank you for calling the Node IVR sample app baseline, have a nice day!'
        ),
        freeclimb.percl.hangup()
      )
    )
})

Then, set the app to listen on your desired port:

const server = app.listen(port, () => {
  console.log(`Starting server on port ${port}`)
})

module.exports = { app, server }

Step 7: Run your app

To hear your IVR Voice-Enabled Call Routing app in action, run the following command at the command line:

yarn start

Once you do this, call the FreeClimb number associated with your application. From there you should be able to experience your call routing application.

For a more advanced IVR tutorial, try out our Pay by Phone with Voice Calling sample app.

Congrats! You can now build your own custom IVR voice-enabled call routing application. 🥳🥳

Updated 16 days ago


Call Routing Using Voice Input


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.