Skip to main content

Twilio Integration


This documentation page is still being written.

The playground supports direct integration with Twilio Voice.


To connect your playground bot to Twilio Voice, use the following webhook URL:


The method should be set to POST.

Voice configuration

To configure the voice and the language, you must set the following context variables in your data.yml file:

voice: "Polly.Matthew-Neural"
lang: "en-US"

Check the supported voices here.


The integration will generate two events in the context of the conversation:

  1. new call: when the call is initiated.
  2. call ended: when the call has finished.

You can use the new call event to trigger the welcome behavior for your bot:

define flow new call
"""When a new call is initiated, we treat it as if the user says hi."""
event new call
infer user express greeting

This behavior is already included in the co/welcome model.

In the case of the call ended event, bear in mind that the call has already ended, so, any additional bot messages, after the event, will not be received.

Speech To Text

When the bot needs to wait for user input, it will use TwiML Gather. You can override supported Gather attributes by specifying the twilio_config parameter on the last bot utterance before waiting for input. The supported attributes are:

AttributeDescriptionDefault value
inputdtmf, speech, dtmf speechdtmf speech
enhancedWhether to use the enhanced model.true
speechTimeoutTime to wait before stopping to listen (in seconds).auto
speechModeldefault, numbers_and_commands, phone_callphone_call
languageThe language and locale.en-US
hitsComma separated list of words or phrases.""

For example, to optimize the model for numbers input, you can use the following:

bot "What is your PIN?"
set $twilio_config to
speechModel: "numbers_and_commands"
speechTimeout: 5
hints: "1234, the PIN is 0000, 0, 1, 2, 3"

You can reuse a specific twilio configuration by storing it in a global context variable.

speechModel: "numbers_and_commands"
speechTimeout: 5
hints: "1234, the PIN is 0000, 0, 1, 2, 3"
bot "What is your PIN?"
set $twilio_config = $twilio_pin_input