Configure BYO SMS for SMPP

AI-generated summary

Genesys Cloud provides a Bring Your Own (BYO) SMS feature that enables integration of existing Short Message Peer-to-Peer (SMPP) accounts to send and receive SMS messages using the platform's full SMS capabilities. The integration requires specific licensing (Genesys Cloud CX 2, CX 3, CX 4, or Digital Add-on variants), appropriate permissions for integrations and SMS phone numbers, and vendor-provided SMPP connection properties. Users must ensure Genesys Cloud IP addresses are added to their vendor allowlist and that the vendor supports three SMPP binds, which is the default non-configurable setting. The BYO SMS feature does not support Virtual Private Networks (VPNs), Multimedia Messaging Service (MMS), alphanumeric sender identification, or Bandwidth as a provider; Genesys Cloud requires Transport Layer Security (TLS) encryption versions 1.2 or 1.3 instead. Customers retain responsibility for SMS keyword compliance functions, including managing compliance keywords (HELP, STOP), sending mandatory auto-responses, and processing opt-out requests. Setup involves accessing the Integrations menu, locating or installing the Bring Your Own SMPP Configuration tile from the Genesys AppFoundry, and configuring the integration through Details and Configuration tabs with meaningful naming conventions. Indirect Genesys Cloud customers must coordinate setup through their partner organization. Technical configuration requires specifying the SMSC host address or IP and port (range 1024–65535), with configurable plus prefix settings (True/False values) for source addresses. Type Of Number (TON) and Numbering Plan Identification (NPI) values apply to both outbound message origination and destination addresses, with selectable ranges (TON: 0–6; NPI: 0, 1, 3, 4, 6, 8, 9, 10, 13, 18). Default values are 0 for both parameters. Message throughput is configurable via the Messages per second field, with a default of 20 and maximum of 100 messages per second. Bind Type options include Transceiver (default and recommended), Transmitter (requires separate receiver configuration for delivery reports and mobile-originated messages), and Receiver. Transport Layer Security (TLS) version selection supports TLS v1.2 (default) and v1.3 for connection encryption. An Advanced Configuration section allows optional charset encoding and error code customization, with default configuration available if left blank. Genesys Cloud implements a comprehensive protocol-specific error code mapping system that translates carrier-level error codes into standardized generic error codes and causes for consistent message handling. The system defines error codes ranging from 0 to 255, each mapped to standardized error categories such as DELIVERED, temporary failures, permanent failures, and authentication failures. Specific error conditions include message delivery validation issues (invalid message length, command length, command ID), carrier status problems, authentication failures (invalid password, invalid system ID), address validation errors (invalid source address, destination address, message ID), and operational constraints (message queue full, bind failures). The mapping distinguishes between recoverable temporary failures such as internal system errors and carrier congestion, and non-recoverable permanent failures including invalid service types, failed message cancellations, and failed message replacements. Additional error categories address distribution list operations, destination flag validation, and submit-with-replace request validation. The platform supports eight character encoding schemes mapped to Data Coding Scheme (DCS) values, including GSM 7-bit (0338), ASCII, ISO-8859-1, ISO-8859-5, ISO-8859-8, JIS0201, and UTF-16BE encoding. Custom advanced configurations allow selective override of default error code mappings while preserving non-overridden default values, enabling flexible error handling tailored to specific deployment requirements. Configuration setup requires entering SMPP System ID and password credentials in the Credentials tab, which Genesys Cloud encrypts and stores securely. After completing all configuration fields, users must save the configuration and verify that Genesys Cloud IP addresses are added to the vendor's IP allowlist if one exists; IP addresses can be retrieved via the API central utilities endpoint (GET /api/v2/ipranges). Users activate the integration by setting the status to Active, which initiates an SMPP bind test with an expected 15-minute establishment window. Connection failures should be addressed through the troubleshooting and operational console resources. Genesys Cloud enables management of BYO

PrerequisitesClick to expand

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
All permissions under SMS > phoneNumber
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
A base64-encoded PKCS12 client certificate file and its associated password
A provider that accepts client certificates and trusts the certificate authority (CA) that issued your certificate

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). Genesys requires customers to use Transport Layer Security (TLS) encryption instead. Genesys supports TLS version 1.2 and 1.3.
- 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.
BYO SMS for SMPP optionally supports mutual Transport Layer Security (mTLS). With mTLS, Genesys Cloud presents a client certificate that you provide, and your SMS provider verifies the certificate before accepting the connection. mTLS provides an additional layer of trust beyond standard SMPP connectivity controls. To enable mTLS, follow the steps provided in the Configure your BYO SMPP SMS integration section.

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 Menu > 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:
1. Go to the Genesys AppFoundry.
2. Search for the Bring Your Own SMS account.
3. 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

The following sections describe how to configure and then manage your BYO SMPP integrations.

Configure your BYO SMPP SMS integration

To configure your BYO SMPP integration, perform the following steps:

Step 1: Update the Details tabClick to expand

Step 2: Update the Configuration tabClick to expand

Click each tab for more information.

Properties tab
Advanced tab

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 Enable mTLS field, indicate whether you are using mTLS for integration. The values are:
- True, mTLS is used for integration.
- False, standard TLS is used for integration.
  Note: If you select True without adding an mTLS client certificate credential, the integration enters an error state and cannot connect. If you select False and add an mTLS client certificate credential, the integration uses standard TLS and ignores the certificate.
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 to connect to your vendor SMSC. Genesys Cloud allows for usage of ports in the 1024 to 65535 range.
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 TLS Version field, select the Transport Layer Security (TLS) version for the SMPP connection. The available values are TLS v1.2 and v1.3. The default value is version 1.2. To use mTLS, you must select TLS v1.2.

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.

Default error codes and charsets that are usedClick to expand

{
  "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.

Sample JSON object that follows the proper schemaClick to expand

{
  "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. Keys: The error codes that you enter in this map should correspond to your vendor error codes. Values: The values you enter in this map should be objects with fields for genericErrorCode, genericErrorCause, and a description (optional). The value you enter in the genericErrorCode field should be a number from this list: 0 – Success 1 – Unknown failure 2 – Retryable failure 3 – Permanent failure 4 – Expired 5 – Deferred 6 – Enroute 7 – Rejected 8 – Accepted 9 – Unknown 10 – Undeliverable. The value you enter in the genericErrorCause field should be from this list of delivery receipts.
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: GSM_0338 ISO-8859-1 UTF-16be ASCII JIS0201 ISO-8859-5 ISO-8859-8

Section name

Description

protocolSpecificCodeMapping

Use this section to map your vendor error code to a generic error that Genesys Cloud can further interpret.

Keys: The error codes that you enter in this map should correspond to your vendor error codes.
Values: The values you enter in this map should be objects with fields for genericErrorCode, genericErrorCause, and a description (optional).
- The value you enter in the genericErrorCode field should be a number from this list:
  - 0 – Success
  - 1 – Unknown failure
  - 2 – Retryable failure
  - 3 – Permanent failure
  - 4 – Expired
  - 5 – Deferred
  - 6 – Enroute
  - 7 – Rejected
  - 8 – Accepted
  - 9 – Unknown
  - 10 – Undeliverable.
- The value you enter in the genericErrorCause field should be from this list of delivery receipts.

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:

GSM_0338
ISO-8859-1
UTF-16be
ASCII
JIS0201
ISO-8859-5
ISO-8859-8

Step 3: Update the Credentials tabClick to expand

Standard TLS: add your SMPP credentialsClick to expand

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.

mTLS (optional): Add your client certificateClick to expand

Use this option if your SMS provider requires mutual TLS (mTLS). mTLS is optional. On the Credentials tab, in the SMPP mTLS client certificate section, click Configure. The Configure Credentials dialog box appears. Perform the following steps:

In the PKCS12 Keystore (Base64) box, paste the Base64-encoded content of your PKCS12 file. The file contains the client private key and certificate, and optionally the certificate chain, that Genesys Cloud presents to your SMSC during mTLS.
In the Keystore Password box, type the password that unlocks the PKCS12 keystore.
In the Confirm Keystore Password box, type the password again.
Click Confirm.

Note:

Genesys Cloud encrypts your certificate and password and stores them securely. You can’t view them after you save. For more information, see How does Genesys Cloud handle credentials?
Genesys Cloud does not validate your certificate when you save. If the certificate or password is incorrect, expired, or not trusted by your provider, the integration enters an error state after you activate it. For more information, see the Manage your mTLS certificate credentials section below for more details. The integration is successful only after the connection is fully established and the integration is active.

Step 4: Save your configurationClick to expand

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.

Step 5: Set your configuration status to ActiveClick to expand

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.

Add your numbers to the SMS number inventoryClick to expand

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.

List of default auto responsesClick to expand

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 shortcode.

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

Update an SMPP SMS integrationClick to expand

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.
Update your mTLS certificate credentials: You can update your mTLS certificate at any time. Follow the steps in Step 3: Update the Credentials tab, and save your changes. Genesys Cloud applies the new certificate when you reactivate the integration.
Notes: Saving credential or configuration changes applies them to the live connection.
- If you update the certificate for an integration that already uses mTLS, an incorrect, expired, or untrusted certificate or an incorrect password can cause the integration to enter an error state and interrupt messaging traffic. Verify the certificate and password before you save your changes.
- If you change an existing standard TLS integration to use mTLS, update the configuration properties as needed. For example, verify that the SMSC Address and SMSC Port are correct for the mTLS connection.
To avoid interrupting live traffic, consider testing the certificate and configuration on a separate BYO SMPP integration first. After you verify that the credentials and configuration are correct, disable or delete the test integration, and then update the live integration with the verified mTLS credentials and configuration.
Remove your mTLS certificate credentials: If you no longer want to use mTLS, on the Properties tab, set Enable mTLS to False, and then remove the client certificate credential. When you remove the credential, a confirmation dialog box appears. Choose whether to unlink the credential from the integration and retain it, or unlink and delete the credential. The integration then connects using standard TLS.
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.

Deactivate an SMPP SMS integrationClick to expand

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.

Delete an SMPP SMS integrationClick to expand

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.

Manage your mTLS certificate credentialsClick to expand

Genesys Cloud does not manage your mTLS client certificate. You are responsible for obtaining, maintaining, and renewing the certificate. Following are your responsibilities and how to rotate your certificate credentials.

Customer responsibilities

Obtain the certificate: Retrieve the certificate from your organization or SMS provider.
Verify the certificate: Ensure that the certificate is valid and trusted by your SMS provider.
Monitor the expiration date: Track the certificate expiration date to prevent service interruptions.
Rotate the certificate: Renew and replace the certificate before it expires. To update or delete the certificate credentials, see Update an SMPP SMS integration. If you use the same certificate for multiple BYO SMPP integrations, update the certificate credentials for each integration.

If your certificate expires or gets invalid

Genesys Cloud cannot connect if the certificate is expired, not yet valid, unreadable, or protected by a password that does not match the password you provided. In these cases, the integration enters an error state and messaging traffic stops. Genesys Cloud reports the error through an Operational Console event under SMPP connection error event. To restore the connection, update the credential with a valid certificate. If Genesys Cloud reports that the certificate is not yet valid, verify the certificate start date and your system clock settings.

Troubleshooting and operational consoleClick to expand

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: Help Opt-out Re Opt-in
Please check your Sender ID type.	This message appears when either the phone number or short code is incorrectly formatted. The phone number must be in E.164 format. Short code must be between 5-6 characters long.
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.

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 Menu > 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 your BYO SMPP SMS integration

To configure your BYO SMPP integration, perform the following steps:

Step 1: Update the Details tabClick to expand

Step 2: Update the Configuration tabClick to expand

Click each tab for more information.

Properties tab
Advanced tab

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 Enable mTLS field, indicate whether you are using mTLS for integration. The values are:
- True, mTLS is used for integration.
- False, standard TLS is used for integration.
  Note: If you select True without adding an mTLS client certificate credential, the integration enters an error state and cannot connect. If you select False and add an mTLS client certificate credential, the integration uses standard TLS and ignores the certificate.
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 to connect to your vendor SMSC. Genesys Cloud allows for usage of ports in the 1024 to 65535 range.
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 TLS Version field, select the Transport Layer Security (TLS) version for the SMPP connection. The available values are TLS v1.2 and v1.3. The default value is version 1.2. To use mTLS, you must select TLS v1.2.

Default error codes and charsets that are usedClick to expand

{
  "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"
  }
 ]
}

Sample JSON object that follows the proper schemaClick to expand

{
  "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. Keys: The error codes that you enter in this map should correspond to your vendor error codes. Values: The values you enter in this map should be objects with fields for genericErrorCode, genericErrorCause, and a description (optional). The value you enter in the genericErrorCode field should be a number from this list: 0 – Success 1 – Unknown failure 2 – Retryable failure 3 – Permanent failure 4 – Expired 5 – Deferred 6 – Enroute 7 – Rejected 8 – Accepted 9 – Unknown 10 – Undeliverable. The value you enter in the genericErrorCause field should be from this list of delivery receipts.
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: GSM_0338 ISO-8859-1 UTF-16be ASCII JIS0201 ISO-8859-5 ISO-8859-8

Section name

Description

protocolSpecificCodeMapping

Use this section to map your vendor error code to a generic error that Genesys Cloud can further interpret.

Keys: The error codes that you enter in this map should correspond to your vendor error codes.
Values: The values you enter in this map should be objects with fields for genericErrorCode, genericErrorCause, and a description (optional).
- The value you enter in the genericErrorCode field should be a number from this list:
  - 0 – Success
  - 1 – Unknown failure
  - 2 – Retryable failure
  - 3 – Permanent failure
  - 4 – Expired
  - 5 – Deferred
  - 6 – Enroute
  - 7 – Rejected
  - 8 – Accepted
  - 9 – Unknown
  - 10 – Undeliverable.
- The value you enter in the genericErrorCause field should be from this list of delivery receipts.

charsets

GSM_0338
ISO-8859-1
UTF-16be
ASCII
JIS0201
ISO-8859-5
ISO-8859-8

Step 3: Update the Credentials tabClick to expand

Standard TLS: add your SMPP credentialsClick to expand

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.

mTLS (optional): Add your client certificateClick to expand

In the PKCS12 Keystore (Base64) box, paste the Base64-encoded content of your PKCS12 file. The file contains the client private key and certificate, and optionally the certificate chain, that Genesys Cloud presents to your SMSC during mTLS.
In the Keystore Password box, type the password that unlocks the PKCS12 keystore.
In the Confirm Keystore Password box, type the password again.
Click Confirm.

Note:

Genesys Cloud encrypts your certificate and password and stores them securely. You can’t view them after you save. For more information, see How does Genesys Cloud handle credentials?
Genesys Cloud does not validate your certificate when you save. If the certificate or password is incorrect, expired, or not trusted by your provider, the integration enters an error state after you activate it. For more information, see the Manage your mTLS certificate credentials section below for more details. The integration is successful only after the connection is fully established and the integration is active.

Step 4: Save your configurationClick to expand

After you complete the fields in your integration, click Save to save your configuration.

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.

Step 5: Set your configuration status to ActiveClick to expand

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.

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.

Add your numbers to the SMS number inventoryClick to expand

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.

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.

List of default auto responsesClick to expand

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 shortcode.

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

Update an SMPP SMS integrationClick to expand

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.
Update your mTLS certificate credentials: You can update your mTLS certificate at any time. Follow the steps in Step 3: Update the Credentials tab, and save your changes. Genesys Cloud applies the new certificate when you reactivate the integration.
Notes: Saving credential or configuration changes applies them to the live connection.
- If you update the certificate for an integration that already uses mTLS, an incorrect, expired, or untrusted certificate or an incorrect password can cause the integration to enter an error state and interrupt messaging traffic. Verify the certificate and password before you save your changes.
- If you change an existing standard TLS integration to use mTLS, update the configuration properties as needed. For example, verify that the SMSC Address and SMSC Port are correct for the mTLS connection.
To avoid interrupting live traffic, consider testing the certificate and configuration on a separate BYO SMPP integration first. After you verify that the credentials and configuration are correct, disable or delete the test integration, and then update the live integration with the verified mTLS credentials and configuration.
Remove your mTLS certificate credentials: If you no longer want to use mTLS, on the Properties tab, set Enable mTLS to False, and then remove the client certificate credential. When you remove the credential, a confirmation dialog box appears. Choose whether to unlink the credential from the integration and retain it, or unlink and delete the credential. The integration then connects using standard TLS.
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.

Deactivate an SMPP SMS integrationClick to expand

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.

Delete an SMPP SMS integrationClick to expand

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.

Manage your mTLS certificate credentialsClick to expand

Customer responsibilities

Obtain the certificate: Retrieve the certificate from your organization or SMS provider.
Verify the certificate: Ensure that the certificate is valid and trusted by your SMS provider.
Monitor the expiration date: Track the certificate expiration date to prevent service interruptions.
Rotate the certificate: Renew and replace the certificate before it expires. To update or delete the certificate credentials, see Update an SMPP SMS integration. If you use the same certificate for multiple BYO SMPP integrations, update the certificate credentials for each integration.

If your certificate expires or gets invalid

Troubleshooting and operational consoleClick to expand

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: Help Opt-out Re Opt-in
Please check your Sender ID type.	This message appears when either the phone number or short code is incorrectly formatted. The phone number must be in E.164 format. Short code must be between 5-6 characters long.
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.

If you further encounter problems with integration, you must work directly with your vendor.

Configure BYO SMS for SMPP

Set up the BYO SMPP SMS integration

Configure and manage your BYO SMPP SMS integration

Configure your BYO SMPP SMS integration

Manage your BYO SMPP SMS integration

[NEXT] Was this article helpful?

Loading...

Configure BYO SMS for SMPP

Set up the BYO SMPP SMS integration

Configure and manage your BYO SMPP SMS integration

Configure your BYO SMPP SMS integration

Manage your BYO SMPP SMS integration

[NEXT] Was this article helpful?