Messaging

Send and Receive SMS

The Core API can be leveraged to send and receive SMS using rented DIDs from CarrierX.
You can use the Core API to send and receive both SMS and MMS using rented DIDs from CarrierX.

Please note that by default all rented DIDs have only one active capability, 4 for voice. To be able to send or receive messages, the rented phone number must be SMS/MMS enabled and have the appropriate active_capabilities attribute value set: 1 for receiving SMS, 2 for sending SMS, 3 for both, sending and receiving SMS, 8 for receiving MMS, 16 for sending MMS, 24 for both, sending and receiving MMS, or 27 for all message capabilities.

I. Sending an SMS

You can send an SMS either using the CarrierX portal or programmatically with the help of Core API.

Sending an SMS via Portal

We will first send an SMS through the portal. Once you are logged into your account, navigate to the left-side menu. Then, locate and click the Messaging menu.

Select the phone number, from which you want to send your SMS, from the drop-down list of the available ones.

Enter the phone number, to which you will send your SMS, and type in the message text.

When ready, click Send.

This will send an SMS message from the selected phone number to the phone number you entered into the To DID form.

Sending an SMS Programmatically

In this section, we will use the Core API to send an SMS.

Form a POST request and include from, to, and message. Refer to the SMS Object section of the Core API Reference for a list of the other fields that exist in the SMS object.

curl -X POST \
'https://api.carrierx.com/core/v2/sms/messages' \
-H 'Content-Type: application/json' \
--data-binary '{"from":"15162065575", "to":"15162065574", "message":"This is a test message"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code along with a response that looks like the following:

{
    "date_changed": "2021-01-18T21:01:13.415Z",
    "date_created": "2021-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients":[],
    "mcc": null,
    "media_urls":[],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": null,
    "status": "queued",
    "to": "15162065574",
    "type":"sms",
    "user_data":null
}

Note, that legacy users may still see the old namings (to_did, from_did) instead of from and to.

II. Getting Message Status

In this section, we will retrieve a message status for a sent SMS.

Form a GET request and include the message_sid from your response object above. Refer to the SMS Object section of the Core API Reference for a list of the other fields that exist in the SMS object.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/messages/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code along with a response that looks like the following:

{
    "date_changed": "2021-01-18T21:01:13.415Z",
    "date_created": "2021-01-18T21:01:13.415Z",
    "date_status_changed": "2021-01-19T10:01:00.000Z",
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients":[],
    "mcc": 0,
    "media_urls":[],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": 0,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": "0.01",
    "status": "delivered",
    "to": "15162065574",
    "type":"sms",
    "user_data":null
}

III. Setting Up Callbacks

In this section, we will learn how to receive SMS receipts by setting callback URLs programmatically and through the portal. We can set callbacks to receive data back about sent SMS at three different levels:

by setting the value of sms in the callbacks object on the Partner object,
by setting the value of callback_url on the DID Group object,
or by setting the value of callback_url on the DID object.

If a callback value is set on all three objects, the DID object value will be used.

Note that callback URLs must have the POST method. You will get an error if you use a GET request.

Set Callback URL via Portal

We will first set a callback URL on the DID object through the portal. Once you are logged into your account, navigate to the left-side menu. Then, locate and click the Configure menu. Click Phone Numbers.

Find and click the phone number to which you would like to assign your callback URL.

Scroll down and click Edit.

Enter the callback URL in the SMS Callback URL box.

Click Save.

You have now assigned a callback URL on the DID level through the portal.

Set Callback URL Using API

Now, we will learn how to assign callbacks using the API. In the following example, we will assign a callback for SMS activity on the Partner object. Create a PATCH request assigning the value of sms inside of the callbacks object.

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/66352290-bd20-4ed0-a403-8c00792f15b8' \
-H 'Content-Type: application/json' \
--data-binary '{"callbacks": {"sms":"https://d528c056e44d.ngrok.io"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code along with the Partner object.

You can also set callbacks on DID and DID Group objects programmatically by sending a PATCH request assigning the value of callback_url.

A callback request to the URL you assigned to the Partner, DID Group, or DID object will look like the following. Refer to the status value to determine the status of the SMS. You will receive one of the following statuses: queued, sent, delivered, received or failed. For the full list of possible SMS/MMS statuses, consult the SMS Object documentation.

{
    "date_changed": "2021-04-21T17:42:55.000Z",
    "date_created": "2021-04-21T17:42:55.000Z",
    "date_status_changed": "2021-04-21T17:42:55.000Z",
    "direction": "inbound",
    "from": "15162065319",
    "group_recipients":[],
    "mcc": null,
    "media_urls":[],
    "message": "This is a test message delivered by CarrierX",
    "message_segments": 1,
    "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
    "mnc": null,
    "partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
    "price": "1",
    "status": "received",
    "to": "15162065318",
    "type":"sms",
    "user_data":null
    "type":"sms",
    "user_data":null
}

IV. Using Callbacks

In this section, we will learn how to use callbacks to perform subsequent actions.

Let’s create a short application that will receive the callback, and will send an SMS to the phone number that we received an SMS from, telling the sender that their SMS was successfully received.

From our callback data, we will take the following values:

from, which is the phone number that the SMS was received from,
to, which is the phone number that the SMS was sent to,
status, which is the current SMS status,
direction, so that we will send callbacks for inbound messages only.

Note that both inbound and outbound messages are sent as callbacks. That is why you will need to pay attention to the direction field to determine if the message is inbound or outbound.

Then we will create another POST request that dynamically populates the to and from values, and will return the SMS status to the source phone number.

The steps for the app creation are the following:

We create a sms_callback.py file to hold the code for our application.
In it, we import the necessary modules from Python and Flask (request to access the incoming request data, requests to create a POST request, and json to form the POST request payload):
```
 from flask import Flask, request
 import requests, json
```
Initiate the Flask application:
```
 app = Flask(__name__)
```
Create a route that will contain the main application logic:

Receive JSON callback data from the phone number to which we sent an SMS.
Parse the data and get the from, to, status, and direction values.
Check if the message direction is inbound. If this is the case, it will post a request to the source phone number with the message containing the SMS status.

The resulting application code will look like the following:

from flask import Flask, request
import requests, json

app = Flask(__name__)

@app.route('/', methods=['POST'])
def home():
    data = request.get_json()
    send_to = data.get('from','')
    send_from = data.get('to','')
    status = data.get('status','')
    direction = data.get('direction','')
    if direction == 'inbound':
        url = "https://api.carrierx.com/core/v2/sms/messages"
        headers = {'Authorization': 'Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda', 'Content-Type':'application/json'}
        payload = {"from": send_from, "to": send_to, "message": f"The SMS status is: {status}"}
        requests.post(url, data=json.dumps(payload), headers=headers)
        return ''
    else:
        return ''

For callbacks, you can return a blank response because we do not use what you send.

Now you can start your application with the command:

FLASK_APP=sms_callback.py flask run

Please do not forget that you need to expose the localhost route publicly over the Internet so that the phone number could access it using the callback_url link. You can either host it on your own server, or use the free ngrok tool for testing purposes. Refer to ngrok website for more information on how to use it.

V. Next Steps

You have learned how to send and receive an SMS using the Core API! You also learned how to configure a callback URL on the Partner, DID Group, or DID object. For more information, refer to the SMS section of the Core API Reference.

For more information about the Partner, DID Group, and DID objects, on which you will set your callback URL, refer to the Core API Partner object, DID Group object, and DID object.

To learn more about renting phone numbers, refer to the Rent a Phone Number tutorial or quick start guide.