Setting Up the ICC Application

This section will walk you through how to configure ICC to integrate with Twilio, Genesys PureEngage, and Google Dialogflow.

If you haven't already, please download the ICC Application zip from the software downloads page.

Genesys PureEngage

Properties File Modification

Prior to importing the application, open the import customization file and modify the following fields:

  1. ICC_ENV_USE_TWILIO_TOGGLE: Set to false.
  2. ICC_VAL_IS_CLOUD_SITE: Set to true or false depending on whether the app is being imported on a cloud site. Please note that sentiment analysis will not work for on-premise installations.
  3. ICC_ENV_GEN_BASE_URL: Set to the base URL of the PureEngage server.
  4. ICC_ENV_GEN_API_URL: Set to the URL you would like to use for API calls to Genesys. Depending on your Genesys configuration, this could be the same as the base URL.
  5. ICC Genesys API Credentials: Set the connected system username and password fields to a Genesys admin account.
  6. ICC_VAL_GEN_QUEUE_ID_LIST: Set to the queue IDs that have been set up in Genesys, separating each with a semicolon.
  7. ICC_VAL_GEN_QUEUE_NAME_LIST: Set to the queue names that have been set up in Genesys, separating each with a semicolon.

App Import

After making the appropriate modifications to the properties file, go through the following steps to properly import the app and ensure usability.

  1. Run ICC_Schema_Creation.sql in your Appian environment’s data store*
  2. Import the application using the import customization file
  3. Publish all data stores

*Please note that this SQL file included in the package is optimized for MySQL. Modifications may need to be made for SQL Server and Oracle.

Twilio

Properties File Modification

Prior to importing the application, open the import customization file and modify the following fields:

  1. ICC_ENV_USE_TWILIO_TOGGLE: Set to true.
  2. ICC_VAL_IS_CLOUD_SITE: Set to true or false depending on whether the app is being imported on a cloud site. Please note that sentiment analysis will not work for on-premise installations.
  3. ICC_VAL_AI_FEATURE_TOGGLE: Set to true or false depending on whether you want to use Dialogflow.
  4. ICC_VAL_CURRENT_ENVIRONMENT_URL: Update the value to the site you are importing the app into. Must be in the format of subdomain.appiancloud.com.
  5. ICC_VAL_TWIL_SUBACCOUNT_NAME: Update the value to something that will identify this environment in the Twilio console.
  6. ICC_VAL_ISO3166_COUNTRY_TO_FIND_PHONE_NUMBER: Set the value to the 2 character country code in which you want to purchase a phone number. Please refer to Twilio's list of supported countries.
    • Please note there are certain cases when needing to purchase an international phone number where it may be necessary to perform actions within the Twilio Console.

If you have an already existing Twilio subaccount that you would like the imported app to use, further modifications to parameters in the properties file can be made.

App Import

After making the appropriate modifications to the properties file, go through the following steps to properly import the app and ensure usability.

  1. Run ICC_Schema_Creation.sql in your Appian environment’s data store*
  2. Import the application using the import customization file
  3. Publish all data stores

*Please note that this SQL file included in the package is optimized for MySQL. Modifications may need to be made for other database management systems, such as SQL Server and Oracle.

Creating the Service Account and API Key

An Appian service account must be created to authenticate requests to Appian. An API key will be used for the authentication process and this service account will be the means by which Twilio and Google Dialogflow call Appian web APIs. The service account is not meant to be used as an agent. Follow the steps below to properly set up the service account.

  1. Create a new service account with the username icc-service-account
  2. Create an API key with the description Twilio to use in the Initialize Twilio Configuration Action section
  3. Create an API key with the description Google Dialogflow to use in the Google Dialogflow API Key Configuration section if needed
  4. Add the new service account to the ICC All Users group

Initialize Twilio Configuration Action

The Initialize Twilio Configuration action in the ICC application is an easy way to set up all of the necessary objects and connections with Twilio to get up and running quickly. This should be done if you want to set up a Twilio subaccount from scratch.

If you would like to change the default names of any of these objects that will be created through the setup, you can modify the constants referred to in this document.

Once the service account is properly set up, the configuration is ready to be run. This section will walk you through each step of the configuration process and the Twilio objects that are created or configured at each step.

Specify Twilio Account

The first step of the configuration is to specify the parent-level Twilio account that will be used for the rest of the setup process.

You can find the Account SID and Auth Token on the main page of your Twilio account.

/ICC specify twilio account

Update Connected Systems For Twilio Subaccount

Appian will now display the newly created subaccount credentials, which you will need to store in a connected system. It is highly recommended that you also store these credentials outside of Appian in a secure manner.

  1. Navigate to the ICC Twilio Subaccount Credentials connected system.
  2. In the following fields, copy the credentials from the newly created subaccount.
    • Username - Account SID
    • Password - Authentication Token

    twilio_subaccount_credentials.png

Once these values have been correctly entered into the connected system, navigate back to the setup and proceed to the next page.

Specify Appian Service Account

In this step, you must copy the Twilio API key created for the service account in the creating service account section to the Twilio configuration. This will provide Twilio with the authenication to communicate to this Appian instance.

ICC_service_account_API_cred.png

Once the credential are properly entered and the user clicks Create Twilio Objects, the following Twilio objects are created. As mentioned previously, you can modify the constants referred to below to change the default name of any of the objects that are created.

  • TwiML App for voice and messaging (constant name referenced: ICC_VAL_TWIL_TWIML_APPLICATION_NAME)
  • Workspace (constant name referenced: ICC_VAL_TWIL_WORKSPACE_NAME)
  • Task Queue #1 (constant name referenced: ICC_VAL_TWIL_TASKQUEUE_NAME_ONE)
  • Task Queue #2 (constant name referenced: ICC_VAL_TWIL_TASKQUEUE_NAME_TWO)
  • Workflow (constant name referenced: ICC_VAL_TWIL_WORKFLOW_NAME)
  • Chat Service (constant name referenced: ICC_VAL_TWIL_CHAT_SERVICE_NAME)
  • Phone Number Purchase (will always purchase the next phone number available in the country specified)
    • When purchasing a non-US number, the purchase may fail. If it fails, you will receive an error on the review screen. See the Review section for more information.

Add Workers

Following creation of these objects, you can now create workers in Twilio, which need to be associated with Appian users. These workers can also now be assigned queues in which to receive calls and chats.

When clicking Next, the following occurs with the users specified on this screen:

  • Added to associated Appian groups for security purposes
  • Created as workers in Twilio (except for Managers)
  • Added to the associated queues in Twilio (except for Managers)

Only Agents are created as Twilio workers since they require integration with Twilio for telephony capabilities. Any users added as Managers are not created as workers in Twilio, but rather just placed in the managers group in Appian for permissions to view the Manager Dashboard.

Following completion of this step, the Appian users which are associated with Twilio workers can be found in the ICC_WORKER table.

Update Connected System for Twilio Credentials

At this point, the setup has created all of the necessary objects in Twilio for ICC. However, the ICC Twilio Credentials connected system must be manually populated with these values for the Twilio component to properly communicate with Twilio. Please note that for security reasons, the setup process does NOT persist these values as constants or in the process model. It is highly recommended that you store these credentials outside of Appian in a secure manner. If you navigate away from this page prior to storing these credentials, you can navigate to your Twilio subaccount to retrieve them.

  1. On a separate tab, open Appian Designer.
  2. Navigate to the ICC Twilio Credentials connected system.
  3. Enter in the values for the following fields.
    • Account SID
    • Authentication Token
    • API Key SID
    • API Key Secret
    • TwiML App SID
    • Workspace SID
    • Chat Service SID
  4. Click Test Connection to ensure the credentials are valid.

    cst_cs_credentials.png

Review

The Review screen will allow you to review all of the Twilio objects and IDs that were created, without exposing any sensitive information. You can also find this information in the Twilio Identifiers report.

If any part of the configuration process failed, you will receive an error on this screen.

If you are purchasing a non-US phone number and it failed to purchase, after you complete this section, follow the instructions in the Manual International Phone Number Purchase section. If a phone number appears in the review page, then the purchase was successful.

Manual International Phone Number Purchase

This section explains how to purchase a non-US phone number from the Twilio console. Note that this is only necessary if you see an error message in the phone number field on the review screen in the section above. If there is an error displayed, then it means that additional verifications are needed due to Twilio phone number regulations in your country.

  1. Navigate to the Twilio Console and log in.
  2. Navigate to your Twilio project.
  3. Click Settings > Subaccounts.
  4. On the subaccount that was just created, click View Subaccount.
    • If unsure which subaccount this is, you can reference the Subaccount SID on the Twilio Identifiers report.
  5. Click All Products and Services twilio_dots_icon_small.png and select Phone Numbers.
  6. Click Regulatory Compliance on the left menu.
  7. Click Create an Identity.

    create_an_identity.png

  8. Select your country and follow the prompts to create a business identity.
    • Note that it will take Twilio up to 48 hours to verify the identity.
  9. Navigate to the Addresses page under Regulatory Compliance.
  10. Click Add new Address and enter in a corporate address.

    Note that the following steps require a verified identity and a validated address.

  11. Navigate to Manage Numbers and click on the + icon to buy a new number.

    twilio_buy_number.png

  12. Follow the prompts to search for and purchase a phone number in your desired country.
    • Note that a number without voice or SMS capabilities will fail to take calls or SMS interactions within ICC.
    • Some countries will require a verified identity within that specific country, while others accept any verified identity.

Testing Connection and Troubleshooting

If you would like to test your configuration to make sure it is set up properly, follow the steps below.

  1. Log in as a user that was added to the queues
  2. Open the Twilio Tester report
  3. Set the Twilio component to Calls or SMS
  4. Call/text the number displayed on the screen

If the Twilio component dynamically updates, you are properly configured! If this test was not successful, please see below for some possible troubleshooting steps.

  • If the Twilio component is not visible, make sure your user was added as a worker. Run the Update Twilio Workers action to add more workers.
  • If the Twilio component still does not load, make sure the subaccount and API key credentials are properly stored in the connected systems.
  • If the call was not routed to your user, log into Twilio to make sure the call was routed to a queue in which your worker is available and that the call was not picked up by another worker.
  • If the Twilio component does not update, make sure your browser is set up to allow access to the microphone.
  • If transfers and/or call recordings are not working, please make sure that Agent Conference is enabled on the parent Twilio account

Google Dialogflow API Key Configuration

Additional steps are needed to configure the previously set up service account and API Key with Google Dialogflow if your ICC site uses Google Dialogflow. Perform the following steps to complete the Google Dialogflow initialization.

  1. As an Appian Admin user, open the ICC_AI DialogFlow API Credentials connected system and authorize access to Google Dialogflow using the same Google account
  2. Return to the Dialogflow console, open the agent created earlier, and select Fullfillment
  3. Set the URL to the endpoint of the ICC_WS_AI_GCC_Fulfillment web API: https://<your Appian ICC site>/suite/webapi/fulfillment
  4. Set the Header item key value to Appian-API-Key and copy the API key created for Google Dialogflow
FEEDBACK