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.

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.

Click Messaging

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

Select From DID

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

Enter To DID and Message

When ready, click Send.

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_did, to_did, 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_did":"15162065575", "to_did":"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_created": "2021-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": null,
    "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_did": "15162065574"
}

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_created": "2021-01-18T21:01:13.415Z",
    "date_status_changed": "2021-01-19T10:01:00.000Z",
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": 0,
    "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_did": "15162065574"
}

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:

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

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.

Click Numbers

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

Select Number

Scroll down and click Edit.

Click Edit

Enter the callback URL in the SMS Callback URL box.

Enter URL

Click Save.

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, or failed.

{
    "date_created": "2021-04-21T17:42:55.000Z",
    "date_status_changed": "2021-04-21T17:42:55.000Z",
    "direction": "inbound",
    "from_did": "15162065319",
    "mcc": null,
    "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_did": "15162065318"
}

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:

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

The steps for the app creation are the following:

  1. We create a sms_callback.py file to hold the code for our application.

  2. 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
    
  3. Initiate the Flask application:

     app = Flask(__name__)
    
  4. Create a route that will contain the main application logic:

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_did','')
    send_from = data.get('to_did','')
    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_did": send_from, "to_did": 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

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.