Skip to main content

Receiving Your First SMS

To send your first SMS, you needed a phone number, API credentials, and a REST API call.

Receiving messages works a bit differently: when using the cXML API, you need to prepare an XML file with instructions on what to do after a message is received on a given phone number.

A diagram illustrating the process of receiving text messages from users using cXML applications.

Receiving text messages from users using cXML applications.

  1. the user sends a message to a number in your SignalWire Space.
  2. SignalWire fetches the XML bin URL associated with the destination number.
  3. The contents of the XML bin are interpreted and executed.
  4. Any response specified in the XML bin will reach the caller.

cXML Applications​

Let's write our first XML bin. We will host this one on SignalWire (you can use your own server if you want, which even allows you to generate bins dynamically).

You can create and manage bins from the LaML section of your Dashboard under the Bins tab.

A screenshot of the LaML page with the Bins tab circled in red.
cXML applications tab of the LaML section

Create a new bin, and use the following lines as content:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Hello from SignalWire!</Message>
</Response>

The bin above will reply with a fixed message to any incoming SMS. Find the full technical reference in the Compatibility XML section.

Copy the Request URL of the bin you just created, then read the next section to configure a number to handle messages using that bin.

Configuring your number​

The last step is connecting a number to the bin. If you don't have a phone number yet, make sure to buy one. You will need at least one number to receive messages.

Then, open the settings for the number. Under "Messaging Settings", choose to handle messages using "LaML Webhooks", then paste the URL of the bin in the field below.

A screenshot of the Phone Numbers page. 'Handle Messages Using' is set to LaML Webhooks. 'When a Message Comes In' is set to the URL of the LaML bin.
Connecting a number to an XML bin. First select "LaML Webhooks", then paste the URL of the bin.

Try sending a message to the configured phone number: after a few seconds you'll receive an automated reply.

Ensuring message delivery

If you are sending messages to the US from a 10DLC number, you must register your traffic with the Campaign Registry. Otherwise, the carriers will not deliver your messages. Please see Campaign Registry - Everything You Need To Know for more information.

Wrap up​

We have shown how to receive a text message and perform follow-up actions.

This example used the Compatibility API, and in particular cXML bins, to receive a message. For more advanced, real-time applications, you'll want to check out our Realtime SDK.