Setting up Integration for Inbound and Outbound SMS

This topic is part of the manual Digital Channels Private Edition Guide for version Current of Digital Channels.

Genesys Multicloud CX supports SMS interactions using one of these three options: built-in connector to Kaleyra SMS text messaging service, a custom gateway built with a third-party messaging API, or a built-in connector to Genesys Cloud CX SMS aggregation service.After completing the setup steps on this page, you will be able to:

Receive SMS messages from your customers on your corporate short code or long code and allow a Designer application or agent to respond to them.
Send SMS messages in your outbound campaigns through CX Contact.

To get started, complete the configuration steps for one of the following scenarios:

Option 1: Set up Digital Channels to use Kaleyra SMS

Complete the steps in this section to set up Digital Channels to use the built-in connector to Kaleyra.

Review the prerequisites table.
Use the Digital Channels provisioning API to create Digital Channels services definition.
Manage and provision sender IDs.

Prerequisites

Review the Prerequisites table and make sure you have all the listed information before you get started. The values in this table are referenced later by the name in the Variable column.

Prerequisites
Parameter	Variable	Type	Example	Notes
Company's sender id	$tfn	string	1650466114	The sender id can be a short code (5 digits) or a long code (10 digits).
Contact Center Id	$ccid	UUID string	45acae06-6b7c-4f97-9c76-471cb5c21bf7	This value comes from your Web Services and Applications deployment.
Digital Channels URL	$baseURL	string	http://digital.example.com	Publicly available URL for Digital Channels API
Kaleyra API URL	$kaleyraURL	string	http://directtext.mgage.com	URL for Kaleyra SMS API.
Kaleyra user name	$kaleyraUserName	string	Secret	The username for an account with permission to send SMS.
Kaleyra password	$kaleyraPassword	string	Secret	The password for an account with permission to send SMS.

Create Digital Channels services definitions

Enable Digital Channels to use the built-in connector to Kaleyra SMS services (Kaleyra was formerly known as mGage). You must configure the following services in Digital Channels within your tenant:

SMS - Enables SMS media for the tenant and selects Kaleyra as the default provider.
mGageSMS - Integrates your Genesys Multicloud CX tenant to Kaleyra for SMS communication.

Important

Use a REST client or curl utility to provision the following services in Digital Channels using the provisioning API. Make sure to substitute the variables - prefixed with '$' - with their values. Note: You must create these services once per tenant.

Create the SMS service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/SMS \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
    "url" : "N/A",
    "data" : { "provider": "mGage" },
    "secret": {}
}'

Create the mGageSMS service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/mGageSMS \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
        "url": "$kaleyraURL"
        "data": { },
        "secret": {          
             "username": "$kaleyraUserName", 
             "password": "$kaleyraPassword"         } }'

Adding sender IDs to Kaleyra

If you need to add a new short code or text-enabled phone number, contact your Genesys representative to complete this step.

Manage and provision sender IDs

Provision sender IDs in Digital Channels.

Option 2: Set up Digital Channels to use a Custom Gateway

Complete the steps in this section to set up Digital Channels to use a custom SMS gateway provider.

Review the prerequisites table.
Use the Digital Channels provisioning API to create Digital Channels services definitions.
Manage and provision sender IDs..

Prerequisites

Review the Prerequisites table and make sure you have all the listed information before you get started. The values in this table are referenced later by the name in the Variable column.

Prerequisites
Parameter	Variable	Type	Example	Notes
Company's sender id	$asyncPhoneNumber	string	16504661149
Third-party Messaging Webhook URL	$asyncWebhookURL	string	https://genesys-webhook.company.com	The FQDN of the third-party service implementing the Third-Party Messaging Webhook.
Third-Party Messaging API secret key	$asyncAPISignatureKey	string	Secret	The key used by the third-party service to calculate the signature for calls to the Third-Party Messaging API.
Third-Party Messaging Webhook secret key	$asyncWebhookSignatureKey	string	Secret	The key used by Digital Channels to calculate the signature for calls to the third-party service through the webhook.

Create Digital Channels services definitions

In this step, you will enable Digital Channels to use a custom gateway for the SMS provider of your choice. You must configure the following services in Digital Channels within your tenant:

Async - Integrates the Genesys Multicloud CX tenant to the custom gateway used to communicate with the SMS provider of your choice.
SMS - Enables SMS media for the tenant and selects the Async provider.

Important

Use a REST client or curl utility to provision the following services in Digital Channels using the provisioning API. Make sure to substitute the variables - prefixed with '$' - with their values. You must create these services once per tenant.

Create the Async service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/Async \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
        "data": {
          "channels": [
            {
              "channelId": "$asyncPhoneNumber",
              "webhook": { "url": "$asyncWebhookURL" }
            },
            {
              "channelId": "$asyncEmailDomain",
              "webhook": { "url": "$asyncWebhookURL" }
            }
          ]
        },
        "secret": {
          "channels": [
            {
              "channelId": "$asyncPhoneNumber",
              "webhook": { "secret": "$asyncWebhookSignatureKey" },
              "api": { "secret": "$asyncAPISignatureKey" }
            },
            {
              "channelId": "$asyncEmailDomain",
              "webhook": { "secret": "$asyncWebhookSignatureKey" },
              "api": { "secret": "$asyncAPISignatureKey" }
            }
          ]
        }
      }'

Create the SMS service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/SMS \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
    "url" : "N/A",
    "data" : { "provider": "Async" },
    "secret": {}
}'

Manage and provision sender IDs

If you need to register a new or a existing short code or a text-enabled phone number, contact your Genesys representative to complete this step.

Provision sender IDs in Digital Channels.

Important

An SMS must have a "provider" property equal to "Async" to use the Third-Party Messaging API implementation.

Add custom HTTP headers

You can add custom HTTP headers with static values to the webhooks sent by Digital Channels to the third-party messaging aggregator. On the transaction NexusServices > [your async provider], add a property that starts with the "header:" prefix and set it to your static value. For example, header:custom-header-for-async-1 = 12345. The webhook from Digital Channels will include this property name and value in the header:

HTTP <\path\>
custom-header-for-async-1: 12345
X-Hub-Signature: <value>
X-B3-TraceId: <value>
Content-Type: application/json
 
{
  "messages": [
    {
        ... RichMedia message ...
    }
  ]
}

Option 3: Set up Digital Channels to use Genesys Cloud CX SMS Aggregation

Complete the steps in this section to set up Digital Channels to use Genesys Cloud CX SMS Aggregation as the SMS gateway.

Review the prerequisites table.
Contact your Genesys representative to create a Genesys Cloud CX organization and get administrator user credentials. Your Genesys representative also must add the Genesys SMS Aggregation product to your organization.
Create the Digital Channels integration in Genesys Cloud CX. This will give you a clientId and clientSecret to authenticate API calls with the Digital Channels provisioning API.
Create a Digital Channels API key for Genesys Cloud CX.
Use the Digital Channels provisioning API to create Digital Channels services definition.
Manage and provision sender IDs.

Prerequisites

Review the Prerequisites table and make sure you have all the listed information before you get started. The values in this table are referenced later by the name in the Variable column.

Prerequisites
Parameter	Variable	Type	Example	Notes
GWS tenant Contact Center ID	$ccid	UUID string	45acae06-6b7c-4f97-9c76-471cb5c21bf7	This value comes from your Web Services and Applications deployment.
Nexus Provider	$nexusProvider	string	Portico	This option depends on the provider's value of the service. Supported values: - Portico - Async - mGage

Request a Genesys Cloud CX organization

Contact your Genesys representative to create a Genesys Cloud CX organization and get administrator user credentials. Your Genesys representative also must add the Genesys SMS Aggregation product to your organization.

Make sure your Genesys representative provides you with the details in the Genesys Cloud CX information table.

Genesys Cloud CX information
Parameter	Variable	Type	Example	Notes
Genesys Cloud CX Organization ID	$orgId	UUID string	47d8329d-1c28-4c86-9374-5596bddfee15	Your Genesys Cloud CX organization ID.
Genesys Cloud CX Organization admin user credentials	$orgUsername $orgPassword	string	admin-user / admin-password	The username and password for an account with administrative permissions for this organization.
Genesys Cloud CX Login URL	$gcLoginURL	HTTPS URL string	https://login.mypurecloud.com	Your Genesys Cloud CX login URL (depends on your organization region).
Genesys Cloud CX API URL	$gcAPIURL	HTTPS URL string	https://api.mypurecloud.com	Your Genesys Cloud CX login URL (depends on your organization region).

Create the Digital Channels integration in Genesys Cloud CX

Complete the steps in this section as an administrator user in Genesys Cloud CX to create the integration client credentials that will be used by Digital Channels to access Genesys Cloud CX APIs to send and receive messages. You're going to create a new role, assign it to your admin user, and create the access credentials.

First, create the new role:

Navigate to $gcLoginURL (for example, https://login.mypurecloud.com) and log in to Genesys Cloud CX with your $orgUsername/$orgPassword.
Go to Admin.
Under People and Permissions, click Roles/Permissions.
Click Add Role and give it a name. For example, Nexus Messaging.
Under Permissions, search for messaging and select messaging > All Permissions and messagingProvisioning > All Permissions. Save your changes.

Next, assign the role to your administrator user:

Click Admin.
Under People and Permissions, click People.
Search for your admin user.
Under Roles, switch the view to All and search for the name of your new role (Nexus Messaging). Click to enable the role and then save your changes.
Log out and log in again to enable the permissions.

Now create access credentials for the Digital Channels integration.

Click Admin.
Under Integrations, click OAuth.
Click Add Client.
Under Client Details, set App Name to Nexus Messaging Integration and select the Client Credentials Grant Type.
Click Roles and assign the Nexus Messaging role. Save your changes.
Go back to Client Details and copy the values for clientId and clientSecret.

As the output of this step, you will have the access credentials:

Parameter	Variable	Type	Example
Nexus Integration client ID	$clientId	UUID string	4da40a9de-b113-4024-8ba9-c9dd89c91f67
Nexus Integration client secret	$clientSecret	string	aKSXEgLO57cm6FqxD4hrjkcW-iuWiXhd0uF0WOcZUm2

Create a Digital Channels API key for Genesys Cloud CX

To create an API key that will be used by Genesys Cloud CX to send requests to Digital Channels, follow the steps in Provision API keys. Make sure to use the following parameters:

"tenant": "*"
"name":"Portico Cluster API Key"
"permissions" : ["nexus:cluster:*"]

As an output of this step, you will have the API key:

Parameter	Variable	Type	Example
Messaging Cluster API Key	$apikey	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695

Create Digital Channels services definitions

Enable Digital Channels to use Genesys Cloud CX SMS Aggregation as the SMS provider. You must configure the following services in Digital Channels within your tenant:

PurecloudIDP - Integrates the Genesys Multicloud CX tenant to the Genesys Cloud CX organization.
SMS - Enables SMS media for the tenant and selects the provider.
PorticoSMS - Enables the SMS service through Genesys Cloud CX.

Important

Use a REST client or curl utility to provision the following services in Digital Channels using the provisioning API. Make sure to substitute the variables - prefixed with '$' - with their values. Note: You must create these services once per tenant.

Create the PurecloudIDP service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/PurecloudIDP \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
    "url" : "$gcLoginURL",
    "secret": {"clientId": "$clientId", "clientSecret": "$clientSecret"},
    "data" : {}
}'

Create the SMS service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/SMS \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
    "url" : "N/A",
    "secret": {},
    "data" : {"tokenProvider": "Purecloud"}
}'

Create the PorticoSMS service:

curl -X POST \
  $nexusURL/nexus/v3/provisioning/services/$ccid/PorticoSMS \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $apiKey' \
  -H 'x-ccid: $ccid' \
  -d '{
    "url" : "$gcAPIURL",
    "secret": {},
    "data": {}
}'

Manage provision sender IDs

You can purchase new SMS numbers or re-use your existing text-enabled numbers.

If you need to register an existing phone number or new short code, contact your Genesys representative to complete this step. Otherwise, follow the steps below to use the Genesys SMS Aggregation API from Genesys Cloud CX to purchase and register toll-free numbers from the pool of available numbers. Note: Each purchased number will incur additional costs to your account.

Retrieve the Genesys Cloud CX token

Any Genesys Cloud CX operation has to include a security token that remains valid for a configured amount of time. When the token expires, you must retrieve it again in order to send new requests.

To retrieve your token, use Basic Authentication where the username is $clientId and the password is $clientSecret.

curl -X POST \
  $gcLoginURL/oauth/token \
  -H 'Authorization: Basic YOUR_BASIC_AUTHENTICATION_SECRETS' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'

The response contains:

access_token - You must include this in all subsequent requests.
expires_in - Indicates how long the token is valid.
token_type - Indicates how this token needs to be included in subsequent requests (bearer token).

List purchased and registered numbers

Run the following command to list your purchased and registered numbers:

curl -X GET \
  $gcAPIURL/api/v2/messaging/sms/provisioning/tollfreenumbers/ \
  -H 'Authorization: Bearer $access_token'

Search for available toll free-number

To order a new number, first search for available numbers and then select one of the options.

curl -X GET \
  $gcAPIURL/api/v2/messaging/sms/provisioning/tollfreenumbers/available \
  -H 'Authorization: Bearer $access_token'

The response contains a few currently available numbers - choose the one you like. We'll use the variable $tfn to represent this number.

Order a toll-free number number

When you send this request, use the comment and emailAddress fields to help Genesys Customer Care quickly identify the best contact person if there's an issue with the SMS service. For example, you can include your organization name in the comment field.

curl -X POST \
  $gcAPIURL/api/v2/messaging/sms/provisioning/tollfreenumbers/ \
  -H 'Authorization: Bearer $access_token' \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "tollfreeNumber": "$tfn",
        "comment": "Nexus Premise ACME Corp",
        "moUrl": "$nexusURL/nexus/v3/sms/message",
        "drUrl": "$nexusURL/nexus/v3/sms/receipt",
        "webhookUsername": "$ccid",
        "webhookPassword": "$GMAKey",
        "emailAddress": "sms.admin@acme.test.com"
    }
]'

Finally, provision your new numbers in Digital Channels.

Provision sender IDs in Digital Channels

Complete the following steps for each short code or text enabled toll-free number you want to use to send and receive SMS messages.

Log in to Designer and create an application to route SMS interactions. Create a chat endpoint and assign it to your application, making note of the name you use. We'll use the variable $designerEndpointName to represent this value.
Log in to Platform Administration and go to Environment > Transactions > NexusServices > Options.
Create a section that starts with 'chat.' and includes some text that represents the purpose of number. For example, chat.SMS_Main_Corporate or chat.SMS_CustomerSupport. Note: The 'chat.' prefix is required and the rest of the value can be made up of letters and underscore or dashes, but not spaces.
In this new section, create the following options:
- channelId = $tfn
- channelType = sms
- endpoint = chat.$designerEndpointName
- interactionSubtype = SMS
- interactionType = Inbound
- media = chat
- cxcOnly = false
  Note: Set cxcOnly to true for CX Contact integrations. If true, incoming SMS messages are not processed as chat messages and are not delivered to an agent. The default value is false.
- provider = $nexusProvider (Default: Portico, if the value is missing)

Digital Channels Private Edition Guide

Overview

Configure and deploy

Upgrade, roll back, or uninstall

Integrate and provision

Configure and deploy AI Connector

Observability

Setting up Integration for Inbound and Outbound SMS

Contents

Option 1: Set up Digital Channels to use Kaleyra SMS

Prerequisites

Create Digital Channels services definitions

Adding sender IDs to Kaleyra

Manage and provision sender IDs

Option 2: Set up Digital Channels to use a Custom Gateway

Prerequisites

Create Digital Channels services definitions

Manage and provision sender IDs

Add custom HTTP headers

Option 3: Set up Digital Channels to use Genesys Cloud CX SMS Aggregation

Prerequisites

Request a Genesys Cloud CX organization

Create the Digital Channels integration in Genesys Cloud CX

Create a Digital Channels API key for Genesys Cloud CX

Create Digital Channels services definitions

Manage provision sender IDs

Retrieve the Genesys Cloud CX token

List purchased and registered numbers

Search for available toll free-number

Order a toll-free number number

Provision sender IDs in Digital Channels