Messaging

Send and Receive MMS

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

I. Sending an MMS

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

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.

Form a POST request and include from, to, and media_urls. 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", "media_urls":["https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"]}' \
-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": [
        "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
    ],
    "message": null,
    "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":"mms",
    "user_data":null
}

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

II. Sending a group MMS

Along with sending an MMS to just one recipient CarrierX also allows sending MMS messages to groups of recipients. Let’s send an MMS to three different recipients at once. We’ll use the group_recipients body argument for that purpose.

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

Please note that as soon as you use the group_recipients body argument the message is automatically treated as MMS, not SMS. You can also make an attachment to your MMS by using the media_url attribute mentioned earlier, but for group MMS messages the media_url field is optional. In the case of group messaging the message will always be sent as MMS only, even if you don’t attach anything to it and send text only in the message field.

curl -X POST \
'https://api.carrierx.com/core/v2/sms/messages' \
-H 'Content-Type: application/json' \
--data-binary '{group_recipients=17575000928%2C%2014386009161%2C%2017208200011&message=This%20is%20a%20test%20MMS.'}' \
-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": "2023-08-03T12:08:46.686Z", 
    "date_created": "2023-08-03T12:08:46.686Z", 
    "date_status_changed": "2023-08-03T12:08:46.686Z", 
    "direction": "outbound", 
    "from ": "15208210009", 
    "group_recipients": [ "17575000928", "17208200011", "14386009161" ], 
    "mcc": 302, 
    "media_urls": [], 
    "message": "This is a test MMS.", 
    "message_segments": 1, 
    "message_sid": "7f053c78-7daf-4ef0-b0bb-1ac883456562", 
    "mnc": 620, 
    "partner_sid": "f1e3gb1a-2e06-43f1-97c6-914493b7b8d3", 
    "price": "0.3", 
    "status": "queued", 
    "to ": "14386009161", 
    "type": "mms", 
    "user_data": null 
}

III. Getting Message Status

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

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":[
        "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
    ],
    "message": null,
    "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":"mms",
    "user_data":null
}

IV. Setting Up Callbacks

In this section, we will learn how to receive MMS receipts by setting callback URLs programmatically and through the portal. We can set callbacks to receive data back about sent MMS 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 MMS 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 MMS. 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":"2023-09-04T17:37:38.852Z",    
    "date_created":"2023-09-04T17:37:36.123Z",
    "date_status_changed":"2023-09-04T17:37:00.000Z",
    "direction":"outbound",
    "from":"13075222216",
    "group_recipients":[ "17575000929", "17208200012", "15162065318" ],
    "mcc": null,
    "media_urls": [
        "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
    ],
    "message": null,
    "message_segments": 1,
    "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
    "mnc": null,
    "partner_sid": "66352290-bd20-4ed0-a403-8c00792f15b8",
    "price": "1",
    "status": "delivered",
    "to": "15162065318",
    "type": "mms",
    "user_data": "null"
}

V. 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 MMS from, telling the sender that their MMS was successfully received.

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

from, which is the phone number that the MMS was received from,
to, which is the phone number that the MMS was sent to,
status, which is the current MMS 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 MMS 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 MMS.
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 MMS 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 MMS 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.

VI. Next Steps

You have learned how to send and receive an MMS 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.