Modifying Virtual Agent and IVR

This page explains setting up Virtual Agent and IVR using the Twilio integration. For related Genesys information, please refer to their PureEngage documentation.

When deciding between using IVR menus or a virtual agents, it is important to consider the experience you want your customers to have. Virtual agents lends itself well to contact centers that are geared towards self-service. IVR menus provide intelligent routing and is more appropriate when wanting to connect to correct agent quickly.

Please note that ICC requires the use of Google Dialogflow for full virtual agent capabilities.

Virtual Agent (Using Dialogflow)

If Dialogflow is properly set up, switch the AI feature toggle constant in the ICC App to "True" to route the virtual agent to Dialogflow.


A virtual agent acts as an agent for an interaction prompting the customer for information and providing appropriate responses. See Google's virtual agent documentation for more information. To expand the capabilities of the existing ICC virtual agent, you must first create a new intent then create any new Appian processes to trigger from the intent.

Creating an Intent

Much of the virtual agent interaction is driven by Dialogflow intents.

To create a new intent in Dialogflow, follow the steps below.

  1. Click on the + next to Intents in the left menu.
  2. Add the name "name" into the Intent name text field.
  3. In the Training Phrases section, click on the text field and enter the phrases a customer would give to initiate this intent, pressing enter after each entry.
    • For example:
      • What is your name?
      • Do you have a name?
      • name
  4. In the Responses section, click on the text field and enter the appropriate response
  5. Click the Save button

Modifying ICC Objects

Now that you have new intents created in Dialogflow, Appian must be properly configured to provide the right reply to these intents. The steps below walk through how to configure certain objects within the ICC Application for intents received from Dialogflow.

  1. In the ICC app, open the ICC Artificial Intelligence Module. You will need to create/edit a few new objects
  2. Open the expression rule ICC_UT_AI_fulfillReply
    • Add a new logic statement to this rule to handle the name of your new intent
      • Use ri!intent.display= (your new intent display name)
    • Add any conditions your new intent requires
    • Run any processes required for the new intent
      • Ensure you add the “ICC AI Log Virtual Agent Interaction” process model as a subprocess to log any virtual agent interactions.
  3. Create any new expression rules to calculate/decide on actions based on your new intent
    • Use ICC_UT_AI_handleCCInfoInquiry as an example - This rule displays information for the customer based on the intent parameters passed in be it credit limit, balance, or APR

Interactive Voice Response

Appian and Twilio can be used together to configure IVR menus. This method relies on Twilio's native speech recognition technology with responses and options configured in Appian. This provides an overview of setting up this approach both in Twilio as well as Appian.

Twilio Voice Request

Twilio allows for custom configurations for each phone number to determine how to handle calls. To view this, go into the Twilio console and navigate to the following:

All Products and Services -> Phone Numbers -> (select phone number) -> "CONFIGURE WITH"

There are a number of possible configuration options, but two are of particular interest.

  1. TwiML App - This is the handler configured by default for the ICC App. Notice that the "Appian ICC App" has been chosen here, as it was set up through the initial configuration. When Twilio receives a call, it will make a request to the app which must reply in TwiML (Twilio Markup Language). The TwiML language can be used to instruct Twilio to read options aloud to the caller, gather responses, create and add attributes to tasks, etc. This can be used to configure an IVR system or Virtual Private Assistant (VPA) through Appian.
  2. Studio - This is a visual tool provided by Twilio currently available as a Beta. It is similar to a visual workflow designer and can be used to graphically program IVR behavior. Since it is currently in Beta, it was not considered for use in the ICC App, but may be of interest to ICC developers in the future.


The remainder of this section will focus on setting up IVR through TwiML. Twilio will use the request URL set up for voice in the TwiML App to interact with the caller. You can find more details about the TwiML app by first navigating to the appropriate subaccount in Twilio and then navigating to the following:

All Products and Services -> Programmable Voice -> TwiML -> TwiML Apps -> (name of your app) -> Voice -> Request URL

Notice that if you configured your environment through the "Initialize Twilio Configuration" action, this has already been set up for you. The Web API in Appian that Twilio calls is "ICC_WS_TWIL_voiceEndpoint"

/ICC IVR_object

The Web API shown above uses the "ICC_WS_TWIL_IVR_voiceEndpointHandler" rule to construct the TwiML response to Twilio. This handler currently has functionality which retrieves configuration details from the ICC App database, specifically the "ICC_IVR_MENU" and "ICC_IVR_MENU_OPTION" tables, and translates them to appropriate TwiML. Further details on the TwiML language can be found in Twilio.

The following section will describe some of the IVR options that come out of the box and provide a walk-through of one of the options.

ICC App Pre-Configured IVR Menus

The ICC App comes with the following pre-configured IVR menus available. These pre-configured options were intended to be a representative sample of different behaviors that customers may want in real life, as well as menus that could be used for demos.

Silent Enqueue Menu

The caller is immediately transferred to the default queue.

Enqueue Menu

A welcome message is read to the caller and then they are transferred immediately to the default queue.

Record Menu

The caller is requested to record a brief message, which is then added as part of the Twilio task attributes. This information is then made available on the Agent Dashboard.

Caller Identity Verification

If the caller's phone number is recognized, an attempt is made to verify the caller's identity. If the caller successfully verifies their date of birth and last four digits of their SSN, then the caller verification is skipped from the Agent Dashboard.

Traditional IVR Menu

A traditional branching menu where the user is prompted with multiple choices to be placed in different queues.

As an Appian administrator, you can select the active IVR menu for the pre-purchased phone number through the "Update IVR Menu" action. The various sample menus are populated in the "ICC_IVR_MENU" table and the handler described above will respond with the menu whose ID is stored in the "ICC_VAL_IVR_ACTIVE_MENU_ID" constant.

As an Appian developer, if you want to add additional menus, or extend the current menus, you would primarily need to update the "ICC_IVR_MENU" or "ICC_IVR_MENU_OPTIONS" table. Please see below for additional information on these tables.

    • Each row represents an IVR menu
    • "Update IVR Menu" action displays the name and description contained in this table
    • Each row specifies optional welcome text that is read aloud to the caller when they initially connect
      • The welcome_prompt_audio field is not currently in use, but could be extended in the future to provide a link to an audio file played to the caller rather than relying on text to speech
    • Each row represents an individual option on an IVR Menu
      • Menus could have only a single option or multiple nested options
      • Each option either gathers information from the caller or enqueue a new task
    • Each row is only a part of a single menu, and may only have a single parent row/option
    • If a menu is to eventually lead to a task for an Agent, it should have at least one row representing an option with an enqueue flag set to true

Handler Walkthrough

This section describes how the “ICC_WS_TWIL_IVR_voiceEndpointHandler” rule operates.

  1. The handler will retrieve the Root Menu options for the current menu from the "ICC_IVR_MENU_OPTION" table (i.e., all the rows in this menu without a Parent Option ID).
  2. It will concatenate all the text of those options in the Prompt column and create a TwiML response which then reads it aloud to the caller, if any.
    • If the matched menu option has the enqueue flag set to true, a task will be enqueued with the attributes specified in the enqueue task attribute JSON string. This is essentially a terminal branch of the IVR Menu tree.
    • If the menu option is not a terminal option, but instead requires input from the user. The TwiML will also contain:
      • A Gather verb which waits for the caller to reply.
      • A Callback URL that Twilio will use when it has gathered the response.
  3. When the subsequent call is made to Appian, the handler attempts to use the pathSegments and the input gathered from the caller to match the appropriate menu option.
    • Otherwise, the handler will read the attributes of the matched menu option, find its children, and read those aloud to the caller. It will continue to recurse down the menu tree until eventually finding an option with the Enqueue Flag set.
  4. If at any point the user chooses an invalid option, the caller is told that they will be transferred to an Agent. Menu looping or error handling could be added, but it is not included in the sample menus.

As an example, we will now walk through the "Caller Identity Verification" IVR menu option.

If the "Caller Identity Verification" menu has been selected as the active IVR option, the "isVerificationMenuOption" local variable in the "ICC_WS_TWIL_IVR_voiceEndpointHandler" will be set to true. This is used to let the handler know that it will be matching data to the Appian ICC contact database, rather than just traversing menu options.

  • The handler will use the phone number included in the incoming http request formData.From to look up the contact.
  • The field specified in the verificationField column on the menu option will be retrieved from the Contact CDT and will be compared to the input gathered from the user before traversing further down the tree.

This will start the process with the ICC_UT_IVR_validateCallerIdentity rule. The business logic will then occur as follows.

  1. The root menu options for the menu are retrieved from the ICC_IVR_MENU_OPTION table, rows ‘id:13’ and ‘id:14’ and the TwiML is constructed which uses the prompt columns to be read aloud to the caller. Twilio uses the TwiML to interact with the caller and gather a response and then callback to Appian.
  2. Depending upon the user input a few things could happen:
    • If an invalid response is given, the task is enqueued immediately
    • If the user presses 2, the subsequent callback to Appian will match row ‘id:14’ and because this row has the enqueue flag set, the call will be enqueued immediately with the specified attributes on this row, {"identity_verification":"rejected"}. The agent dashboard can then handle the identity verification of the caller.
    • If the user presses 1, the subsequent callback to Appian will match row ‘id:13’ using the pathSegments and input provided by the caller. Since this row is not an enqueue option, the child options will be gathered from this table. The logic proceeds on as follows in the next step.
  3. In this case, there is only one child, row ‘id:15’. The prompt on row ‘id:15’ is read aloud to the user, “Please provide the last four digits of your Social..” and the TwiML gathers the response. Twilio returns the gathered input to the provided callBack URL to Appian.
  4. When the callback happens, Appian recognizes that this is menu option ‘id:15’. The handler gathers the verification field value as specified on this row, ssn, from the Contact CDT for the caller. If the gathered input matches, Appian recurses further down the menu, since this option does not have the enqueue flag set.
  5. There is only one child, row ‘id:16’. The prompt on row ‘id:16’ is read aloud to the user, “Please provide your birthdate in the format of fou…” and the TwiML gathers the response. Twilio returns the gathered input to the provided callBack URL to Appian.
  6. When the callback happens, Appian recognizes that this is menu option ‘id:16’. The handler gathers the verification field value as specified on this row, birthdateVerificationFormatted, from the Contact CDT for the caller. If the gathered input matches, Appian will enqueue the task for an Agent, since the enqueueFlag is set for this row. The enqueueTaskAttributesJson are included in the task, most importantly an identity_verification: attribute.
  7. When the agent dashboard acquires this Twilio task, it recognizes the {"identity_verification":"passed"} attribute and skips the “workflow” of asking the Agent to verify the caller identity.

Additional Configuration Details

Some additional configuration options that may be of interest to an Appian Developer are as follows:

  • ICC_VAL_TWIL_IVR_LANGUAGE - This option essentially chooses the ‘accent’ used by the Twilio voice which interacts with an incoming caller. It does not translate the actual words, but should be set to a value that pairs correctly with the actual text configured in the ICC_IVR_MENU_OPTION table. In other words, if your menu has French vocabulary, set this constant to fr-FR so that the virtual operator reads those words aloud as a French speaker would. The available options are specified in the description field of this constant.
  • ICC_VAL_TWIL_IVR_PROFANITY_FILTER_FLAG - If set to true, any text gathered by Twilio in an IVR menu that contains profanity will be replaced with * before being added as a Task Attribute and routed to the Agent.
  • ICC_VAL_TWIL_ENABLE_WEB_API_LOGGING - If set to true, incoming requests from the TwiML application will be stored in the ICC_WEB_API_REQUESTS table. This can be used In conjunction with the Twilio Console Logging to debug issues while developing IVR menus.
    • All Products and Services -> Task Router -> Errors & Warning