Building a Basic IVR System with MessageBird
During a voice call, the caller can press keys that trigger so-called DTMF tones. By capturing this user input and responding accordingly, you can build sophisticated IVR (Interactive Voice Response) systems.
In this MessageBird Tutorial you’ll learn the basics of support call centers and build a sophisticated IVR system powered by the MessageBird API. We'll cover a basic support call center scenario, where the caller is greeted with a message and asked to press the key for the department they want to speak with; after pressing the corresponding key, the call is transferred to the department’s phone number.
Step 1: Setting a call flow
We start with setting a call flow that defines steps for greeting the caller, pausing for 10 seconds, and capture and handle the keys pressed during the message or the pause.
For this scenario, we'll have to introduce conditional logic to our call flow. After capturing user input, we want to execute specific steps only if the condition we set is evaluated as "true".
The call flow looks like this:
<?xml version="1.0" encoding="UTF-8"?><Say language="en-US" voice="female" onKeypressVar="department" onKeypressGoto="transferToDepartment">Welcome to MessageBird. Press 1 for sales, or 2 for support.</Say><Pause length="10s" onKeypressVar="department" onKeypressGoto="transferToDepartment"/><Say language="en-US" voice="female">You didn't press anything. Good bye!</Say><Hangup/><If id="transferToDepartment" condition="department == 1"><Say language="en-US" voice="female">You're now transferred to the sales department.</Say><Transfer destination="31971111111"/><Hangup/></If><If condition="department == 2"><Say language="en-US" voice="female">You're now transferred to the support department.</Say><Transfer destination="31972222222"/><Hangup/></If><Say language="en-US" voice="female">You pressed something, but it wasn't 1 or 2. Good bye!</Say>
During the greeting and the pause, using the onKeypressVar parameter we store the key that was pressed in a variable called department. Also, we define an onKeypressGoto parameter that causes the call flow to skip to the step with the corresponding id value if a key is pressed.
The If tag is used for evaluating if a step should be executed. The value of the condition parameter is of the form {variable} {operator} {value}. In the XML call flow above we use department == 1. If the user pressed 1 before, this condition would evaluate as "true", and the nested steps will be executed. If not, the call flow will proceed to the next tag in the call flow. You can define multiple If tags which will be parsed in sequence.
The cURL command to create the above call flow through the Voice API looks like this:
curl -X "PUT" "https://voice.messagebird.com/numbers/:your_number/call-flow" \-H "Authorization: AccessKey :your_access_key:" \-H "Content-Type: application/xml" \-d $'<?xml version="1.0" encoding="UTF-8"?><Say language="en-US" voice="female" onKeypressVar="department" onKeypressGoto="transferToDepartment">Welcome to MessageBird. Press 1 for sales, or 2 for support.</Say><Pause length="10s" onKeypressVar="department" onKeypressGoto="transferToDepartment"/><Say language="en-US" voice="female">You didn't press anything. Good bye!</Say><Hangup/><If id="transferToDepartment" condition="department == 1"><Say language="en-US" voice="female">You're now transferred to the sales department.</Say><Transfer destination="31971111111"/><Hangup/></If><If condition="department == 2"><Say language="en-US" voice="female">You're now transferred to the support department.</Say><Transfer destination="31972222222"/><Hangup/></If><Say language="en-US" voice="female">You pressed something, but it wasn't 1 or 2. Good bye!</Say>'
Step 2: Assign a number to the call flow
To have the call flow executed when a number you own is called, you first need to assign that number to the call flow. The endpoint to do this is:
POST https://voice.messagebird.com/call-flows/:call_flow_id:/numbers
The following is an example with cURL:
curl -X "POST" "http://voice.messagebird.com/call-flows/:call_flow_id/numbers" \-H "Authorization: AccessKey :your_access_key:" \-d $'{"numbers": ["31612345678"]}'
The call_flow_id parameter is the ID of the call flow created in step 1. The string value in the numbers array is the E.164 formatted number you want to assign. Keep in mind that this must be a number you previously purchased. Buying a MessageBird number is quite easy, in this Help Center article we explain to you how to do it.
Awesome! After making this request, the call flow will be executed for every incoming call to the number.
Step 3: Testing the call flow
Dial the number you used in step 2. You should hear the greeting message and a pause of 10 seconds. If you press 1 or 2 during the greeting or the pause, you should hear a message stating you're now being transferred to the applicable department. If you don't press a key during the greeting or the pause, you should hear a message saying "You didn't press anything. Goodbye!". If you pressed a key that wasn't 1 or 2, you should hear a message that says just that.
By default, steps are sequentially executed in order, but as you can see by looking at the XML call flow and the description above, you can alter the flow of step execution by skipping around the call flow based on key presses and by using If conditions to evaluate them.
Keep in mind
This tutorial uses a fairly simple static call flow; the outcome of the keypress is always the same for every caller. You can also configure a "fetch" call flow that queries your web service via HTTP to obtain a call flow. This approach is outlined in the ‘Dynamic call flows’ section of our Voice Calling API documentation.
By using a "fetch" call flow, you can alter the behavior of your call flow based on dynamic values, for example, the number that's calling or the time of day. Because your web service parses the incoming request, it can programmatically decide and assemble the call flow to return.
Nice work! 🎉
You just learned how to build a basic IVR system!
Start building!
Want to build something similar but not quite sure how to get started? Feel free to let us know at support@messagebird.com; we'd love to help!
