MMS API

🚧
API Endpoint and Authentication

Your API endpoint varies based on where your Webex Connect account is hosted. Visit Know Your API Endpoint section to know more.

You can use either Service Key or JSON Web Tokens (JWT) for authentication. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.

❗️
API Access
This API is currently available only for clients in the US and Canadian regions. MMS capability must be requested as part of the tenant on-boarding process. A default MMS tps throughput is provided, but higher throughput requirements can be provided after discussion with your account manager.
**TFN MMS messaging may not be supported on all Canadian carriers. For more details please ask the account team on specific MMS reach in the US and Canada.
Please reach out to you account manager to enable MMS in other regions.

MMS API

Try our MMS APIs using the Postman collection here:

MMS Sample

{
    "channel": "mms",
    "from": "34343",
    "to": [
        {
            "msisdn": [
               " +1647XXXXXXX" //E.164 format required/recommended. Older tenants might still accept other formats.
            ],
            "correlationId": "asdfghjklasdfghj",
            "substitutions": {
                "area": "EC1M 4BH",
                "offerName": "By1_Get1",
                "accountNumber": "38S189"
            }
        }
    ],
    "substitutions": {
        "offerName": "buy1_get1",
        "value": "123"
    },
    "callbackData": "suneelmmstest",
    "notifyUrl": "https://requestinspector.com/inspect/01h6wxh0k8byhe6a3rga8957w9",
    "requestedReceipts": [],
    "options": {},
    "content": {
        "fallbacktext": "fallback $(offerName)text as SMS",
        "name": "Internal $(offerName)Name",
        "attachments": [
            {
                "type": "image",
                "messageText": "hi user",
                "mediaUrl": "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg"
            },
             {
                "type": "video",
                "messageText": "hello",
                "mediaUrl": "https://sample-videos.com/img/Sample-jpg-image-50kb.mp4"
            }
        ]
    }
}

When an MMS message is received via the Messaging API v2:

If the from senderID is not MMS enabled for the tenant in Admin Console, then the message is rejected.
If the senderID doesn't match the preset list, the API request fails with “Invalid senderID” response.

Request Body Parameters

Parameter	Description
channel	MMS
from	The number from which the MMS is sent The from number can only be one of the MMS enabled numbers provisioned for the account
to	The number to which MMS is sent The to number must follow E.164 format

📘
Note
If +E.164 format is enabled for your tenant - all the numbers in the To field should follow the "+E.164" format.
This format displays the number with a "+" followed by the country code and the phone number.
+E.164 format is not applicable to the numbers in the From field.

Supported File Types and Sizes

The overall MMS size must not exceed 750 KB.

Media Type	File Extension	Maximum File Size
Overall MMS payload size		750 KB
Image	The URL must be publicly accessible and end with one of the following file types: .jpg = image/jpg, image/jpeg .png = image/png .gif = image/gif	750 KB
Audio	The URL must be publicly accessible and end with one of the following file types: .mp3 = audio/mp3, audio/mpeg	750 KB
Video	The URL must be publicly accessible and end with one of the following file types: .mp4 = video/mp4	750 KB
Calendar	.ics, .ical, .ifb, .icalendar = text/calendar	750 KB
Contact	.vcf, .vcard = text/vcard, text/v-card, text/x-vcard	750 KB
Pdf	.pdf = application/pdf, application/x-pdf	750 KB
Text	text/plain	750 KB

Content validation rules:

Supported MIME TYPE and Supported Extension SHALL pass at validation.
Supported MIME TYPE and Invalid Extension SHALL pass at validation.
Supported MIME TYPE and No Extension SHALL pass at validation.

Special Considerations

Delivery success takes precedence over audio and video content quality and occasionally the picture quality will be reduced to fit handset message size requirements.
Video SHALL be reduced in quality to fit delivery limitations and if it still does not fit it will be delivered as a Fallback SMS.
Each request MUST contain at least one slide which MAY contain text and MAY contain an image, video, audio or other supported object.
The API SHALL support up to 9 slides for each MMS submission.
The API SHALL NOT support multiple files of the same MIME type in the same slide.
Slides with images SHALL NOT support video but SHALL support audio.
Slides with audio SHALL NOT support video. Slides with video SHALL only support text.
Slides with text SHALL support up to 5000 characters in any slide.
Slide with vCard/iCal/PDF objects SHALL NOT support media type audio/video/image and vice-versa.
URLs provided MUST contain the full path to the content files.
If the Transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
After submission, you will not be given a successful acknowledgment of audio/video encoding when a message is submitted.
The status of audio/video encoding after it has been completed will be sent to your Postback URL

HTTP Response Codes

HTTP Response Codes	Descriptions
200 OK	Successful
201 Created	Created
400 Bad Request	Bad input parameter. Error description should indicate which one and why
401 Unauthorized	The client passed in the invalid key/token
403 Forbidden	The customer doesn’t exist. * Customer account over quota.
404 Not Found	Resource not found
405 Method Not Allowed	The resource doesn't support the specified HTTP verb
409 Conflict	Conflict
429 Too Many Requests	Too many requests for rate limiting
500 Internal Server Error	The servers are not working as expected. The request is probably valid but needs to be requested again later
503 Service Unavailable	Service Unavailable

Delivery Receipts

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Submitted",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7501",
            "deliveryStatus": "Submitted",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Delivered",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7500",
            "deliveryStatus": "Submitted",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "Read",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "code": "7524",
            "deliveryStatus": "Read",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "deliveryChannel": "mms",
            "Description": "https://clientname.uk/offer|192.0.2.1",
            "destinationType": "msisdn",
            "timeStamp": "2016-07-21T12:44:23.644",
            "additionalInfo":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.90 Safari/537.36",
            "code": "7525",
            "deliveryStatus": "Clicked",
            "destination": "447500661610"
        },
        "correlationid": "3bd8edf31c81-4b72d8a2-290d-49e2-993e",
        "callbackData": "return callbackdata",
        "transid": "4b72d8a2-290d-49e2-993e-3bd8edf31c81"
    }
}

{
  "deliveryInfoNotification": {
    "deliveryInfo": {
      "deliveryChannel": "mms",
      "Description": "Message expired",
      "destinationType": "msisdn",
      "timeStamp": "2016-07-28T11:47:56.459Z",
      "code": "7208",
      "deliveryStatus": "Un-Delivered",
      "destination": "910000000001"
    },
    "correlationid": "",
    "callbackData": "",
    "transid": "8f0fd088-2a80-43e3-9da1-e82e52b17390"
  }
}

Status Codes

Code	Message	Delivery Status
7500	Delivered	Delivered
7501	Submitted	Submitted
7208	Un-delivered	Message expired
7524	Opened	Opened
7525	Link\|IP	Clicked
7552	Address error	Failed
7553	Address not found	Failed
7554	Multimedia content refused	Failed
7555	Message format corrupt	Failed
7556	Message rejected	Failed

API Error Codes - HTTP 400 Bad Request

Code	Message
7000	Invalid JSON
7003	Dynamic Format “Mandatory parameter missing: {{parameter}}”
7004	Dynamic Format “Invalid parameter: {{parameter}}”
7127	Source IP is not in the allowed listed
7016	Unknown exception
7020	You have reached the maximum transaction limit
7101	Invalid sender ID
7102	Invalid destination address
7104	Invalid app ID
7107	Message length exceeded
7108	Invalid template ID
7126	Invalid content type
7009	Maximum number of destinations reached
7022	JSON size exceeded