x

SignalWire Work is here. A complete office, school, or event venue right in your browser. Sign up for a 30-DAY FREE TRIAL or Learn more.

Messaging on SignalWire

How to use the SignalWire APIs to send and receive text messages and MMS

The SignalWire platform makes it easy to send and receive SMS using our REST APIs and a bit of LāML.

Sending messages

Our REST API SDKs are available in many languages. Examples in this post will be presented in Python. For a quick introduction to the SDKs, refer to this previous post.

Sending a text message or an MMS is very simple, as you can see in our first example:

from signalwire.rest import Client as signalwire_client

client = signalwire_client("YourProjectID", "YourAuthToken", signalwire_space_url = 'example.signalwire.com')

message = client.messages.create(
                              from_='+15550011222',
                              body='Hello World!',
                              to='+15550011333'
                          )

print(message.sid)

The from parameter should always be a number from your SignalWire account. Note that the underscore in the parameter name is a Python specific requirement.

Now let's explore how to send an MMS, adding a media_url parameter, pointing at a file available via HTTP. The size limit is currently 0.5Mb and the list of accepted MIME types can be found here.

from signalwire.rest import Client as signalwire_client

client = signalwire_client("YourProjectID", "YourAuthToken", signalwire_space_url = 'example.signalwire.com')

message = client.messages.create(
                              from_='+15550011222',
                              body='Hello World!',
                              to='+15550011333',
                              media_url= 'https://SOME-EXAMPLE-URL'
                          )

print(message.sid)

You might find it useful to specify a status_callback parameter pointing at a URL in your application. That webhook will receive updates on the message delivery and eventual errors. You can find the full list of parameters here.

Message deliverability

Sending SMS and MMS requires some care to avoid triggering spam filters and to keep your traffic within the legitimate guidelines. To help your messages be delivered in the best fashion, SignalWire published a Code of Conduct. It contains best practices like obtaining proper permission and honoring stop keywords.

Content guidelines include addressing the receiver, having a clear opt out language and not using public URL shorteners. You can refer to the CTIA guidelines for the current best practices.

In addition to that, there are considerations for each type of phone number you can purchase.

10-digit long code numbers are commonly referred to as "local" numbers, and are the most common type. They are primarily intended for person-to-person (P2P) messaging, meaning a casual two way conversation initiated by an actual user. They are limited to 1 message per second, but that should not be an issue if they are used as intended. Being that SignalWire is an API platform, all messages that leave the platform are automatically classified as A2P (application-to-person) by the downstream carriers. Currently, Verizon is the only carrier that guarantees deliverability of A2P messaging on 10-digit local numbers on it's network, and levies a Network Access Fee for each message delivered (see Messaging Pricing for up-to-date carrier fees). Other mobile carriers are likely to implement similar A2P specific products in the future. To ensure maximum of deliverability of A2P messages on 10-digit long code numbers, make sure to follow our A2P Messaging Best Practices.

Toll free numbers have an area code that begins with an 8, and are less restrictive due to their nature. They can be used for application-to-person (A2P) messaging provided content meets the general guidelines. They are limited to sending 10 messages per second.

Short codes are 5 or 6 digit phone numbers that are allowed to send SMS and MMS when an user opts in by texting them. The messages that are sent via short codes have to respect pre-approved content. As a result, the procedure to get a short code in place can be slightly longer, but they have the best deliverability of all types of numbers. You can find more information about short codes at SignalWire here.

Carrier surcharges

Carriers have recently introduced a series of surcharges for SMS and MMS traffic, which are applied differently in each country. For example, the US have surcharges on short code messages, and Canada on long and toll free numbers. You can find the current list of surcharges on our pricing page.

Receiving an SMS

To receive an SMS on one of your SignalWire numbers, you can use a variety of different methods.

The simplest way is... do nothing. Any message you receive will show up in the dashboard under "Usage". You might then want to list the messages you received using the REST API.

In a more useful scenario, you will want to intercept the message so you can do something with it programmatically. Setting up a LaML bin like this:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Thank you for contacting SignalWire!</Message>
</Response>

will result in a reply to each message received. <Message> supports other parameters, most notably to and from which allow you to send a reply to a different number than the original sender. You can find the documentation here.

As usual, use your dashboard to set it as the messaging handler.

To handle messages programmatically, the best way is to set up your own web application. The following Flask app will reply in the same way as the above LaML bin, but allows you to do something useful with the From and Body fields.

from flask import Flask, request
from signalwire.messaging_response import MessagingResponse
app = Flask(__name__)

@app.route('/')
def hello_world():
    from_number = request.args.get('From')
    message_body = request.args.get('Body')

    # do something useful with the parameters
    print(from_number, message_body)

    response = MessagingResponse()
    response.message('Hello from SignalWire!')
    return response.to_xml()

Conclusions

SignalWire makes integrating SMS and MMS into your application fun and easy.