SMS on DIDs
- Tom Cavey
- Zachary Kinney
- Ian Hambelton (Unlicensed)
- Timothy Linn
VI Communication Services supports both inbound and outbound SMS (Short Message Service) or text messaging.
For instructions on activating DIDs for SMS, please click here for our Wiki article.
For documentation on using SMS with our Programmable Telco / APIDaze platform, click here.
Both inbound and outbound SMS have a limit of 160 characters inherent in all text messages.
Please format your messages accordingly.
SMS as SIP
Once you have a SIP SMS enabled DID on your account, you will receive inbound SMS traffic just as you receive SIP traffic, namely, directly to the Endpoint Group you have assigned the number to in the Back Office. You will see the message in the packets and if you have a device configured that can interpret the message, the text will be displayed. You can verify you are receiving the SMS text by obtaining a packet capture of this traffic coming into your network. For a detailed description of how to obtain and interpret packet captures, click here.
For outbound SMS to work properly, you will need to ensure you prepend the destination number with a #. If you have a device (for example, a softphone) capable of creating a text message and can send the call from that device prepended with the #, we will route the message correctly. You can ensure how you are sending calls to us using Wireshark to capture traffic leaving your network (see link in previous paragraph for Wireshark article).
If you would like to view the voip-info.org article regarding how various gateways including Asterisk handle SMS, click here.
If you are having inbound issues with SMS, open a ticket with our Support Team (if you are unfamiliar with how to contact Support, click here). If you are having an inbound problem, Support will only verify via a packet capture that we are correctly passing the message. This will require live testing wherein we set a capture while you (or your user) send a test message. If we can verify through the packet capture that the message is being passed to your endpoint correctly you will need to investigate further on your end. If we are not receiving your message, we may attempt to capture a test message sent from a device in our NOC and/or different devices by you. If that message is delivered to your endpoint correctly you will need to verify why we are not receiving your specific end-user's messages by contacting their provider. If we can duplicate an issue we will contact our underlying carrier for resolution.
If you are having outbound issues with SMS, open a ticket with Support (see above paragraph for link if you are unsure how to do this). We may request a packet capture from you network verifying you are sending correctly, OR we may suggest live testing wherein we capture the traffic. If we can verify you are correctly sending SMS, but the end user is not receiving correctly, we may request you send to an alternate device that we can verify (such as one of our cell phone numbers). If we can duplicate the issue, we will open a trouble ticket with our underlying carrier for resolution.
Please note that now we cannot verify message receipt. A Wireshark capture may show a 200 OK yet the device did not receive the message. This is because the receiving gateway accepted the message with the SIP 200 OK and failed to deliver it to the corresponding device.
Set up capture (this is an example, this image may look different on your system)
Compose Text Message
Send Text Message
SMS to Email
The information that was provided previously was for SIP SMS messaging. However, we do have the option for SMS to Email so a message will be sent to an email or a list of emails. This can be done through the back office. The steps on activating SMS are in the article "Activating SMS on DIDs", you can see this article if you click here.
After entering the email of choice for your DID and clicking save it will take 15-20 minutes for propagation to take place.
After this time has passed, you may test a message by sending a test message from your cell phone to test.
Sending the Test Message
Received Message in Email
You'll see the message in the body of the email. Next you will see the number that sent you the message in the from field for the email client you are using followed by ‘@mysmsforward.com’. (This example is from Microsoft Outlook) You will also see that the email will be listed with the subject header labeled as "SMS From (Source Number) To (Destination or Your DID)".
Some have the question if you can reply to the SMS message from the email. You can do this if your email that you have listed in the back office for this DID has a valid SPF record. We would advise reaching out to your domain provider to ensure you have a valid SPF record if you are having trouble replying to the message sent to your email.
SMS Forward
We offer another SMS solution and this a forward. This option is a 1 v 0 scenario where you configure the DID to forward to another number. In most cases, this is a cell phone, or an off-network number not hosted through VoIP Innovations. This can be done through the back office. The steps on activating SMS are in the article "Activating SMS on DIDs", you can see this article if you click here. Once updated, please allow 15-20 minutes for propagation to pass and the number being fully active for SMS.
Now with the forwarding service for SMS, recipients cannot respond to the text message when they receive it. This SMS option is strictly to pass a message along to the receiving side without the sender knowing the destinations cell phone number. For example, customers will use this option if they have a business line enabled with SMS functionality that forwards to their cell phone, when in return, they do not want to give out their personal cell phone to customers. This is useful for Real Estate companies where they can later contact a buyer who is interested in a house, when they may not be in the office.
In the picture below, a text message was sent to the VI SMS enabled DID and was received on the destination cell phone. You can see from the screenshot, the VI DID shows as the source number as it is the authorized sender and how you wouldn't be able to text back because it would cause a loop.
API POST/API GET
VI offers two other SMS services that are handled via the API, API POST and API GET. These two options are the different locations you want messages sent to regarding your API. To properly use these methods, you need to authorize your credentials. This means you need to validate requests by authorizing a valid username, password and IP address. You can authorize your credentials under Add-Ons > API > API Users.
GET and POST methods can achieve the same goal via HTTP. GET requests data from a specified resource. POST submits data to be processed to a specified resource. GET requests can be cached, and they also remain in the browser history. GET Requests should never be used dealing with sensitive data as the values are sent in the URL of the GET Request.
GET requests also have length restrictions in the return URL. POST requests are never cached, and the values are sent in the HTTP message body. There are no restrictions on data length or data type. Below is a test SMS that was sent via GET and POST.
API GET
API POST
As you can see in both screenshots, the GET request shows the message in the Query String, while the POST request is in the body of the message. Therefore, we recommend using POST.
MS Teams Webhook
As part of our Microsoft Teams integration, we also allow for SMS/MMS including images to be delivered to a channel in your Microsoft Teams instance. The first step of sending your SMS/MMS to a Teams channel is creating an Incoming Webhook in the channel(s) that you wish to receive your messages in:
Create an Incoming Webhook - Teams
Once the webhook is created, simply copy the URL and paste it inside the URL textbox on the SMS Configuration Screen after selecting “MS Teams Webhook.” Text from SMS and MMS as well as images from MMS messages will then start showing in the channel with the webhook.
Programmable Telco
Vi's last option for using SMS is programmable telco. Programmable Telco is our CPaaS platform this allows you to program numbers to scripts, so you can use SMS. You can create a generic script through our product APIDaze or you can host an external script on your own web server. Either method you choose, it will connect with our programmable telco product APIDaze. You can reach programmable telco under App. This will redirect you to our APIDaze platform and you can configure the DIDs through there.
SMS and Emoji
SMS does support the use of “Emoji” objects, however the emoji unicode must be escaped correctly in order to be received by the far end, as for the correct escaping characters, it would depend on the language in use. This does work through SIP, though do not have a working example at present, the below are examples sent via API3.
XML Example:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendSMS xmlns="http://tempuri.org/">
<login>API_USERNAME</login>
<secret>API_PASSWORD</secret>
<sender>SOURCE_DID</sender>
<recipient>DESTINATION_OF_SMS</recipient>
<message>I am testing this application 😀 😀</message>
</SendSMS>
</soap:Body>
</soap:Envelope>Result:
Python API3 Example:
from suds.client import Client
client = Client('https://backoffice.voipinnovations.com/Services/APIService.asmx?wsdl')
client.service.SendSMS('API_USERNAME','API_PASSWORD','SOURCE_DID','DESTINATION_OF_SMS','Python message \U0001F600 \U0001F923 \U0001F618')
As you can see, escaping characters is different between languages so proper syntax for said language is paramount. As to which is correct for each language, that information is readily available on the internet via a search.