shell

Send and Receive SMS

The Core API can be leveraged to send and receive SMS using rented DIDs from CarrierX.

I. Sending an SMS

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 Guide 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"}'
-u '[your_user_name]:[your_password]'


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

{
    "date_created": "2019-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 Guide 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' \
-u '[your_user_name]:[your_password]'


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

{
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": "2019-01-18T10: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 two different levels - by setting the value of sms in the callbacks object on the Partner object, or by setting the value of callback_url on the DID object. If a callback value is set on both the Partner and DID objects, the DID object value will be used.

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

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 on the Configure menu. Click Phone Numbers.

Click Numbers

Find and click on 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.

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.

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

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/66352290-bd20-4ed0-a403-8c00792f15b8' \
-H 'Content-Type: application/json' \
--data-binary '{"callbacks": {"sms":"http://sampleurl.com"}}' 
-u '[your_user_name]:[your_password]'


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


A callback request to the URL you assigned to the Partner 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: created, queued, sending, sent, or received.

{
    "price": "1",
    "message_segments": 1,
    "mnc": null,
    "mcc": null,
    "status": "received",
    "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
    "partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
    "message": "This is a test message delivered by CarrierX",
    "direction": "inbound",
    "date_created": "2016-04-21T17:42:55.000Z",
    "date_status_changed": "2016-04-21T17:42:55.000Z",
    "from_did": "15162065319",
    "to_did": "15162065318"
}

IV. Using Callbacks

In this section, we will learn how to use callbacks to perform subsequent actions. We will use the callback data we receive to send an SMS to the phone number that we received an SMS from.

From our callback data, we will take the value for the from_did, which is the phone number that the SMS was received from. Then we will create another POST request that dynamically populates this value as the to_did value.

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

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

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 or DID Object. For more information, refer to the SMS section of the Core API.

For more information about the Partner and DID Objects, on which you will set your callback URL, refer to the Core API Partner object and DID object. To learn more about renting phone numbers, refer to the Rent a Phone number tutorial or quick start guide.