Configure BYO SMS for SMPP
- Genesys Cloud CX 2, Genesys Cloud CX 3, Genesys Cloud CX 4, Genesys Cloud CX 2 Digital, Genesys Cloud CX 3 Digital, or Genesys Cloud CX 1 Digital Add-on II license
- Integrations > Integration > Add, Delete, Edit, and View permissions
- SMS > phoneNumber > All permissions
- Vendor provided connection properties to configure the Short Message Peer to Peer (SMPP) Short Messaging Service (SMS) integration
- Genesys Cloud Internet Protocol (IP) addresses added to the vendor allowlist available in Step 4: Save your configuration section in this article.
- Vendor allows Genesys Cloud to establish three SMPP binds, which is the default binds count and currently non-configurable
Use the Bring Your Own (BYO) SMS feature to connect your existing Short Message Peer-to-Peer (SMPP) account to Genesys Cloud. If your SMS provider supports an SMPP interface, you can integrate it and start sending and receiving SMS messages with customers using Genesys Cloud’s full SMS capabilities.
For BYO SMS pricing, see Genesys Cloud fair use policy.
Notes:
- If you are an indirect Genesys Cloud customer, you must work directly with your partner organization to set up BYO SMS for SMPP.
- Ensure that the Genesys Cloud IP addresses are added to the vendor allowlist. See vendor allowlist available in Step 4: Save your configuration section in this article.
- Genesys Cloud BYO SMS for SMPP does not support:
- Virtual Private Network (VPNs). We require customers to use Transport Layer Security (TLS) encryption instead.
- Multimedia Messaging Service (MMS).
- Alphanumeric sender identification (IDs). For more information, see SMS delivery receipts.
- Bandwidth as a BYO SMS provider. A platform control within Bandwidth prevents the provisioning of public IP addresses across multiple accounts. Genesys Cloud will provide updates when a solution is available.
- Genesys Cloud expects that delivery reports are received for each segment for delivery tracking of concatenated messages.
- As a customer, ensure that you work with your SMS provider to complete any required use case registration.
- Genesys Cloud requires ownership of SMS keyword compliance functions, regardless of the customer’s chosen messaging provider. SMS keyword compliance functions include:
- Managing and processing compliance keywords (for example: HELP, STOP).
- Sending mandatory auto-responses.
- Ensuring that all opt-out requests are processed.
Set up the BYO SMPP SMS integration
To set up the BYO SMPP SMS integration, perform these steps:
- Click Admin.
- Under Integrations, click Integrations.
- Click Admin > IT and Integrations > Integrations.
- Click Integrations.
- Locate the Bring Your Own SMPP Configuration tile. If you already use the BYO Twilio integration, proceed to install your integration. If you do not see the SMPP SMS account configuration tile, you must add it. To add the SMPP SMS account configuration tile, perform the following steps:
- Go to the Genesys AppFoundry.
- Search for the Bring Your Own SMS account.
- To add the BYO SMPP SMS integration to your Genesys Cloud organization, follow the instructions provided in this section and proceed accordingly.
- Click Install. The Bring Your Own SMPP Configuration screen is displayed.
You can now proceed with the configuring and managing your BYO SMPP SMS integration.
Configure and manage your BYO SMPP SMS integration
Configure your BYO SMPP SMS integration
To configure your BYO SMPP integration, perform the following steps:
In the Details tab, enter the name of your integration and add notes. Genesys Cloud recommends that you use meaningful names and notes to identify your SMPP accounts.
Click each tab for more information.
The Configuration tab displays the Properties tab by default. Add relevant details for your SMPP vendor. Define the properties for the following fields:
- In the SMSC Address field, enter the host name or IP address of your vendor SMSC.
- In the Inbound plus prefix field, indicate whether your vendor includes a leading + on the source addresses (not the mobile handset number) for inbound (Mobile Originated) messages. The values are:
- True
- False
- In the Outbound plus prefix field, indicate whether your vendor requires a leading + on the source addresses for outbound (Mobile Terminated) messages. The values are:
- True
- False (This is the default selection.)
- In the SMSC Port field, enter the port details to connect to your vendor SMSC. The default value is 2776, which is the conventional encrypted port for SMPP over TLS. Genesys Cloud recommends that you use the default port value. Genesys Cloud supports the following additional ports: 1776, 2775, 2776, 3550, 3601, 4200, 7777, 8887, and 10000. Note: If you don’t see your port in the list, you can request a custom port value by submitting a request with Genesys Cloud My Support. However, the request can take 3–4 weeks to implement.
- In the Address TON field, select the Type Of Number (TON). You can select values 0–6. Zero is the default value. This applies to the phone number that an outbound message is sent from.
- In the Address NPI field, select the Numbering Plan Identification (NPI) value. You can select values any of these values: 0,1,3,4,6,8,9,10,13,18. Zero is the default value. This applies to the phone number that an outbound message is sent from.
- In the Default destination address TON field, select the required value. You can select values 0–6. Zero is the default value. This applies to the phone number that an outbound message is sent to.
- In the Default destination address NPI field, select a value for the numbering plan identification. You can select any of these values: 0,1,3,4,6,8,9,10,13,18. Zero is the default value. This applies to the phone number that an outbound message is sent to.
- In the Messages per second field, enter the required value. The default value is 20 messages per second with a maximum limit of 100 messages per second.
- In the Bind Type field, select the type. The types available for selection are:
- Transceiver: This is the default and recommended selection.
- Transmitter: If you select this option, ensure that you have a receiver bind to receive delivery reports and mobile originated messages. If you do not have a receiver, you cannot receive delivery reports and mobile originated messages.
- Receiver
In the Advanced Configuration section, enter the charset encoding details for your SMPP vendor or the error codes for your SMPP vendor. You can choose to leave this section blank and can use the default configuration.
{
"protocolSpecificCodeMapping": {
"0": {
"genericErrorCode": 0,
"genericErrorCause": "DELIVERED",
"description": "Message delivered"
},
"1" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "Message length is invalid"
},
"2" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "Command length is invalid"
},
"3": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "Invalid command ID"
},
"4": {
"genericErrorCode": 2,
"genericErrorCause": "OTHER_TEMPORARY_FAILURE",
"description": "Incorrect carrier status for given command"
},
"5": {
"genericErrorCode": 2,
"genericErrorCause": "OTHER_TEMPORARY_FAILURE",
"description": "Incorrect carrier status for given command"
},
"6": {
"genericErrorCode": 3,
"genericErrorCause": "PRIORITY_INVALID",
"description": "Invalid priority flag"
},
"7": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "Invalid registered delivery flag"
},
"8": {
"genericErrorCode": 2,
"genericErrorCause": "OTHER_TEMPORARY_FAILURE",
"description": "Internal system error"
},
"10" : {
"genericErrorCode": 3,
"genericErrorCause": "SOURCE_ADDR_INVALID",
"description": "Invalid source address"
},
"11" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "Invalid destination address"
},
"12" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_ID_INVALID",
"description": "Invalid message ID"
},
"13" : {
"genericErrorCode": 2,
"genericErrorCause": "OTHER_TEMPORARY_FAILURE",
"description": "Bind failed"
},
"14" : {
"genericErrorCode": 2,
"genericErrorCause": "AUTHENTICATION_FAILED",
"description": "Invalid password"
},
"15" : {
"genericErrorCode": 2,
"genericErrorCause": "AUTHENTICATION_FAILED",
"description": "Invalid system ID"
},
"17" : {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RCANCELFAIL: Cancel SM failed."
},
"19" : {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RREPLACEFAIL: Replace SM failed."
},
"20" : {
"genericErrorCode": 2,
"genericErrorCause": "CARRIER_CONGESTED",
"description": "ESME_RMSGQFUL: Message queue full."
},
"21" : {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RINVSERTYP: Invalid service type."
},
"51" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RINVNUMDESTS: Invalid number of destinations."
},
"52": {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RINVLDLNAME: Invalid distribution list name."
},
"64" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RINVDESTFLAG: Destination flag is invalid (submit_multi)."
},
"66": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVSUBREP: Invalid 'submit with replace' request (i.e. submit_sm with replace_if_present_flag set)."
},
"67" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVESMCLASS: Invalid esm_class field data."
},
"68" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RCNTSUBDL: Cannot submit to distribution list."
},
"69": {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RSUBMITFAIL: submit_sm or submit_multi failed."
},
"72" : {
"genericErrorCode": 3,
"genericErrorCause": "SOURCE_ADDR_INVALID",
"description": "ESME_RINVSRCTON: Invalid source address TON."
},
"73" : {
"genericErrorCode": 3,
"genericErrorCause": "SOURCE_ADDR_INVALID",
"description": "ESME_RINVSRCNPI: Invalid source address NPI."
},
"80" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RINVDSTTON: Invalid destination address TON."
},
"81" : {
"genericErrorCode": 3,
"genericErrorCause": "DEST_ADDR_INVALID",
"description": "ESME_RINVDSTNPI: Invalid destination address NPI."
},
"83": {
"genericErrorCode": 3,
"genericErrorCause": "AUTHENTICATION_FAILED",
"description": "ESME_RINVSYSTYP: Invalid system_type field."
},
"84" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVREPFLAG: Invalid replace_if_present flag."
},
"85" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVNUMMSGS: Invalid number of messages."
},
"88" : {
"genericErrorCode": 2,
"genericErrorCause": "THROTTLED",
"description": "ESME_RTHROTTLED: Throttling error(ESME has exceeded allowed message limits)."
},
"97" : {
"genericErrorCode": 3,
"genericErrorCause": "TIME_PERIOD_INVALID",
"description": "ESME_RINVSCHED: Invalid scheduled delivery time."
},
"98" : {
"genericErrorCode": 3,
"genericErrorCause": "TIME_PERIOD_INVALID",
"description": "ESME_RINVEXPIRY: Invalid message validity period (expiry time)."
},
"99" : {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVDFTMSGID: Predefined message invalid or not found."
},
"100": {
"genericErrorCode": 2,
"genericErrorCause": "OTHER_TEMPORARY_FAILURE",
"description": "ESME_RX_T_APPN: ESME receiver temporary app error code."
},
"101": {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RX_P_APPN: ESME receiver permanent app error code."
},
"102": {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RX_R_APPN: ESME receiver reject message error code."
},
"103": {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RQUERYFAIL: query_sm request failed."
},
"192": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVOPTPARSTREAM: Error in the optional part of the PDU body."
},
"193": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_ROPTPARNOTALLWD: Optional parameter not allowed."
},
"194": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVPARLEN: Invalid parameter length."
},
"195": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RMISSINGOPTPARAM: Expected optional parameter missing."
},
"196": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "ESME_RINVOPTPARAMVAL: Invalid optional parameter value."
},
"254": {
"genericErrorCode": 2,
"genericErrorCause": "CARRIER_DELIVERY_FAILED",
"description": "ESME_RDELIVERYFAILURE: Delivery failure (used for data_sm_resp)."
},
"255": {
"genericErrorCode": 3,
"genericErrorCause": "OTHER_PERMANENT_FAILURE",
"description": "ESME_RUNKNOWNERR: Unknown error."
}
},
"charsets": [
{
"dcs": 0,
"charset": "gsm_0338"
},
{
"dcs": 1,
"charset": "ASCII"
},
{
"dcs": 2,
"charset": "gsm_0338"
},
{
"dcs": 3,
"charset": "ISO-8859-1"
},
{
"dcs": 5,
"charset": "JIS0201"
},
{
"dcs": 6,
"charset": "ISO-8859-5"
},
{
"dcs": 7,
"charset": "ISO-8859-8"
},
{
"dcs": 8,
"charset": "utf-16be"
}
]
}
When you enter a custom advanced configuration, it overrides the default values for the custom error codes, while keeping any defaults that have not been overridden. A custom advanced configuration must be a valid JSON object, and follow the proper schema.
{
"protocolSpecificCodeMapping": {
"0": {
"genericErrorCode": 0,
"genericErrorCause": "DELIVERED",
"description": "Message delivered"
},
"1": {
"genericErrorCode": 3,
"genericErrorCause": "MESSAGE_DATA_INVALID",
"description": "Message length is invalid"
}
},
"charsets": [
{
"dcs": 0,
"charset": "gsm_0338"
},
{
"dcs": 1,
"charset": "ASCII"
}
]
}
The following table describes the two sections in the advanced configuration tab:
| Section name | Description |
|---|---|
| protocolSpecificCodeMapping | Use this section to map your vendor error code to a generic error that Genesys Cloud can further interpret.
|
| charsets | Use this section for an ordered list of charset preferences. You can use this to encode a message before sending it to the vendor SMSC. If a message cannot be encoded with the first charset in the list, the next charset is used, and so on. Examples of charsets are as follows:
|
In the Credentials tab, click Configure. The Configure Credentials dialog box appears. Perform the following steps:
- In the System ID box, type the system ID for your SMPP account.
- In the Password box, type the password for your SMPP account. Note: Genesys Cloud encrypts your SMPP credentials and stores them in a secure environment. For more information, see How does Genesys Cloud handle credentials?
- Click OK.
After you complete the fields in your integration, click Save to save your configuration.
If the Save button is not available for selection, then check with your vendor if they maintain an IP allowlist. Add the Genesys Cloud IP addresses from which SMPP bind requests originate to that allowlist. To get a list of the IP addresses, perform the following steps:
- Navigate to the API central.
- In the upper right corner of the page, click the Account Selection drop-down.
- Click Add Account and select the region of your Genesys Cloud organization.
- On the left panel, click API Resources.
- From the list, select Utilities.
- Click GET /api/v2/ipranges.
- On the right side of the page, turn off the Reading mode is enabled toggle to switch out of reading mode.
- Click Execute Request.
- The Responses section is displayed. You can view the IP addresses from which you can perform and locate the byo-smpp services IP addresses. For more information, see IP addresses for the firewall allowlist.
Once you have completed all the above steps, you can finally activate your integration. To activate your integration, at the bottom of the page, click Active.
Genesys Cloud tries to establish an SMPP bind using the vendor properties used when configuring the integration. Expect a 15-minute wait time for the bind to be tested and established. If there was unsuccessful binding and connection failures, see the Troubleshooting and Operational Console section in this article. Once you are on the Operational Console, look for the events defined in the Developer Center.
If you encounter problems with integration, you must work directly with your vendor.
Note: You can create a maximum of 10 BYO SMPP integrations. To set up an active-active connection to your vendor’s redundant SMSC, create a separate integration for each connection.
Manage your BYO SMPP SMS integration
Once your integration is ready, you can add your numbers to the SMS number inventory, update, deactivate, or delete your integrations. Click each collapsible for more information.
After you set up your SMPP SMS integration, you are ready to add your numbers to the SMS Number Inventory. You can only add one number at a time.
Note: Adding your numbers to the SMS Number Inventory does not affect your control of these numbers. Essentially, you permit Genesys Cloud to use those numbers for SMS. The numbers remain in your provider’s account.
To add your SMS numbers, perform these steps:
- Click Admin.
- Under Message, click SMS Number Inventory.
- Click Menu > Digital Telephony > Message > SMS Inventory.
- The SMS Number Inventory page appears. Click Add numbers.
- Click Import.
- The Import Number dialog appears. In the Integration list, select the integration from which you want to import numbers.
- In the Type list, select the type of number to import.
- Local, Mobile, or Toll-free: Displays the Sender ID field, which you can use to enter the number using the E164 format. When you import a Local, Mobile, or Toll-Free number, Genesys automatically provisions a standard set of auto-responses for the HELP and STOP keywords.
Default auto response Description Help keywords HELP or INFO. Help auto response Reply STOP to unsubscribe. Msg&Data Rates May Apply. Opt-out keywords CANCEL, END, QUIT, STOP, UNSUBSCRIBE, STOPALL, REVOKE, or OPTOUT. Opt-out auto response You have successfully been unsubscribed. You will not receive any more messages from this number. Reply START to resubscribe. Opt-in keywords START, YES, or UNSTOP. Opt-in auto response You have successfully been resubscribed to messages from this number. Reply HELP for help. Reply STOP to unsubscribe. Msg&Data Rates May Apply. - Shortcode: Displays the Country and Sender ID fields, which you can use to select the country and enter the number using the E164 format.
- Local, Mobile, or Toll-free: Displays the Sender ID field, which you can use to enter the number using the E164 format. When you import a Local, Mobile, or Toll-Free number, Genesys automatically provisions a standard set of auto-responses for the HELP and STOP keywords.
- Click Next.
- In the Type list, if you had selected Shortcode as the type, it displays the Required Interaction dialog box. The dialog box displays the following tabs:
- In the Help tab, do the following:
- In the Keywords box, enter the help keywords you want to use.
- In the Message box, enter the message that you want to send to customers in response to a help request.
- In the Opt-out tab, do the following:
- In the Keywords box, enter the opt-out keywords you want to use.
- In the Message box, enter the message that you want to send to customers in response to an opt-out request.
- In the Re Opt-in tab, do the following:
- In the Keywords box, enter the opt-in keywords you want to use.
- In the Message box, enter the message that you want to send to customers in response to an opt-in request.
- In the Help tab, do the following:
- Click Confirm import. Genesys Cloud retrieves the SMS number data and then returns you to the SMS Number Inventory page. A toast appears at the top of the page telling you that the number import was successful.
For more information, see Manage your SMS long code number inventory.
You can change your SMPP SMS integration from the Integration dashboard. To update the integration, perform the following steps:
- From the Integration dashboard, select the integration to which you want to make changes.
- Make the required changes in the Details, Configuration Properties, Advanced, or Credentials tabs.
- Click Save.
Note: If you change the credentials, then you have to reactivate your integration.
- If the integration is in Inactive status, then turn on the toggle to activate the integration.
- If the integration is already in Active status, then turn off the toggle to make it inactive and then change it to Active again.
You can deactivate your SMPP SMS integration from the Integration Dashboard page. To deactivate your integration, perform the following steps:
- On the Integration page, in the Actions column, click the More icon.
- From the options, select Deactivate Integration.
When you deactivate the integration:
- It is done temporarily in Genesys Cloud and all numbers imported for this integration are disabled.
- The SMPP connection is disconnected. This means that no messages can be sent or received. Any messages sent or received are added to the queue and will remain so until the connection is activated.
You can delete your SMPP SMS integration from the Integration Dashboard page. To delete your integration, perform the following steps:
- On the Integration page, in the Actions column, click the More icon.
- From the options, select Delete Integration.
Warning: Deleting an SMPP SMS integration removes all imported numbers from the SMS Number Inventory without regard for active inbound flows or queue configurations.
Note: Deleting an SMPP SMS integration in Genesys Cloud does not delete the numbers from your SMPP account. It only removes your ability to use the numbers in Genesys Cloud.
- Deleting the SMPP SMS integration shuts down the SMPP connection in Genesys Cloud and you will not be able to use it for sending or receiving SMS messages.
- Ensure to remove Genesys Cloud IP addresses.
Troubleshooting
The following table lists common error messages and their descriptions that you might see when integrating your SMPP account with Genesys Cloud.
| Message | Description |
|---|---|
| Please check the Integration for BYO Sender ID. | This message appears when the request is sent to the back-end service and the integration is missing the Sender ID. |
| Please provide the required compliance keywords and messages for your Sender ID. | This message appears when any of the compliance information is missing. Check the fields on the three tabs in the Required interaction dialog box:
|
| Please check your Sender ID type. | This message appears when either the phone number or short code is incorrectly formatted.
|
| Please check your Sender ID country code. | This message appears when the phone number and the country code do not match. |
| A provisioning action is already in progress for this phone number address. | This message appears if you attempt to resubmit a request that is already provisioned. Some numbers take longer to provision. |
| This Phone Number address is not available for provisioning. Please select a different phone number address and try again. | This message appears when the phone number has already been provisioned in another organization. |
Operational console
You can find events relevant on your BYO SMPP integration in the Operational Console. To navigate to the Operational Console, perform the following steps:
- Click Admin.
- Under Troubleshooting, click Operational Console.
- Click Menu > IT and Integrations > Operational Console.
The Operational Console page is displayed.
For more information about the SMS Event Catalog on the operational events that are relevant to BYO SMPP, see the SMS Event Catalog on Developer Center. For more information about using the Operational Console, see Troubleshoot using the Genesys Cloud Operational Console.
If you further encounter problems with integration, you must work directly with your vendor.
[NEXT] Was this article helpful?
Get user feedback about articles.