Guides
API StatusSupportLog In

Self Service Using Text-to-Speech

Suggest Edits

In this how-to guide, we will walk you through implementing a basic self service IVR application with FreeClimb that utilizes user DTMF (e.g. keypad) and voice input. 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
  • Return information to the user based on previous input

This self service how-to guide relies on the Say PerCL command for IVR content. To build this guide using the Play PerCL command instead, try the Self Service Using Audio Files guide.

You can also find the code for this sample app on GitHub

👍

You're ready for this how-to guide 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 port = process.env.PORT || 3000

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

module.exports = { app }

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 {
    createConfiguration,
    DefaultApi,
    PerclScript,
    Say,
    Pause,
    Redirect,
    GetDigits,
    Hangup
} = require('@freeclimb/sdk')

const port = process.env.PORT || 3000
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

app.post('/incomingCall', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new Say({ text: 'Welcome to the Node self service IVR.' }),
                new Pause({ length: 100 }),
                new Redirect({ actionUrl: `${host}/mainMenuPrompt` })
            ]
        }).build()
    )
})

We'll also use index.js to contain the routes for handling call end and transfer. To create these add the following to index.js after /incomingCall but before app.listen:

app.post('/transfer', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new Say({ text: 'there are no operators available at this time' }),
                new Redirect({ actionUrl: `${host}/endCall` })
            ]
        }).build()
    )
})

app.post('/endCall', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new Say({
                    text: 'Thank you for calling the Node self service IVR , have a nice day!'
                }),
                new Hangup({})
            ]
        }).build()
    )
})

Step 3: Collect speech and digits via a main menu

Next we'll create a main menu for

  • collecting DTMF and speech input from the user and
  • routing their call appropriately

Create a main menu

To do this create a new file in your project directory called mainMenu.js and add the following:

require('dotenv-safe').config()
const express = require('express')
const {
    createConfiguration,
    DefaultApi,
    PerclScript,
    GetSpeech,
    Say,
    Redirect,
    Pause
} = require('@freeclimb/sdk')
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

router = express.Router()

let mainMenuErrCount = 0

router.post('/mainMenuPrompt', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new GetSpeech({
                    actionUrl: `${host}/mainMenu`,
                    grammarFile: `${host}/mainMenuGrammar`,
                    grammarType: 'URL',
                    grammarRule: 'option',
                    prompts: [
                        new Say({
                            text:
                                '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'
                        })
                    ]
                })
            ]
        }).build()
    )
})

router.post('/mainMenu', (req, res) => {
    let menuOpts
    const getSpeechResponse = req.body
    const response = getSpeechResponse.recognitionResult
    if (req.body.reason === 'digit') {
        menuOpts = new Map([
            [
                '1',
                {
                    script: 'Redirecting your call to existing orders.',
                    redirect: `${host}/accountNumberPrompt`
                }
            ],
            [
                '2',
                {
                    script: 'Redirecting your call to new orders.',
                    redirect: `${host}/transfer`
                }
            ],
            ['0', { script: 'Redirecting you to an operator', redirect: `${host}/transfer` }]
        ])
    } else if (req.body.reason === 'recognition') {
        menuOpts = new Map([
            [
                'EXISTING',
                {
                    script: 'Redirecting your call to existing orders.',
                    redirect: `${host}/accountNumberPrompt`
                }
            ],
            [
                'NEW',
                {
                    script: 'Redirecting your call to new orders.',
                    redirect: `${host}/transfer`
                }
            ],
            ['OPERATOR', { script: 'Redirecting you to an operator', redirect: `${host}/transfer` }]
        ])
    }

    if ((!response || !menuOpts.get(response)) && mainMenuErrCount < 3) {
        mainMenuErrCount++
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Error, please try again' }),
                    new Redirect({ actionUrl: `${host}/mainMenuPrompt` })
                ]
            }).build()
        )
    } else if (mainMenuErrCount >= 3) {
        mainMenuErrCount = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Max retry limit reached' }),
                    new Pause({ length: 100 }),
                    new Redirect({ actionUrl: `${host}/endCall` })
                ]
            }).build()
        )
    } else {
        mainMenuErrCount = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: menuOpts.get(response).script }),
                    new Redirect({ actionUrl: menuOpts.get(response).redirect })
                ]
            }).build()
        )
    }
})

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

module.exports = router

To make these routes available from our /incomingCall endpoint defined in index.js, add the following content to your index.js file before the /incomingCall endpoint:

const mainMenuRoutes = require('./mainMenu')

app.use('/', mainMenuRoutes)

Create a grammar file

We'll also create a grammar file to be used by the GetSpeech function located in the /mainMenu Prompt endpoint.. 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>

In order to get our main menu up and fully functional, we'll add a route to load our grammar file for use. To do this, add the following to mainMenu.js:

router.get('/mainMenuGrammar', function (req, res) { // load grammar file to be used for speech recognition
    const file = `${__dirname}/mainMenuGrammar.xml`
    res.download(file)
})

📘

To learn more about grammars and creating your own XML files, check out our How to Write Grammars guide.


Step 4: Get an account number

Next we'll create routes to

  • ask the user for an account number and
  • redirect according to their input.

To do this, create a new file in your project directory called accountNumberEntry.js and add the following:

require('dotenv-safe').config()
const express = require('express')
const {
    createConfiguration,
    DefaultApi,
    PerclScript,
    GetSpeech,
    Say,
    Redirect,
    Pause
} = require('@freeclimb/sdk')
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

router = express.Router()
let acctMenuErrCount = 0

router.post('/accountNumberPrompt', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new GetSpeech({
                    actionUrl: `${host}/accountNumber`,
                    grammarFile: 'ANY_DIG',
                    grammarType: 'BUILTIN',
                    prompts: [
                        new Say({ text: 'Please enter or say your six digit account number' })
                    ]
                })
            ]
        }).build()
    )
})

router.post('/accountNumber', (req, res) => {
    const getSpeechResponse = req.body
    const input = getSpeechResponse.recognitionResult
    const response = input ? input.replace(/\s+/g, '') : null
    if ((!response || response.length < 6) && acctMenuErrCount < 2) {
        acctMenuErrCount++
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Error' }),
                    new Pause({ length: 100 }),
                    new Redirect({ actionUrl: `${host}/accountNumberPrompt` })
                ]
            }).build()
        )
    } else if (acctMenuErrCount >= 2) {
        acctMenuErrCount = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({
                        text:
                            'Max retry limit reached, please wait while we connect you to an operator'
                    }),
                    new Pause({ length: 100 }),
                    new Redirect({ actionUrl: `${host}/transfer` })
                ]
            }).build()
        )
    } else {
        acctMenuErrCount = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Redirect({
                        actionUrl: `${host}/confirmAccountNumberPrompt?acct=${response}`
                    })
                ]
            }).build()
        )
    }
})
module.exports = router

To make these routes available from our /incomingCall endpoint defined in index.js, add the following content to your index.js file before the /incomingCall endpoint:

const accountNumberEntryRoutes = require('./accountNumberEntry')

app.use('/', accountNumberEntryRoutes)

Step 5: Confirm the account number

Next we'll create routes to :

  • read the input from the user back to them and
  • ask the to confirm their previous entry

Confirm user input

To do this, create a file in your project directory called accountNumberConfirmation.js and add the following:

require('dotenv-safe').config()
const express = require('express')
const {
    createConfiguration,
    DefaultApi,
    PerclScript,
    GetSpeech,
    Say,
    Redirect,
    Pause
} = require('@freeclimb/sdk')
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

router = express.Router()

let confirmNumberErrCount = 0
let retries = 0

router.post('/confirmAccountNumberPrompt', (req, res) => {
    res.status(200).json(
        new PerclScript({
            commands: [
                new GetSpeech({
                    actionUrl: `${host}/confirmAccountNumber?acct=${req.param('acct')}`,
                    grammarFile: `${host}/accountNumberConfirmationGrammar`,
                    grammarType: 'URL',
                    grammarRule: 'option',
                    prompts: [
                        new Say({
                            text: `You entered ${req.param(
                                'acct'
                            )} is that correct? Press 1 or say yes to confirm your account number or press 2 or say no to try again`
                        })
                    ]
                })
            ]
        }).build()
    )
})

router.post('/confirmAccountNumber', (req, res) => {
    const getSpeechResponse = req.body
    const response = getSpeechResponse.recognitionResult
    let menuOpts
    if (req.body.reason === 'digit') {
        menuOpts = new Map([
            [
                '1',
                {
                    script: 'proceeding to account number lookup.',
                    redirect: `${host}/accountLookup?acct=${req.param('acct')}`
                }
            ],
            [
                '2',
                {
                    script: 'Ok',
                    redirect: `${host}/accountNumberPrompt`
                }
            ],
            ['0', { script: 'Redirecting you to an operator', redirect: `${host}/transfer` }]
        ])
    } else if (req.body.reason === 'recognition') {
        menuOpts = new Map([
            [
                'YES',
                {
                    script: 'proceeding to account number lookup.',
                    redirect: `${host}/accountLookup?acct=${req.param('acct')}`
                }
            ],
            [
                'NO',
                {
                    script: 'Ok',
                    redirect: `${host}/accountNumberPrompt`
                }
            ],
            ['OPERATOR', { script: 'Redirecting you to an operator', redirect: `${host}/transfer` }]
        ])
    }

    if ((!response || !menuOpts.get(response)) && confirmNumberErrCount < 3) {
        confirmNumberErrCount++
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Error' }),
                    new Redirect({
                        actionUrl: `${host}/confirmAccountNumberPrompt?acct=${req.param('acct')}`
                    })
                ]
            }).build()
        )
    } else if (confirmNumberErrCount >= 3 || retries >= 2) {
        confirmNumberErrCount = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Please wait while we connect you to an operator' }),
                    new Pause({ length: 100 }),
                    new Redirect({ actionUrl: `${host}/transfer` })
                ]
            }).build()
        )
    } else {
        confirmNumberErrCount = 0
        if (response === '2' || response === 'NO') {
            retries++ // retries tracked separately from input errors
        } else if (response === '1' || response === 'YES') {
            retries = 0
        }
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: menuOpts.get(response).script }),
                    new Redirect({ actionUrl: menuOpts.get(response).redirect })
                ]
            }).build()
        )
    }
})

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

module.exports = router

To make these routes available from our /incomingCall endpoint defined in index.js, add the following content to your index.js file before the /incomingCall endpoint:

const accountNumberConfirmationRoutes = require('./accountNumberConfirmation')

app.use('/', accountNumberConfirmationRoutes)

Create a grammar file

We'll also define a custom grammar file to validate any speech input from the user in the account number confirmation menu. To do so, create a file called accountNumberConfirmationGrammar.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>yes<tag>$._value = "YES";</tag></item>
                        <item>no<tag>$._value = "NO";</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>

To access the above grammar file during account number confirmation, we'll add an endpoint used by the GetSpeech PerCL command to load our grammar file for use. To do this, add the following to accountNumberConfirmation.js:

router.get('/accountNumberConfirmationGrammar', function (req, res) { // load grammar file to be used for speech recognition
    const file = `${__dirname}/accountNumberConfirmationGrammar.xml`
    res.download(file)
})

Step 6: Create an accounts file for testing

In order to simulate having an accounts service that returns accounts with several different statuses, we'll create a new file for testing purposes. To do this, create a new file called accounts.js in your main directory and add the following:

const accounts = new Map([
    [
        '111222',
        {
            open: true,
            frequentBuyer: true,
            name: 'John Smith',
            mostRecentOrderDate: 'March 30th 2020'
        }
    ],
    [
        '222333',
        {
            open: true,
            frequentBuyer: false,
            name: 'Jane Smith',
            mostRecentOrderDate: 'March 30th 2020'
        }
    ],
    [
        '333444',
        {
            open: false,
            frequentBuyer: true,
            name: 'Sam Smith',
            mostRecentOrderDate: 'March 30th 2020'
        }
    ]
])

module.exports = accounts

Step 7: Look up the account number

Next we'll create a route to take the account number entered and confirmed by the user in steps 4 and 5 and search for it in the data structure we created in step 6. We'll also direct the call based on the status of the account.

To do this create a new file in your project directory called accountLookup.js and add the following content:

require('dotenv-safe').config()
const express = require('express')
const {
    createConfiguration,
    DefaultApi,
    PerclScript,
    GetSpeech,
    Say,
    Redirect,
    Pause
} = require('@freeclimb/sdk')
const accounts = require('./accounts')
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

router = express.Router()
let retries = 0

router.post('/accountLookup', (req, res) => {
    if (!accounts.get(req.param('acct')) && retries < 2) {
        retries++
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({ text: 'Sorry, we couldnt find that account number.' }),
                    new Redirect({ actionUrl: `${host}/accountNumberPrompt` })
                ]
            }).build()
        )
    } else if (retries >= 2) {
        retries = 0
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({
                        text:
                            'Max retry limit reached, please wait while we connect you to an operator'
                    }),
                    new Pause({ length: 100 }),
                    new Redirect({ actionUrl: `${host}/transfer` })
                ]
            }).build()
        )
    } else {
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Redirect({ actionUrl: `${host}/accountRead?acct=${req.param('acct')}` })
                ]
            }).build()
        )
    }
})

module.exports = router

Then, make the routes available by adding the following to your index.js file before the /incomingCall endpoint:

const accountLookupRoutes = require('./accountLookup')

app.use('/', accountLookupRoutes)

Step 8: Read account information back to caller

Finally, we'll add the route for reading information about the user's account back to the caller. To do this, create a new file called accountRead.js and add the following:

require('dotenv-safe').config()
const express = require('express')
const {
    createConfiguration,
    DefaultApi,
    PerclScript,
    GetSpeech,
    Say,
    Redirect,
    Pause
} = require('@freeclimb/sdk')
const accounts = require('./accounts')
const host = process.env.HOST
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = new DefaultApi(createConfiguration({ accountId, apiKey }))

router = express.Router()

router.post('/accountRead', (req, res) => {
    account = accounts.get(req.param('acct'))

    if (account.open) {
        if (account.frequentBuyer) {
            res.status(200).json(
                new PerclScript({
                    commands: [
                        new Say({
                            text:
                                'Welcome back platinum member, please wait while we connect you with a customer service representative.'
                        }),
                        new Pause({ length: 100 }),
                        new Redirect({ actionUrl: `${host}/transfer` })
                    ]
                }).build()
            )
        } else {
            res.status(200).json(
                new PerclScript({
                    commands: [
                        new Say({
                            text: `Welcome back ${account.name}, I've found your most recent order from ${account.mostRecentOrderDate}, please hold while I connect you with a customer service representative. `
                        }),
                        new Pause({ length: 100 }),
                        new Redirect({ actionUrl: `${host}/transfer` })
                    ]
                }).build()
            )
        }
    } else {
        res.status(200).json(
            new PerclScript({
                commands: [
                    new Say({
                        text:
                            'This account appears to be closed please wait while we transfer you to an operator for asistance'
                    }),
                    new Redirect({ actionUrl: `${host}/transfer` })
                ]
            }).build()
        )
    }
})

module.exports = router

Then, make the routes available by adding the following to your index.js file before the /incomingCall endpoint:

const accountReadRoutes = require('./accountRead')

app.use('/', accountReadRoutes)

Step 9: Run your app

To hear your IVR voice-enabled DTMF self service 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 self service application.

Congrats! You can now build your own custom IVR voice-enabled DTMF self service application. 🥳🥳

Or, to use your own pre-recroded audio files instead of text-to-speech, try our Self Service Using Audio Files how-to guide.

For a more advanced IVR how-to guide, try out our Pay by Phone with Voice Calling sample app.

Updated about 1 month ago

Related Content