Configure BYO SMS for Twilio

Prerequisites
  • Genesys Cloud CX 1 Digital Add-on II, Genesys Cloud CX 2, Genesys Cloud CX 2 Digital, Genesys Cloud CX 3, or Genesys Cloud CX 3 Digital license

The following permissions:

  • Integrations > Integration > Add
  • Integrations > Integration > Delete
  • Integrations > Integration > Edit
  • Integrations > Integration > View
  • SMS > phoneNumber > All 

If you have an existing relationship with Twilio for SMS services, you can use the Bring Your Own (BYO) SMS feature to integrate your existing Twilio account into Genesys Cloud. You can then send and receive SMS messages with your customers using all the Genesys Cloud SMS capabilities.

Note: If you are an indirect Genesys Cloud customer, you must work directly with your partner organization to set up BYO SMS for Twilio.

For BYO SMS pricing, see Genesys Cloud fair use policy.

Provision SMS Numbers with Genesys Cloud inbound Webhook

Before you can add your Twilio SMS numbers to your BYO SMS Twilio integration, you must provision your SMS numbers to use the Genesys Cloud inbound Webhook.  To do so, you provision the appropriate Genesys Cloud Webhook URL for your region on each SMS number. For more information, see the Webhooks article in Twilio Docs.

Configuring Webhooks for 10DLC numbers

If you are using US 10DLC numbers, which have been registered, then you may discover that Twilio places those numbers in a Messaging Service. In this case, Genesys recommends that you select the Defer to sender’s webhook option in the webhook configuration for the Messaging Service and provision your SMS numbers to use the Genesys Cloud inbound Webhook.

Region-specific Genesys Cloud Webhook URLS

US East (N. Virginia)

https://byosms.mypurecloud.com/vendors/v1/twilio/a906d2848ad146028e8805a8bbaa24d3/mo 

US East (Ohio)

https://byosms.use2.us-gov-pure.cloud/vendors/v1/twilio/60b5013a2511482999b30b6db5ec67d8/mo 

US West (Oregon)

https://byosms.usw2.pure.cloud/vendors/v1/twilio/b1adfe3a944c428bbc65d953bb8629b2/mo

Canada (Canada Central)

https://byosms.cac1.pure.cloud/vendors/v1/twilio/1190471d172842c283dc5376a92df73d/mo

South America (Sao Paulo)

https://byosms.sae1.pure.cloud/vendors/v1/twilio/44e8a8cd75f849b18ab6fc8bbad9a057/mo

Europe (Frankfurt)

https://byosms.mypurecloud.de/vendors/v1/twilio/3d904439dc3f4eceb2e574b43c8f5ac5/mo

Europe (Ireland)

https://byosms.mypurecloud.ie/vendors/v1/twilio/a123cbc6467b48ccbdccc3e03fd30f4d/mo

Europe (London)

https://byosms.euw2.pure.cloud/vendors/v1/twilio/f5c59e8b3a1345739ebd4564a340e526/mo

Europe (Zurich)

https://byosms.euc2.pure.cloud/vendors/v1/twilio/FhcOBGsMEALrQfWsxH1LQy39tzI3F3qk/mo  

Middle East (UAE)

https://byosms.mec1.pure.cloud/vendors/v1/twilio/N1aXOj92NXNBA21KqdkZfA3kFjdmAM2B/mo

Asia Pacific (Osaka)

https://byosms.apne3.pure.cloud/vendors/v1/twilio/yXaIsznST36qG0qy7UAP4mWlsHDHh0E0/mo

Asia Pacific (Seoul)

https://byosms.apne2.pure.cloud/vendors/v1/twilio/2e58f741f7a547b49c15c64dfb305361/mo

Asia Pacific (Sydney)

https://byosms.mypurecloud.com.au/vendors/v1/twilio/97b4889e04514098a34715f0c216bf7b/mo

Asia Pacific (Tokyo)

https://byosms.mypurecloud.jp/vendors/v1/twilio/b7c9a0818bc343379513f713247b56ce/mo

Asia Pacific (Mumbai)

https://byosms.aps1.pure.cloud/vendors/v1/twilio/b462e102a5414620bc6f002bc561595d/mo

Warnings:
  • If a Twilio number does not have a webhook URL set up before you try to import, Genesys Cloud rejects the import request.
  • Genesys Cloud’s BYO SMS does not support Twilio’s secondary AuthTokens option.

Genesys Cloud’s BYO SMS does not support the secondary AuthTokens option because Twilio implicitly uses the primary Authtoken supplied with inbound SMS/MMS messages. Unfortunately, this implicit use causes a failure when Genesys Cloud attempts to validate the AuthToken. As an alternative, Genesys suggests using a Twilio Subaccount for your BYO SMS integration. For more information, see Twilio’s Getting Started with Twilio Accounts and Subaccounts article.

Set up the BYO Twilio SMS integration

To set up the BYO Twilio SMS integration, perform these steps:

  1. Click Admin.
  2. Under Integrations, click Integrations.
  3. Click Integrations.
  4. Locate the Bring Your Own Twilio SMS Account Configuration tile.
  1. Go to the Genesys AppFoundry.
  2. Search for the BYO Twilio SMS integration.
  3. To add the BYO Twilio SMS integration to your Genesys Cloud organization, follow the instructions.

  1. Click Install. The Bring Your Own Twilio SMS Account Configuration screen appears.
  2. (Optional) On the Details tab, customize the name of your integration and add notes.
    Note: Genesys recommends that you use the name and notes to identify the Twilio account you are using.
  3. Click the Configuration tab.
  4. Click the Credentials tab.
  5. Click Configure. The Configure Credentials dialog box appears.
  6. In the Account SID box, type the SID for your Twilio account. 
  7. In the Authorized Token box, type the Authorized Token for your Twilio account.
    Note: Genesys Cloud encrypts your Twilio credentials and stores them in a secure environment. For more information, see How does Genesys Cloud handle credentials?.
  8. Click OK.
  9. Click Save.
  10. Set the Status to Active.

Add your numbers to the SMS Number Inventory

After you set up your BYO Twilio 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 Twilio account and you can still use them for voice interactions in Twilio.

To add your SMS numbers, perform these steps:

  1. Click Admin.
  2. Under Message, click SMS Number Inventory.
  3. When the SMS Number Inventory page appears, click Add numbers.
  4. Click Import. The Import Number dialog appears.
  5. From the Integration list, select the integration from which you want to import numbers.
  6. From the Type list, select the type of number you are importing.
    • If you select Local, Mobile, or Toll-free:
      • In the Sender ID box, type a number using the E164 format.
    • If you select Shortcode:
      • From the Country list, select the country.
      • In the Sender ID box, type a number.
  7. Click Next.
  8. If you select Shortcode from the Type list, the Required interaction dialog appears and you must fill in the information on each of the three tabs.
    • On the Help tab:
      • 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.
    • On the Opt-out tab:
      • 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.
    • On the Re Opt-in tab:
      • 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.
  9. 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.

Deactivating a Twilio SMS integration in Genesys Cloud is temporary. When you deactivate an integration, all numbers imported for this integration are disabled in the SMS Number Inventory. However, while any inbound messages transfer from Twilio to Genesys Cloud, they are dropped. In other words, they will not route to any queues you set up.

If you do not want inbound messages and delivery reports to be sent from Twilio to Genesys Cloud while the integration is deactivated, change the webhooks for the numbers to something other than the Genesys Cloud Webhook URL.

Notes:
  • Deactivating a Twilio SMS integration in Genesys Cloud does not deactivate the numbers in your Twilio account.
  • If you later decide to reactivate the Twilio SMS integration, change the webhook URL back to the Genesys Cloud webhook URL.

For more information about the Twilio console, see Twilio’s Webhooks article. For more information about how to deactivate an integration, see Edit, deactivate, or delete an integration.

Warning: Deleting a Twilio SMS integration removes all imported numbers from the SMS Number Inventory without regard for active inbound flows or queue configurations.

When you delete a BYO SMS Twilio integration in Genesys Cloud, you should change the Inbound Webhook URL for every number in your Twilio console back to its original configuration. If you do not change the Webhook URL, inbound messages will continue to route to Genesys Cloud, where those messages will be dropped. The messages do not route to any queues you set up.

Note: Deleting a Twilio SMS integration in Genesys Cloud does not delete the numbers from your Twilio account. It only removes your ability to use the numbers in Genesys Cloud.

For more information about the Twilio console, see Twilio’s Webhooks article. For more information about how to delete an integration, see Edit, deactivate, or delete an integration.

If you receive an error while you integrate your existing Twilio account into Genesys Cloud, use this table to find out more information.

Note: If you encounter problems with the delivery of SMS messages, you need to work directly with Twilio.

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:

  • 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 five and six 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.
This phone number cannot be found with the vendor. This message appears when the phone number does not exist in the Twilio subaccount.