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.

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
}

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.

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:

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 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:

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:

  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','')
    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

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.