Message Exchange

Table of Contents

  • Overview
  • Prerequisites
  • Federating your UC server
  • Use an already federated XMPP server and XMPP client
  • Setting up your first phone number
    • Setting up a new number
    • Setting up an existing number
  • Creating and XMPP mapping
  • Receiving an SMS/message to your UC client
  • Sending an SMS/message from your UC client
  • Use your custom domain
    • Setting up your custom domain
    • Setting up the new domain
    • Testing the XMPP server using your new custom domain

Overview

Restcomm Message Exchange helps service providers enable their enterprise customers to send and receive SMS using their Unified Communication (UC) client. Enterprise customers can send either two-way SMS or an SMS to multiple destinations.

If you want to use the Restcomm Message Exchange feature, you will need to complete the following steps:

  • Federate your UC server with Restcomm Message Exchange
  • Import an existing phone number (or buy a new one)
  • Create a mapping
  • Start sending messages

Prerequisites

In order to complete the aforementioned steps, you will need:

  • An operational XMPP server on the public internet with valid, CA-issued certificates
  • An open firewall port to your XMPP server, allowing incoming traffic from xmpp.restcomm.com’s IP on port 5269
  • A working knowledge of cURL and a way to make HTTP API calls (either using cURL or Postman; we recommend Postman if you’re not familiar with cURL.)
  • An understanding of how to add and configure phone numbers in Restcomm. Please visit the Getting Started with Your Restcomm Organization Guide, if you are not familiar with the process.
  • An activated Restcomm Cloud account.

Federating your UC server

Federation is the process of establishing a server-to-server connection between your messaging environment and ours. Once this connection is established, the two servers will manage staying connected on their own.

The process of federation is managed by the Telestax Global Support Services (GSS) organization and must be scheduled. Please contact your Telestax sales or GSS representative to schedule your federation interop.

Follow the steps below to federate your server:

  • Add your server’s IP addresses to our Whitelist using the Whitelist API
    Create DNS SRV records on your DNS servers for our Message Exchange server (cloud-xmpp-server.restcomm.com).
  • Ensure your server is on the public internet and has a firewall port open for port 5269
  • Ensure your firewall is allowing incoming traffic from cloud-xmpp-server.restcomm.com’s IP address
  • From a contact on your server, create a new contact and, for the IM address, enter interop@restcomm.com
  • Save the contact record and send a test message to interop@restcomm.com. This will initiate the server federation process. Our technical representatives will verify that federation has been successfully completed.

Use an already federated XMPP server and XMPP client

Restcomm Message Exchange has already been federated with a number of public servers. If you don’t have your own UC server to federate with, you can use XMPP.is and register an account there. If you don’t have a UC client, you are able to utilize any XMPP client. Pidgin and Audium have been successfully tested with Restcomm Message Exchange. You can configure either of those clients with the previously created account from XMPP.is.

Setting up your first phone number

Note: You must have a valid, working Restcomm account in order to complete this step. If you do not have one, you can sign up for one here or contact us.

You can set up your phone number in two different ways, either via the Restcomm Dashboard or via the API. For the purposes of this guide, we will use the Dashboard and will be using a new number rather than an existing number.

Setting up a new number

  • Log in to your Restcomm account
  • Click on Numbers
  • Click on Register Number
  • Navigate to Provider Number on the left side.
  • Enter your country, choose an area code. If you prefer a specific area code, click the Search button on the right side
  • Select a number from the list of displayed numbers and click Register Number
  • Once registration is completed, the number will show up in your Numbers List on the Dashboard.
  • Click on the number. You will then see a screen that looks like the one below::

  • Select RCML URL from the dropdown
  • Enter the value https://cloud-xmpp-service.restcomm.com/xmpp/messages/sms in the text box and leave the right drop-down value as POST
  • Click Save Changes

Setting up an existing number

  • Send a CSV file of all numbers you want to enable for SMS traffic to your Telestax Restcomm Support representative
  • Click on Numbers
  • Click on Register Number
  • In the SIP Address text box, enter your number. If in the US, do not enter a + in front of your number
  • In the Friendly Name text box, enter some identifying name
  • Once registration is completed, the number will show up in your Numbers List on the Dashboard.
  • Click the number. You’ll see a screen that looks like this:

  • Select RCML URL from the dropdown
  • Enter the value https://cloud-xmpp-service.restcomm.com/xmpp/messages/sms in the textbox and leave the right dropdown value as POST
  • Click Save Changes

Creating and XMPP mapping

Once you’ve added your phone number, you’re ready to create an XMPP Mapping. The purpose of an XMPP mapping is to associate a phone number with an existing XMPP contact on your UC server. For example, imagine you have a user with the XMPP address of joe@myserver.com and Joe’s desk phone is +1-919-555-1212.

An XMPP mapping will tell the Restcomm Message Exchange service to send all inbound SMS messages sent to Joe’s number to joe@myserver.com. Additionally, any time Joe sends an outbound SMS from his XMPP account, it will be sent from his phone number.

You will need your Restcomm Account SID and Token for this part of the process. Log in to your Restcomm Console, click on your name in the upper right corner, and select Account.

Let’s create a mapping. For our example, we’re going to use the Restcomm Message Exchange API. You can use Postman or cURL, if you’d prefer.

  • Go to Restcomm Message Exchange API
  • Click on the Authorize button on the right side of the screen.
  • Enter your Restcomm Account SID for the username. This can be found on the Account screen referenced above.
  • For the password, enter your Restcomm Auth Token. This can also be found on the Account screen referenced above.
  • Click Authorize. You’re now ready to create your first mapping.
  • Click on POST from the list of operations on the screen, then click on Try It Out
  • You’ll see an example of the payload in the text box. Modify these values to match your phone number and XMPP address.
  • In the externalAddress field, enter the phone number. As an example, you would enter 19195551212 in the field.. Note that you do not need the +, and there should not be any spaces or dashes included..
  • Either completely remove the domain field or check “Use your own domain” below for how to create and use a custom domain here.
  • Enter your UC address for the value of jabberAddress. For our example, you would enter joe@myserver.com.
  • Click the blue Execute button below the text box.
  • Scroll down to the Server response area of the screen. You should see a code of 200. If this is the case, you’ve successfully created your first mapping!

Receiving an SMS/message to your UC client

Once you’ve completed all of the steps above, you’re ready to test. Login to your UC client as your test user (in our case joe@myserver.com)., Then, using your mobile phone, send a text message to the number you added to Restcomm.

You should then see the message appear in your UC client.

Sending an SMS/message from your UC client

To send an SMS message from your UC client, perform the following steps:

  • Add a contact to your contact list in your UC client as you would normally.
  • In the IM Address field, enter the address in the format of phoneNumber@restcomm.com or, if you have a custom domain, phoneNumber@yourdomain.com. For example, if your cell phone number is 19195551212, then you would enter 19195551212@restcomm.com for the IM Address of the contact.
  • Once the contact is added, send a message from your client to the new contact.
  • Restcomm Message Exchange will convert the message from a UC message to SMS and route it to the number provided.
  • The message will appear on the destination handset.

Use your custom domain

Restcomm message exchange supports usage of custom domains. For example you can use phoneNumber@mycompany.com instead of phoneNumber@restcomm.com

Setting up your custom domain

In order to use your custom domain with Restcomm message exchange, you will need to:

  • Provide a valid certificate obtained by trusted third party organization
    • You should provide a full chain certificate in PEM format, that obtains Root CA and intermediate CAs
  • You have to create a DNS SRV record pointing to Restcomm Message Exchange. For example the DNS SRV record for xmpp.mycompany.com should look like:

_xmpp-server._tcp.xmpp.mycompany.com. 1 1 5269 cloud-xmpp-server.restcomm.com.

Warning: Pay attention to _ or . characters since they are important for DNS SRV records

Important: DNS Records propagation might take some time to complete.

Setting up your domain with GoDaddy

For simplicity, let’s assume your domain is testxmpp.com and for UC-One you use sub-domain text.testxmpp.com. The next step is to make sure you set DNS SRV for your subdomain to point to our XMPP server (cloud-xmpp-server.restcomm.com). Below is a screenshot on how to set up DNS SRV on GoDaddy.

Setting up your SSL certificate with GoDaddy

To begin using white labeling, you must first set up an SSL Certificate for the sub-domain and upload full chain of certificate on Restcomm via Swagger UI. Make sure the order of the SSL Certificate chain is as follows: your domain certificate, your private key, authority issuing your certificate, root certificate.

For simplicity let’s assume your domain is testxmpp.com and for UC-One you are using the following sub-domain: text.testxmpp.com. In the steps below, we will explain how to generate a private key and certificate using OpenSSL.

  • Generate an openssl key (GSS bought a domain on Godaddy text.textxmpp.com)

$ openssl genrsa -out text.testxmpp.com.key 2048

  • Create your CSR or certification request file (notice the password below is just an example, please use your own strong password)

$ openssl req -new -key text.testxmpp.com.key -out text.testxmpp.com.csr

  • Copy the content of the newly created text.testxmpp.com.csr and paste it into the Godaddy CSR enrollment form.
  • When you receive the confirmation, download the certificate zip file from you Godaddy Dashboard

  • The content of the certificate zip file for Tomcat should look like the one below:
  • Combine the certificate from Godaddy with the openssl key you generated in step one

$ cat ‘/home/charles/Downloads/text.testxmpp.com/51e1fbfeeae30fdb.crt’ ‘/home/charles/telestax/text.testxmpp.com.key’ ‘/home/charles/Downloads/text.testxmpp.com/gd_bundle-g2-g1.crt’ > text.testxmpp.combined.pem….

  • The newly created text.testxmpp.combined.pem will contain the certificate you need to create a new domain mapping in Swagger. Copy and paste the content of the combine.pem to Swagger UI.

  • If the mapping and the certificate are valid, you will see the following response:

Setting up the new domain

To set up a custom domain you will need to provide the full chain certificate and the domain name.

For this example, we will use the Restcomm Message Exchange API. You can use Postman or cURL if you’d prefer it.

  • Go to Restcomm Message Exchange API
  • Click on the Authorize button on the right side of the screen.
  • Enter your Restcomm Account SID for the username. This is found on the Account screen referenced above.
  • For the password, enter your Restcomm Auth Token. This can be found on the
  • Account screen referenced above.
  • Click Authorize. You’re now ready to create your first mapping.
  • Click on POST from the list of operations on the screen, then click Try It Out
  • You’ll see an example of the payload in the text box. Modify these values to match your domain name and certificate.
  • Enter the domain name for the value of name. For our example, you would enter mycompany.com.
  • Enter your full chain certificate for the value of certificate.
  • Click the blue Execute button below the text box.
  • Scroll down to the Server response area of the screen. You should see a code of 200. If this is the case, you’ve successfully created your new custom domain!

Important: Please allow few minutes for domain changes to be applied to Restcomm Message Exchange

Testing the XMPP server using your new custom domain

You can use https://xmpp.net/index.php to start an XMPP server to server test for your new domain.

For example:

Get awesome content in your inbox every week.

Give it a try. It only takes a click to unsubscribe.