Setting up your first AWS End User Messaging SMS Number

Overview

This guide walks you through how to set up the Symbee Connect SMS channel using the AWS End User Messaging (EUM) service in your AWS Account for SMS message delivery. For additional information see SMS Administration.

All general functionality for SMS management, queuing and handling resides in the Symbee Connect SaaS cloud, however for security reasons the actual usage of the AWS End User Messaging service remains in your own AWS account. An AWS CloudFormation is provided to establish the configuration needed in your AWS account for integration of AWS EUM with the Symbee Connect SaaS solution.

Prerequisites

Confirm CCP-V2 is being used

In order to receive Amazon Connect Chats (Chat/SMS) (if you are going to use Amazon as the Delivery Provider), 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. On the Amazon Connect Integration screen, in the top General section, confirm your Amazon Connect URL ends with "/ccp-v2".
   • If it doesn’t, modify your URL to end with /ccp-v2 - this is required to receive Amazon Connect Chats (Chat/SMS).

Run the CloudFormation

Download the AWS End User Messaging SMS CloudFormation

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 AWS End User Messaging SMS 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 Symbee Connect AWS End User Messaging SMS CloudFormation

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 - or just search for "CloudFormation").

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 Prerequisite - Prepare template section, select Choose an existing template

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
    
    

11. In the next Specify Stack Details screen, complete the fields as follows:

12. 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-endusermessagingsms

13. LambdaDistroBucket: This is the Symbee Connect Lambdas S3 bucket where the Pinpoint Lambda will uploaded from. Select the bucket name from the drop-down that matches the AWS region you are running the CloudFormation in
14. End User Messaging Contact Flow Lambda: Select from the dropdown, there will be only 1 value to pick from
15. End User Messaging / Pinpoint Lambda: Select from the dropdown, there will be only 1 value to pick from

16. Secrets Manager Region: Enter the name of the AWS region where the initial Symbee Connect Integration CloudFormation was run in (see section 2.2 above).
    Examples: us-east-1, us-west-2, eu-central-1, etc.
    
    

17. Click Next.

18. On the next Configure stack options screen, use all the defaults, but scroll down to the bottom Capabilities section, and check the “I acknowledge that AWS CloudFormation might create IAM resources.” checkbox, and click Next.

19. On the next Review and create screen, review the details, and scroll to the bottom and click Submit.

Claiming SMS Phone Numbers in AWS End User Messaging

The following steps claim a new SMS Phone Number in the AWS End User Messaging console. If you have already claimed SMS phone numbers, skip this section and continue with Complete the Two-way SMS configuration on your End User Messaging SMS numbers.

1. Log into your AWS Console and navigate to the AWS End User Messaging service console.
2. In the AWS End User Messaging console, from the left navigation bar, select SMS...
3. On the AWS End User Messaging SMS console, click Phone numbers in the left navigation bar, and click Request Originator in the top-right...
4. On the next Select Country screen, select your Message destination country, and click Next.
5. On the next Define use case screen, select appropriate values, making sure to select Yes for Two-way SMS messaging, and click Next...
6. On the next Select originator type screen, select the type of SMS phone number you want at the top (under Originator type), select your associated Brand and Campaign registration from the drop downs (see note at the top of this section above about Registrations), and at the bottom under Resource policy, select Amazon Simple Notification Service (SNS)...
7. On the final Review and Request page, review the details, and click Request in the bottom right.

You will be returned to the Phone Numbers screen, with your new Phone number showing, but the new number will likely be in a Pending state. You will need to wait until the numbers show a state of Active before you can begin using them. Based on experience, this can take a few days.

Complete the Two-way SMS configuration on your End User Messaging SMS numbers

Once you have claimed, and active, SMS phone numbers in AWS End User Messaging, you need to configure the destination for inbound SMS messages received on those phone numbers. This allows new sessions (conversations, or contacts) to be established for inbound SMS messages received from a customer that are not yet part of any in-progress conversation, as well as inbound SMS messages from the customer already in a conversation, being added to the appropriate session.

When configuring Two-way SMS on each number, you have two choices (below). When using Symbee Connect, both choices will still allow the SMS conversations to be delivered and handled seamlessly by agents logged into the Symbee Connect User/Agent UI. Which method you choose will mostly depend on whether you have the need to also allow agent-initiated outbound SMS conversations and how those will function, or whether you will only ever be handling customer-initiated inbound SMS conversations:

1. Inbound SMS message Destination type: Amazon Connect
   • Integrates the SMS phone number directly with Amazon Connect.
   • In this configuration, all conversational SMS messages (both customer-initiated inbound interactions, and agent-initiated outbound interactions) result in a Contact in Amazon Connect, and all SMS messages within those conversations are delivered directly through the Amazon Chat channel.
   • In this configuration, you will incur the higher Amazon Connect pricing line item labelled "SMS usage - per message" on the Amazon Connect pricing page (which at time of writing is $.010 per message), plus the AWS EUM SMS delivery costs (the latter you pay regardless). (Please refer to the AWS pricing pages for actual costs, as prices may change).
   • If agent-initiated outbound SMS messages are required, there are delivery-to-agent limitations that apply, due to all SMS conversations being delivered through the Amazon Chat channel. For details of these limitations, see: Notes for Agent-initiated Outbound SMS, specific to AWS End User Messaging.
   • When configuring the associated mappings in the Symbee Connect Admin Portal (in the next section), only Delivery Provider of Amazon applies. Setting the Delivery Provider to Symbee is not applicable in this configuration.
2. Inbound SMS message Destination type: Amazon SNS (Simple Notification Service)
   • Integrates the SMS phone number to an SMS Topic rather than directly with Amazon Connect. The Symbee Connect CloudFormation you ran further above already pre-configured this SNS topic for you, with all the associated required permissions.
   • In this configuration, whether all conversational SMS messages result in a Contact in Amazon Connect and get delivered through the Amazon Chat channel, depends on which Delivery Provider you select when configuring the associated mappings in the Symbee Connect Admin Portal (in the next section).
   • In this configuration, you will not incur the higher Amazon Connect pricing line item labelled "SMS usage - per message" on the Amazon Connect pricing page. If you choose to use Delivery Provider of Amazon, the SMS conversation gets delivered via a standard/basic Amazon Chat in Amazon Connect (which at time of writing is the lower $.004 per message). The AWS EUM SMS delivery costs you pay regardless. (Please refer to the AWS pricing pages for actual costs, as prices may change).
   • If agent-initiated outbound SMS messages are required, in this configuration you will have the option to use Delivery Provider set to Symbee to avoid the delivery-to-agent limitations that apply when SMS conversations get delivered through the Amazon Chat channel. When Delivery Provider is set to Symbee, the SMS conversations do not run through the Amazon Connect Chat channel, which allows agents to begin an outbound SMS conversation (or send a single SMS message) from any state (Available or Unavailable) regardless of whether they are servicing another interaction at the time, and avoids requiring you to have the agent's Amazon Connect Routing Profile with Cross-channel concurrency set to allow other channels concurrently.

Option 1 - To configure an End User Messaging SMS number to directly integrate to Amazon Connect:

1. From the AWS End User Messaging SMS console, click Phone numbers in the left navigation bar
2. From the phone numbers list, click into the Phone Number you want to configure
3. From the phone number detail screen, select the Two-way SMS tab at the bottom and click Edit settings... (Note: if your phone number has been assigned to a pool, the Edit settings option will be disabled - when a number is part of a pool, you need to do these same steps here but on the pool instead of the phone number (all phone numbers in a pool are always configured the same way)
4. From the Edit settings screen, check the Enable two-way message checkbox at the top, and select Amazon Connect as the Destination type...

5. In the Two-way channel role section of the above screen, you need an IAM Role that can be assumed by AWS End User Messaging, that gives it permissions to integrate with your Amazon Connect instance. If you have already set this up, skip to the next step (6) further below.

   • (For reference, see IAM policies for Amazon Connect in the AWS documentation - the steps below create an IAM Role for this)

   • In another browser tab, navigate to the IAM console,

   • First create an access policy... Under Access management on the left, select Policies, then click Create policy (top-right)

   • On the Policy Specify permissions page, switch to JSON, and paste the required IAM policy from the AWS documentation link above. The end result should look like this:

   • Click Next on the above, and on the final policy page give the policy a name (for example: AllowConnectChatIntegration) and a description, and click the bottom right Create policy to complete the policy creation.

   • Next, create an IAM Role to attach the above policy to... Under Access management on the left, select Roles, then click Create role (top-right)

   • Under Trusted entity type, select Custom trust policy...

   • In the custom trust policy JSON editor at the bottom, replace the starter JSON policy it provides with the trust policy from the AWS documentation link above (replacing the SourceAccount in the policy with your AWS account number). The end result should look like this:

   • Click Next on the above. On the following Add permissions page, search for the policy you created above, and select it to add to the role.

   • On the final Name, review, and create page, give the role a name (for example: AWSEndUserMessaging-UseAmazonConnect) and description, and click the bottom right Create role to complete the role creation.

6. Returning to the browser tab where you have the AWS End User Messaging SMS Phone Number Edit settings page, at the bottom of the page in the Two-way channel role section, select Choose existing IAM role, and in the Existing IAM roles drop-down, click the refresh button on the right to refresh the latest role list, and select the newly created IAM role from above.

7. Click Save changes on the bottom-right of the Phone Number Edit settings page to complete the Two-way SMS configuration. When you do this, a dialog will show like below, asking which Amazon Connect instance the Phone Number should be imported to.
8. Selecting the Connect instance appropriately, and click Import Phone Number to complete.

Once the above steps are complete, you should see the same phone number also listed in your Amazon Connect instance console in the Phone Numbers page, which "SMS" in the Active Channels column beside it.

Option 2 - To configure an End User Messaging SMS number to integrate with SNS (Simple Notification Service):

1. From the AWS End User Messaging SMS console, click Phone numbers in the left navigation bar
2. From the phone numbers list, click into the Phone Number you want to configure
3. From the phone number detail screen, select the Two-way SMS tab at the bottom and click Edit settings... (Note: if your phone number has been assigned to a pool, the Edit settings option will be disabled - when a number is part of a pool, you need to do these same steps here but on the pool instead of the phone number (all phone numbers in a pool are always configured the same way)
4. From the Edit settings screen, check the Enable two-way message checkbox at the top,
5. Select Amazon SNS as the Destination type,
6. Select Existing SNS standard topic, and in the SNS Topics dropdown, select the SNS Topic that was created by the CloudFormation you ran aty the beginning of this step-by-step guide. It will be named with a convention of: Symbee-Pinpoint-{your-company-alias}-{environment}
7. Lastly, under Two-way channel role, select the Use SNS topic policies option. You resulting screen should look something like this:
8. Click on Save changes in the bottom right to complete the Two-way SMS configuration.

Configuring the AWS End User Messaging SMS channel within Symbee Connect

When using Delivery Provider set to Symbee, you will need to configure at least one SMS type Skill Queue in Symbee Connect. Details for this immediately follow this section, here. This is needed to complete the steps in this section.

​ When using Delivery Provider set to Amazon, you will need to configure at least one Contact Flow in your Amazon Connect instance, used to begin customer-initiated inbound SMS conversations.

​ When using Delivery Provider set to Amazon, AND if you also want to allow agent-initiated outbound SMS conversations/messages, you will need to configure one further small Contact Flow in your Amazon Connect instance, used to loop-back new outbound SMS chats to the initiating agent/user. Details for creating this flow immediately follow this section, here.

Create a new Symbee Connect Skill Queue

The following steps create a new Skill Queue within Symbee Connect that will be used to queue new incoming AWS End User Messaging SMS conversations and have them routed to the appropriately skilled agents. This queue is then configured in the AWS End User Messaging SMS mapping created in the section further below.

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. Select Queues and Skill Assignment from the main Function menu in the top navigation bar.
4. Select Skill Queues in the resulting left-hand navigation bar, and click the Add New Queue button.
5. On the Add New Queue screen, enter an appropriate Skill Queue Code, Display Name and Description for your new Queue. Then make sure to select a Queue Type of SMS Pinpoint.
6. Complete the remaining settings for your new Skill queue as needed and Save.
7. Finally, use the Skill Assignment screen to assign your new Skill Queue to the appropriate agents that will be handling SMS conversations.

Create an Amazon Connect Contact Flow for Agent-initiated Outbound SMS

In your Amazon Connect instance, due to how SMS Chat conversations are handled in Amazon Connect, you need a Contact Flow that routes the new SMS Contact immediately back to the agent initiating the SMS conversation.

In Amazon Connect, create a new Contact flow (a standard flow, not an Outbound whisper flow) that gets used when an agent initiates a new Outbound SMS message or conversation via an AWS End User Messaging SMS phone number.

This flow basically initiates and immediately routes the contact back to the initiating agent, where it’s auto-answered (the Symbee Connect User/Agent UI automatically accepts these type of contacts immediately, regardless of whether the agent is configured for Auto-Accept in Amazon Connect or not). The SMS contact is routed back to the agent using the special sc_agent_id attribute (which gets populated by Symbee Connect with the Amazon Connect User-id of the agent initiating the outbound SMS). This happens in the Set Working Queue block.

Create the Contact flow as depicted in the screen-shot below:

• Set Working Queue: This is the required block, that causes the new outbound SMS Contact to be queued back to the initiating agent. for an agent to be able to initiate an Outbound SMS conversation. Configure this block as follows:

• Transfer to Queue: This block is the standard Transfer to Queue block - use its default configuration.

Configure an AWS End User Messaging SMS Mapping

The following steps create a new mapping configuration between your AWS End User Messaging SMS phone numbers, to either your new Skill Queue configured in the previous step (if Delivery Provider is set to Symbee) or to an Amazon Connect Contact Flow (if Delivery Provider is set to Amazon).

1. Select SMS Administration from the main Function menu in the top navigation bar under Channel Configuration.

2. Then select SMS - AWS End User Messaging in the left-hand navigation bar, and click the Add AWS EUM SMS Mapping button.

3. On the resulting Add AWS End User Messaging/Pinpoint SMS Mapping dialog window, enter an appropriate declarative Code and Description to represent the new mapping, and click Add.

4. Once added, select the new mapping from the list screen, and click Modify.

5. On the Maintain AWS End User Messaging/Pinpoint SMS Mapping screen, complete the fields as follows...

---

Under the AWS End User Messaging / Pinpoint SMS Configuration section...

AWS Configuration Mode

If you are still using an older/legacy Amazon Pinpoint project, set the mode to: Pinpoint Project

If, when you configured Two-way SMS on your phone numbers in AWS End User Messaging to use SNS (Simple Notification Service), set the mode to: End User Messaging - SNS integrated

If, when you configured Two-way SMS on your phone numbers in AWS End User Messaging to integrate directly to Amazon Connect, set the mode to: End User Messaging - Connect integrated

Project Id

(Only relevant if the mode above is set to Pinpoint Project). Paste the unique 32 character Project ID for your Pinpoint SMS project in your AWS Account here.

Delivery Provider

(If the mode above is set to End User Messaging - Connect integrated, Delivery Provider will be forced to Amazon)

Refer to Selecting the Chat Delivery Provider for further details on what this is, and the implications of each choice.

Set to Symbee to have the SMS conversations delivered/routed directly through a Symbee Connect Skill Queue.

Set to Amazon to have the SMS conversations delivered/routed via Amazon Connect.

Outbound Contact Flow

(Only relevant when the Delivery Provider above, is set to Amazon)

Set this to the Contact Flow you created in Amazon Connect in the previous Create an Amazon Connect Contact Flow for Agent-initiated Outbound SMS section. This is the flow that gets used when an agent initiates a new Outbound SMS message from any phone numbers mapped in this configuration, to route the new SMS Contact immediately back to the initiating agent.

Default Country Code

All phone numbers seen in SMS conversations are converted to the international E.164 phone number format (e.g. +17201232216).

Enter the ISO country code to be assumed (e.g. US, GB, FR, etc.) for phone numbers seen in conversations that don’t already have an explicit identifiable country-code, used for converting to E.164 format.

For a reference list of all ISO country codes, refer to the values in the “ISO CODES” column of the table posted here: https://countrycode.org/

Configuration Set Name

(Only relevant if the mode above is not set to Pinpoint Project)

If you have a Configuration set configured in AWS End User Messaging SMS to control where activity and stats are sent, and you want to use it for the phone numbers configured in this mapping, set this to the name of the Configuration set in AWS EUM SMS.

AWS Region

Set to the same AWS region where you ran the CloudFormation at the beginning of the Step by Step guide, and where your AWS End User Messaging SMS phone numbers reside.

Under the Chat Control section...

Suppress System Messages to Customer

If enabled, system generated messages such as Agent Disconnected and Conversation Ended will not be sent out. Check this to reduce the number of extra (usually unwanted in an SMS conversation) messages in the SMS conversation.

Idle Timeout

If no activity is seen from agent or customer, how long in minutes do you want the SMS conversation to remain active before it is automatically ended? A value between 1 and 60 is required.

Idle Timeout Message

The system message that is sent when in the conversation when an idle timeout occurs.

Under the SMS Phone Number and Routing Details section...

This section allows you to configure (map) up to 5 of your SMS phone numbers to this specific configuration in Symbee Connect. (If you have more than 5 SMS phone numbers, create multiple mapping configurations in Symbee Connect).

Set the values for each of the 5 phone numbers as follows:

SMS Phone Number (n)

The phone number you claimed within your AWS End User Messaging SMS console. Enter the phone numbers in E.164 format, including the leading “+” sign, and don’t include any braces, dashes, or spaces.

Display Name (n)

The friendly name displayed for this SMS Phone Number in the Agent UI. If your agent's are allowed to initiate unsolicited outbound SMS conversations/send messages, depending on how the agent is configured (see the section further below), they may get displayed a list of "Origin" SMS phone number to send the outbound conversation/messages from. This is the display name they will see in that list of choices.

Skill Queue Code (n)

(Only relevant when the Delivery Provider further above, is set to Symbee)

Select the associated SMS Pinpoint Skill Queue (you created in the Create a new Symbee Connect Skill Queue section further above) from the drop-down list to route new incoming SMS conversations to.

Contact Flow (n)

(Only relevant when the Delivery Provider further above, is set to Amazon, and when the AWS Configuration Mode is not set to End User Messaging - Connect integrated)

Choose which Amazon Connect Contact Flow you want to use to begin inbound SMS conversations received on this phone number.

---

When complete, click Save to save your changes.

Configure Agents to Initiate Outbound Messages from the Symbee Connect UI

Lastly, in order for an agent or group of agents to be able to initiate outbound SMS messages from within the Symbee Connect client, they must be configured to do so. In addition to configuring the agent(s) to allow this functionality, you can also set a default originating SMS Phone Number for their messages or conversations to be sent out from. Even with this default origin set, they will still have the ability to change it to another originating SMS Phone number if they choose to.

In your Symbee Connect Administration portal:

1. Select User Administration from the main Function menu in the top navigation bar.

2. In either a group user template or within an individual agents user profile, select the Digital Channels option on the left hand menu. Then expand the Chat section.

3. Configure the following options:

   • Outbound SMS Allowed: Tick the checkbox to enable. This will allow the individual agent or group of agents to initiate unsolicited outbound SMS conversations.

   • Outbound SMS Default Origin: If Outbound SMS is allowed, enter in one of the configured SMS Phone Numbers that you have setup within your SMS Integrations. The phone number must be entered using E.164 format.

   For example: +1112223456. If no phone number is provided, the agent will be required to choose an originating SMS Phone Number from a list of those available, the first time they begin an outbound SMS conversation or send a message.
   
   
   
   

4. Scroll to the top and click Save to save the changes to the User profile or User Template.