Twilio SMS Integration

Prev Next

Connecting your Rocket.Chat workspace with SMS allows external users to easily communicate with your support team through text messages. This powerful integration extends Rocket.Chat's Omnichannel capabilities, enabling your customers to reach out via their preferred method, directly enhancing customer service and accessibility.

While Rocket.Chat supports various SMS providers, this guide focuses on configuring SMS integration specifically using the Twilio Programmable Messaging API.

Step 1. Configure your Twilio account

Follow these steps to prepare your Twilio account:

  1. Sign up for a Twilio account or log in to your existing account.

  2. Acquire a number:

    1. From your Twilio Console dashboard, navigate to Phone Numbers > Manage > Buy a number.

    2. Search for a number with SMS capabilities in your desired region.

    3. Follow the prompts to purchase and provision the number.

Twilio might automatically provision a number for new trial accounts. If this happens, you can skip purchasing a new one and proceed with the automatically provisioned number.

Step 2. Connect Twilio to Rocket.Chat

Follow these steps in your Twilio Console:

  1. From your Twilio console dashboard, go to Phone Numbers > Manage > Active Numbers. You will see a list of your Twilio provisioned phone numbers.

  2. Click on the specific Twilio phone number that you wish to use for this integration. This will open its configuration page.

  3. On the number's configuration page, scroll down to the "Messaging Configuration" section. Under the heading "A message comes in”, locate the field for the Webhook URL. Ensure the dropdown next to this field is set to Webhook.

  4. In the Webhook URL field, enter the full URL of your Rocket.Chat workspace's SMS incoming endpoint. This URL follows a specific format: https://<YOUR_ROCKETCHAT_SERVER_URL>/api/v1/livechat/sms-incoming/twilio. Replace <YOUR_ROCKETCHAT_SERVER_URL> with the actual public URL of your Rocket.Chat workspace.

  5. Ensure the dropdown next to the Webhook URL field is set to HTTP POST.

  6. Click the "Save configuration" button to apply your settings.

Step 3. Configure SMS settings in Rocket.Chat

Follow these steps within your Rocket.Chat workspace:

  1. Go to Administration > Workspace > Settings > SMS on your Rocket.Chat workspace.

  2. Enable the SMS integration by toggling the Enabled switch. From the Service dropdown, select Twilio.

  3. On the same page, navigate to the Twilio tab and enter your Account SID and Auth Token in the respective fields. You can find these values in your Twilio account dashboard under the Account info section.

  4. You can Enable or Disable the File Uploads Enabled option. If enabled, specify the Accepted Media Types as comma-separated values (e.g., image/jpeg,image/png,video/mp4,application/pdf). Leave this field blank to accept all media types.

  5. Click the Save changes button to apply your Rocket.Chat SMS settings.

Step 4. Test your Rocket.Chat SMS messaging

Follow these steps to test the integration:

  1. Open any SMS messaging application on your personal mobile phone and send a test message to your Twilio active number. This is the number you configured in Twilio (e.g., the one you purchased or was automatically provisioned).

  2. The message should be received almost instantly on your Rocket.Chat workspace. It will appear as a new Omnichannel conversation, available for any assigned Omnichannel agent to view and continue the conversation.

  3. When a reply is sent from Rocket.Chat, the original sender receives it via SMS.

The green message icon sms is displayed on the side and identifies external SMS messages sent to an Omnichannel department.

Potential issues & Troubleshooting

If the message is not appearing in Rocket.Chat:

  • Double-check that the webhook URL in your Twilio phone number's configuration (section 2, step 4) is exactly correct, including the /api/v1/livechat/sms-incoming/twilio part, and that the method is set to HTTP POST.

  • Verify your Rocket.Chat workspace is publicly accessible.

  • Check your Twilio Programmable Messaging Logs in the Twilio Console (under Monitor > Logs > Messaging). Look for incoming messages to your Twilio number and see if Twilio attempted to deliver them to your webhook URL, and if there were any errors reported by Twilio.

  • Ensure that you have specified an Omnichannel department name in Rocket.Chat's SMS settings. This department is where incoming SMS conversations will be routed. You can find this setting under Administration > Workspace > Settings > SMS, then navigate to the Omnichannel Department (Default) section.