Setting up Twilio SMS MMS

Overview

The Symbee Connect Twilio SMS integration allows you to fully service two-way SMS conversations fronted by your Twilio Account within your Omnichannel Symbee Connect enabled Amazon Connect instance. The following functionality is provided:

  • Route inbound Twilio SMS messages into your Symbee Connect instance, and queue them to the next available, appropriately skilled agent for servicing in a two-way SMS conversation:
  • The first new SMS message received from a customer’s phone number begins an SMS Conversation within Symbee Connect. After the conversation is delivered to an agent, all subsequent SMS messages sent between the agent and customer are part of that Conversation, with the conversation concluding when the agent ends the dialogue and wraps the associated interaction.
  • Symbee Connect Agents can initiate new Outbound SMS conversations with a customer:
  • An outbound SMS conversation can be simply initiated as a New Outbound interaction within the Symbee Connect Agent UI.
  • Alternatively, if the Agent already has a phone call in progress with a customer (and the customer is on a mobile phone), the Agent can use the Symbee Connect Quick SMS feature to begin an outbound two-way SMS conversation with the same customer while talking with them, allowing the Agent to:
    • Send related information via SMS messages to the customer (Examples: new Passwords, a Contract or Ticket number, Address and navigation directions, or links to product or support documentation).
    • Or to request the Customer to provide 2-factor authentication responses via SMS for additional security.
  • Inbound Twilio SMS Messages (conversations) can be optionally configured within Symbee Connect to be first routed via Amazon Connect Chat, therefore starting in an Amazon Connect Contact Flow for self service and Lex Bot integration, then subsequently queued to a Symbee Connect Agent for further servicing as needed.
  • All the same chat-based Symbee Connect functionality like Auto-Text libraries, and Work Codes / Dispositions, and Audible Chat Notifications are available for use in the Twilio SMS Conversations, just like any other Chat conversation serviced with Symbee Connect.

The following step by step guides you through setting up a Twilio SMS integration. The instructions differ depending on the Delivery Provider you are going to use for your Twilio SMS conversations. See Selecting the Chat Delivery Provider for further details on this.

Setting up Twilio SMS using Delivery Provider: Amazon

Important Note: The following steps are only required if you are going to be using Amazon as your Delivery Provider.

Prerequisites

Confirm CCP-V2 is being used

In order to receive Amazon Connect Chats (chat/SMS), you need to be running CCP v2.

  1. Log into the Symbee Connect Administration Portal.
  2. Click the on the main Function menu in the top navigation bar and then click on Amazon Connect Integration under Company Environment Configuration

  3. Confirm your Amazon Connect URL ends with /ccp-v2.

  4. If it doesn’t, modify your URL to end with /ccp-v2 - this is required to receive Amazon Connect Chats (Chat/SMS).


Download the Amazon Connect Chat Integration CloudFormation

Note that this step only needs to be performed before setting up your first new Amazon Delivered Chat channel for a Symbee Connect Environment.

If this is the first Symbee Connect CloudFormation you have run, you will need to run the Integrations CloudFormation first. For step by step instructions and further information about CloudFormations click here.

  1. Log into the Symbee Connect Administration Portal.
  2. If you have more than one Environment configured within your Company in Symbee Connect, make sure you have the appropriate one selected. This can be found on the Navigation bar to the left of the Function menu.
  3. Then click on the main Function menu in the top navigation bar, and click on Feature Integrations (CloudFormations) in the Company Environment Configuration section.
  4. From the Feature Integrations (AWS CloudFormations) page, scroll down and locate the Amazon Connect Chat Integration CloudFormation, and click the download link to download and save the CloudFormation script.
  5. You will be prompted with a Save As dialog screen. Save the file locally to your PC for use in the following steps.


Run Amazon Connect Chat Integration CloudFormation in your AWS Account

  1. Log Into your AWS Management Console.
  2. Make sure you are in the correct AWS region for where you want to deploy (top right of the Navigation bar) – the same region as your Amazon Connect instance.
  3. Navigate to the CloudFormation console (under Management and Governance, on the Services menu).

  4. From the CloudFormations console, select Stacks in the left-hand navigation bar, and select Create Stack and select With new resources (standard) from the dropdown box.

  5. You will be presented the “Create Stack” view for creating/deploying a new CloudFormation script (known as a stack):

  6. Under the Prepare Template section, select Template is Ready

  7. Under Specify Template, select Upload a template file

  8. Under Upload a template file, click Choose File

  9. In the resulting file selector, find and upload the file you saved from above.

  10. Click Next at the bottom

  1. In the Specify Stack Details screen, complete the fields as follows:
  2. Stack Name: Enter a name appropriately. We suggest using your Symbee Connect Environment (e.g. dev, prod, etc.) in the name for better organization, in case you have CloudFormations for multiple Symbee Connect Environments Connect being deployed into the same AWS Account.
    For example:
    companyalias-environment-amazonchat
  3. Click Next
  4. On the next Configure stack options screen, accept all the defaults, and click Next.
  5. On the next Review testing screen, scroll to the bottom Capabilities section, check the “I acknowledge that AWS CloudFormation might create IAM resources with custom names.” Checkbox, and finally click Create Stack.


Build Amazon Connect Chat Queue and Contact Flow

You will need to setup an Amazon Connect Contact Flow to receive and handle your chat and respective Chat Queue in Amazon Connect and assign it to a Routing Profile, if you are routing your SMS to an agent.



Setting up Twilio SMS using Delivery Provider: Symbee Connect

Important Note: The following steps are only required if you are going to be using Symbee as your Delivery Provider.

Prerequisites

Configure Skill Queue

  • You will need to set up a specific Skill Queue for Twilio SMS. Make sure you when you add the new skill queue, you select SMS Social in the Queue Type.
  • You will need to assign the new Twilio SMS queue to selected agents.

Click here for our Queues and Skill Assignment section in our Administration Guide.


Configure Hours of Operation

This is an optional step but if you would like Twilio SMS to be operational at certain times of the day, you will need to set up Hours of Operation.

For our step by step guide for setting up Hours of Operation, click here.


Configure Programmable SMS within Twilio

The steps in this section walk you through the setup of a new Twilio Project within your Twilio Account, creating a new Messaging Service within that project and assigning or buying a Twilio number for SMS use.

Note: If you already have an existing Twilio Account, Project and Twilio phone numbers acquired (or are porting them), many of the steps in this section will be redundant. If this is the case, the key steps for integration with your Symbee Connect environment are to:

  • Have a Messaging Service configured for Chat Bot/Interactive 2-Way with your required Phone Numbers assigned to the service, with its Web Hook configured as per section Create or Configure a Programmable SMS Messaging Service Step 13 below.
  • Obtain your Twilio Project’s ACCOUNT SID and AUTH TOKEN codes from the Project Dashboard (click here) for input into your Symbee Connect environment’s SMS Configuration.

Create or Access your Twilio Account and Project

  1. Log into your Twilio Account at https://www.twilio.com/
    If you don’t already have a Twilio Account, click the Sign-up button on the Twilio website to register for your new Twilio Account. Create your new account and then sign in.
  2. In your Twilio Account, if you already have an existing Project you wish to use, you can skip this step. Otherwise select Create New Project from the top-left drop-down menu.
    Notes:
    • If this is your first time logging in, you will automatically be put into the Create New Project flow.
    • Any New Project will begin as a Trial. Once created, there are options in Twilio you can use to Upgrade the project as needed.
  3. Provide a name for your new project, and click Verify.
  4. Twilio walks you through 2-factor authentication to confirm the Project/Account creation, depending on how you setup your account. Once the authentication is complete, you will be asked a series of questions you can answer them based on your specific needs. You can also click the Skip to Dashboard button to bypass.

Create or Configure a Programmable SMS Messaging Service

In general, SMS Numbers and functionality with Twilio Programmable SMS are organized into what is referred to as Messaging Services. A Messaging Service can be the home to multiple related SMS Numbers.

  1. With an existing project selected (or newly created) and the Project Dashboard displaying, from the left side navigation Bar, click the Ellipsis button and then Programmable SMS.



  2. From the Programmable SMS Menu on the left side navigation bar, select SMS, then Messaging Services.
  3. Either select one of your existing Messaging Services with the numbers you already own, or Create New Messaging Service.
  4. Give your new Messaging Service an appropriate name and select the Chat Bot/Interactive 2-Way from the Use Case dropdown box.



  5. Once your new Messaging Service is created, select it from your list of Messaging Services on the left side navigation menu.
  6. From the sub-menu, select Numbers to either buy or provision new Twilio SMS numbers for your Messaging Service.
    Note: Another option is to select Add an existing number from the Numbers screen, to assign a phone number previously purchased within your Twilio project, for use with this new Messaging Service. If you will be using this option, skip the next step.
  7. From the Buy a Number screen, select the required Country, and for the Capabilities checkboxes, make sure to at least check SMS (you can also check MMS if required, and may also want to check Voice depending on your other Twilio needs). Then click Search and Buy the numbers you want to use.
  8. On the Managed Numbers page, either add additional optional configuration or cancel out of that page.
  9. Return to the Messaging Services page by going to All Products and Services > Programmable SMS > SMS and click on your newly created Messaging Service.
  10. If this is the first SMS number you are provisioning, you’ll be prompted to Add an Existing Number.
  11. Select the checkbox for the number you wish to add and click Add Selected.
  12. With at least one Phone Number now configured in your Messaging Service, select the Settings sub-menu within your Messaging Service.
  13. On the Messaging Service Settings page:
    • Confirm your Use Case
    • Within Inbound Settings select the radio button next to SEND AN INCOMING_MESSAGE WEBHOOK
    • In both the Request URL and Fallback URL fields, copy in your Symbee Connect Web Hook URL. This can be obtained from your Symbee Connect Administration Console, click here for details.
    • Click Save.


Obtain your Twilio Project API Credentials

The API credentials obtained here will be used during the SMS Twilio configuration in your Symbee Connect environment in Section 3.

  1. Navigate to your main Twilio Project Dashboard by clicking the Home icon at the top of the left side navigation bar and select the main project Settings submenu.
  2. Under Settings in the General section, locate the API Credentials section of the page:
  3. Copy the ACCOUNT SID value
  4. For the AUTH TOKEN value, click on the eye icon and copy the displayed value.



Configure Twilio SMS in your Environment

Declare SMS REST Based Provider

Declare an SMS REST Based Provider definition to represent your Twilio Messaging Service:

  1. Login to the Symbee Connect Administration Portal.

  2. If you have more than one Environment configured within your Company in Symbee Connect, make sure you have the appropriate one selected. This can be found on the Navigation bar to the left of the Function menu.

  3. Click on the Function menu on the in the top navigation bar and the select SMS Administration located under the Channel Configuration section.

  4. Select SMS - REST Based on the left and then click Add SMS Provider Mapping.

  5. Provide a SMS Provider Mapping Code and a Provider Mapping Name.

  6. Select your newly created Provider Mapping from the list view and configure the SMS Provider Configuration section with the following:

    • SMS Provider: select Twilio
    • Delivery Provider: select either Symbee or Amazon, depending on whether you want to have the SMS Conversations delivered through a Symbee Connect Skill Queue, or alternatively via an Amazon Connect Contact Flow.
    • User Name: leave blank
    • Password: leave blank
    • Access Key: use the ACCOUNT SID value obtained from your Twilio Project here.
    • Access Secret: use the AUTH TOKEN value obtained from your Twilio Project here.


  7. Scroll down to the SMS Number Queue Routing section and configure with the following:

    • Address 1: Phone Number assigned in your Twilio Messaging Service (from this step).
    • Queue Name 1 or Contact Flow 1 (depending on your Delivery Provider): Assign to a queue or contact flow. Either a Symbee Connect Skill Queue. Use subsequent address mapping fields if you are configuring multiple numbers.
      Note: When populating the Address field for each mapping, declare the Twilio Phone Number value in E.164 format (i.e. with a leading ‘+’ and the E.164 numeric Country Number) – see example below


  8. Scroll back to the top and click the Save button.


Your Twilio Webhook URL

Once the above step is complete, the resulting Webhook URL needs to be populated within your Twilio Messaging Service see this section, step 16.

The Webhook URL value can be copied from the bottom of your Twilio SMS – REST Based Provider Mapping above.

  1. Select your newly created Provider Mapping from the list view.

  2. Scroll down to the bottom to find the Callback Webhook URL. Copy the URL