Skip to main content

Setting Up The CTI Adapter Using Guided Setup

In order to navigate to the Guided Setup feature, perform the following steps (NOTE: If you are not an admin user then you must first add yourself to the AC_Administrator permission set, see here for more details):

  1. Navigate to the Service Console in your Salesforce instance.

  2. Click the drawdown button in the Service Console navigation bar, and select Edit.

  1. In the proceeding popup, select Add More Items.
  1. Click the + button next to AC Guided Setup, then add the item and save.

  2. Select the newly added AC Guided Setup button in the drawdown menu.

Guided Setup Prerequisites#

The below sections are linked to from the Guided Setup feature. Only perform the below steps when the Guided Setup feature links to them.

Create Named Credential#

See here for instructions on setting up the Named Credential.

Create Connected App#

To get access to the environment, a Connected App must be configured with OAuth settings enabled.

  1. Log in into your Salesforce org and go to Setup

  2. In the Quick Find field, type app manager, then select App Manager from the results

  3. In the upper right corner, select New Connected App

  1. On the New Connected App form, enter a name for the Connected App, such as Amazon Connect Integration and press tab. This will populate the API Name automatically. Then provide a contact email address
  1. Select the checkbox to Enable OAuth Settings
  1. Set the Callback URL to https://www.salesforce.com
  1. In the Selected OAuth Scopes section, select the following and add them to the Selected OAuth Scopes:

  2. Access and manage your data (api)

  3. Access your basic information (id, profile, email, address, phone)

  4. Select the checkbox for Require Secret for Web Server Flow

  5. The API (Enable OAuth Settings) section should now look like this

  1. Select Save at the bottom of the screen.

  2. Select Continue on the New Connected App page

  3. You should now be at the new app's page

  4. Copy the value for Consumer Key to your notepad

  5. Select Click to reveal next to Consumer Secret and copy the value to your notepad

  6. At the top of the detail page, select Manage

  7. On the Connected App Detail page, select the Edit Policies button

  8. Set Permitted Users to Admin approved users are pre-authorized and choose OK on the pop-up dialog

  9. Set IP Relaxation to Relax IP restrictions

  10. The OAuth Policies section should now look like the following

  1. Select Save

Guided Setup Additional Instructions#

The below sections are linked to from the Guided Setup feature. Only perform the below steps when the Guided Setup feature links to them.

Retrieve Amazon Connect Instance Url#

  1. Navigate to the Amazon Connect Console

  2. Select your Instance Alias

  3. On the Overview page for your instance, copy the Login URL up until the / (if your login url has one).

Add users to the Call Center#

  1. Log in into your Salesforce org and go to Setup

  2. In the Quick Find field, enter Call Center, then select Call Centers from the result list

  1. If you see the Say Hello to Salesforce Call Center page, select Continue

  2. Select AC Lightning Adapter

  1. On the AC Lightning Adapter detail page, select Edit

  2. On the AC Lightning Adapter: Manage Users page, select Add More Users.

  3. Set filters (if desired) and then choose Find.

  4. Select the checkbox next to the user to add, then choose Add to Call Center.

  1. Repeat the steps to add more users.

Add users to a Permission Set#

All users must be assigned the required permission set to access Salesforce metadata. The Amazon Connect CTI Adapter includes two Permission Sets, one for agents and one for managers, that grant users the appropriate access for their role. More information on assigning user permissions can be found in the Salesforce help documentation.

  1. Log in into your Salesforce org and go to Setup

  2. In Quick Find, enter Permission and select Permission Sets from the results

  3. Choose AC_Administrator, AC_Agent or AC_Manager as appropriate for the user(s)

  1. Choose Manage Assignments.

  2. Choose Add Assignments.

  3. Select the users to assign the permissions, then choose Assign.

  1. Repeat these steps as needed for all users

AC_Administrator#

AC_Manager#

AC_Agent#

Configure the Toolkit settings#

  1. Navigate to Setup then in type Custom Settings in Quick Find
  1. Next to the Toolkit for Amazon Connect custom setting, choose Manage
  1. Select New
  1. On the following page, provide the URL to your Amazon Connect instance. This value can be found in your Amazon Connect console.

You will also see the option to enable and disable certain triggers in the package, which you can configure to meet your needs. You can change these whenever you would like to. For more details, see the troubleshooting section.

  1. Select Save

Create the Softphone Layout#

The softphone layout settings will tell the console what resources are available for screenpop by default and what to do under different match conditions.

  1. Log in into your Salesforce org and go to Setup

  2. In the Quick Find box, type Softphone, then choose Softphone Layouts from the results

  3. If you are presented with the Get Started message, choose Continue

  4. On the Softphone Layouts page, choose New

  1. Enter a name for the layout, such as AmazonConnectDefault, then select the Is Default Layout checkbox.
  1. Expand Display these salesforce.com objects and select objects that CTI Connector should be able to search, for a screen-pop query. In this example, Case has been added to the default selection, allowing search and screen-pop by CaseID.
  1. If desired, configure the search behavior to your requirements
  1. Additionally, validate the Screen Pop settings. Please note that the default behavior is to not pop a screen if there is more than one result
  1. Once you have configured the search behavior, choose Save

Retrieve the Salesforce API Version#

  1. Log in into your Salesforce org and go to Setup

  2. In the Quick Find field, type apex, then select Apex Classes from the results

  1. Select New
  1. Select the Version Settings tab
  1. Note the Salesforce.com API version in your notepad. The pattern of this value is vXX.X.

Setting up the Salesforce API User#

The Lambda functions authenticate with Salesforce via user credentials. It is a common practice to create an API user account for this purpose.

  1. Log in into your Salesforce org and go to Setup

  2. In the Quick Find field, type profiles, then select Profiles from the results

  3. Select New Profile

  1. Provide a Profile Name, such as API_ONLY

  2. From the Existing Profile dropdown, select System Administrator NOTE: You\'re advised to use a full Salesforce License for the user to be able to set the below permissions and have full access to avoid any other errors.

  1. Select Save to create the new profile

  2. Once the new profile page opens, select the Edit button

  3. Scroll down to the Administrative Permissions section

  4. If the Lightning Experience User checkbox is selected, clear it

  1. Scroll down to the Password Policies section at the bottom of the page

  2. Set User password expire in to Never expires NOTE: Failure to this may lead to production outages.

  3. Select Save

  4. In the Quick Find field, type connect, then select Manage Connected Apps from the results

  1. Select the app you have created earlier, Amazon Connect Integration

  2. In the profiles section, select Manage Profiles

  3. Select the new API_Only profile that you just created

  4. Select Save at the bottom of the page

  5. In the Quick Find field, type users then select Users from the results

  6. Select New User

  7. Set the required fields as:

    a. Last Name: apiuser

    b. Alias: apiuser

    c. Email: provide a valid email address

    d. Username: apiuser@<yoursalesforcedomain>.com

    e. Nickname: apiuser

  8. On the right-hand side, set User License to Salesforce

  9. Set Profile to API_ONLY

  10. Choose Save

  11. In Quick Find, search for "Permission Sets". Select the AC_Administrator permission set.

  1. Select Manage Assignments. Add the apiuser you just created to the permission set.

  2. A confirmation email with an activation link will be sent to the email address provided. Choose the link to activate your user and set their password

  3. Fill out the form to set a password for the API user

  4. Select Change Password. The API user will log into the Salesforce Classic view

  5. Access the API user's personal settings by selecting the username in the top right corner, then choose My Settings

  1. In the Quick Find field, type security then select Reset My Security Token from the results
  1. Select Reset Security Token. Your security token will be emailed to you

  2. Copy the security token from the email to your notepad

Setting up the SecretsManager Secret#

To ensure that your Salesforce credentials are secure, the Lambdas require that the credentials are stored in AWS Secrets Manager. AWS Secrets Manager is a highly secure service that helps you store and retrieve secrets.

  1. In a new browser tab, login to the AWS console

  2. Make sure you are in the same region as your Amazon Connect instance. You can set the region by expanding the region selector in the upper right and choosing the region

  1. Navigate to the Secrets Manager console

  2. Select Secrets

  3. Select Store a new secret

  4. Select Other types of secrets

  5. Make sure Secret key/value is selected

  6. Enter key value pairs that match the following:

    a. Key: Password, Value: the password for the API user that you configured in the previous section

    b. Key: ConsumerKey, Value: the Consumer Key for the Connected App you created in the previous section

    c. Key: ConsumerSecret, Value: the Consumer Secret for the Connected App you created in the previous section

    d. Key: AccessToken, Value: this is the access token for the API user that you configured in the previous section

  7. For the encryption key, click Add new key

  8. Select Create Key

  9. Make sure key type is set to symmetric

  10. Give your key an alias, like SalesforceCredentialsSecretsManagerKey

  11. Click Next

  12. Select administrators you want to have access permission to change the key policy. Make sure you are being as restrictive as possible

  13. Click Next

  14. Select the users and roles you want to have access to the Salesforce credentials in Secrets Manager. Make sure you are being as restrictive as possible

  15. Click Next

  16. Click Finish

  17. Click on the managed key that you just created (which is SalesforceCredentialsSecretsManagerKey in this case).

  18. Note down the ARN. This is SalesforceCredentialsKMSKeyARN that will be used later when installing the Amazon Connect Salesforce Lambda package.

  19. Navigate back to the Secrets Manager setup tab

  20. Select the key you just created

  1. Click Next

  2. Give your secret a name, like SalesforceCredentials

  3. Click Next

  4. Make sure Disable automatic rotation is checked.

  5. Click Next

  6. Click Store

  7. Select the secret you just created, and copy the Secret ARN

Test the Salesforce Lambda Core Functionality#

The package provides a core Lambda function (sfInvokeAPI) that supports multiple operations, like lookup, create and update. For the initial validation, sample events are provided within the function. Validating this function provides a good check that the installation and configuration is correct.

Validating the lambda functions requires the use of test events to simulate data coming into the function as it would in a typical deployment. Each function has a set of test event samples included to make validation easier.

Validate the core functionality#

  1. In a new browser tab, login to the AWS console

  2. Open the AWS Lambda Console

  3. In the Filter field, enter sfInvokeAPI and press enter, this will filter your list out to the core function that we just installed

  1. Select the function name. First, we will validate a phone number lookup.

  2. In the Environment pane, double-click the event-phoneLookup.json file

  1. The test even JSON will open in the Lambda editor

  2. Modify the value for sf_phone to match the phone number of the test contact you created when you setup the CTI adapter or for any valid contact in your Salesforce org\ NOTE: The phone number must be in E.164 format

  1. Select the entire JSON event and copy it, then close the event-phoneLookup.json tab.

  2. In the top-right corner, select drop-down arrow next to Test and choose Configure test events

  1. Select the radio button for Create new test event and provide an event name, for example: phoneLookup

  2. Select the existing event JSON and delete it. Paste the modified JSON payload you copied from the event-phoneLookup.json file

  1. Select Create to save your test event

  2. By default, your new test event should be selected in the drop-down list to the left of the Test button.

  1. Select Test

  2. If successful, the result will contain fields defined in "sf_fields" parameter in the invocation event

  1. Copy the value for the Id key in the response. Next, we are going to use that Id to create a Case in Salesforce.

  2. In the Environment pane, double-click the event-create.json file. Replace the existing ContactId value with the ID value you copied previously.

  1. Select the entire JSON event and copy it, then close the event-create.json tab.

  2. In the top-right corner, select drop-down arrow next to Test and choose Configure test events

  1. Select the radio button for Create new test event and provide an event name, for example: createCase

  2. Select the existing event JSON and delete it. Paste the modified JSON payload you copied from the event-create.json file

  1. Select Create to save your test event

  2. By default, your new test event should be selected in the drop-down list to the left of the Test button.

  1. Select Test

  2. If successful, the result will contain the Case Id

  1. Copy the value for the Id key in the response.

  2. When we created the case, the Status was set to New and the Priority to Low. We are going to use the update operation to close the case.

  3. In the Environment pane, double-click the event-update.json file and replace the existing Case Id in "sf_id" parameter with the new one you copied from the last test result

  1. Select the entire JSON event and copy it, then close the event-update.json tab.

  2. In the top-right corner, select drop-down arrow next to Test and choose **Configure test events

  1. Select the radio button for Create new test event and provide an event name, for example: updateCase

  2. Select the existing event JSON and delete it. Paste the modified JSON payload you copied from the event-update.json file

  1. Select Create to save your test event

  2. By default, your new test event should be selected in the drop-down list to the left of the Test button.

  1. Select Test

  2. If successful, the result will be the HTTP 204 No Content success status response code

  1. Log in into your Salesforce org and go to the Service Console

  2. In the search box, change the object type to Cases and type Amazon Connect Case, then press enter

  1. You should find 1 case opened by the API user, and the status should be closed
  1. You have completed core function validation

Allow Amazon Connect to Access the sfInvokeAPI Lambda Function#

Once you have validated function, you can use the Amazon Connect console to add the sfInvokeAPI Lambda function to your Amazon Connect instance. This automatically adds resource permissions that allow Amazon Connect to invoke the function.

Add the Lambda function to your Amazon Connect instance#

  1. In a new browser tab, login to the AWS console

  2. Navigate to the Amazon Connect Console

  3. Select your Instance Alias

  4. In the navigation pane, choose Contact flows.

  1. For AWS Lambda, select the function that includes sfInvokeAPI in the name
  1. Choose Add Lambda Function. Confirm that the ARN of the function is added under Lambda Functions.
  1. The AWS Lambda function has been added to your Amazon Connect instance.

Create Public/Private key pair for the Cloudfront distribution#

Use the following command to generate a private key:

openssl genrsa -out private_key.pem 2048

Use the following command to generate a public key from the private key: openssl rsa -pubout -in private_key.pem -out public_key.pem

Add Private Key, Access Key to Secrets Manager Secret#

To retrieve the Access Key ID:

  1. Navigate to the Cloudfront console.

  2. In the left hand sidebar, select Public keys.

  3. Look for the public key that was created by Guided Setup, and copy down the public key's ID

To add the private key and access key to the Secrets Manager secret:

  1. Copy and paste the contents of the private key .pem file into a text editor. Replace every newline character with a space, and then delete the last character. This is most easily done using a "find and replace" feature in your text editor. The resulting string of text should resemble the following:
-----BEGIN RSA PRIVATE KEY----- (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (64 character string) (under 64 character string) -----END RSA PRIVATE KEY-----
  1. Navigate to the "Secrets Manager" service. Select the SalesforceCredentials.

  2. Under the "Secret value" tab, select "Retrieve secret value" and then "Edit".

  3. For the CloudFrontPrivateKey field, copy and paste the modified contents of the private key .pem file. For the CloudFrontAccessKeyID field, copy and paste the Access Key Id you recorded above. Your Secrets Manager Secret should look like the following:

Please note that your secret may also be formatted stored as a "Secret key/value" secret rather than a "Plaintext" secret; both secret types are valid.