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:

Run in Postman

MMS Sample

{
    "channel": "mms",
    "from": "34343",
    "to": [
        {
            "msisdn": [
               " +1647XXXXXXX" //E.164 format required/recommended. Older tenants might still accept other formats.
            ],
            "correlationId":"", //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
            "substitutions": {	
                "area": "EC1M 4BH",
                "offerName": "By1_Get1",
                "accountNumber": "38S189"
            }
        }
    ],
    "substitutions": {
        "offerName": "buy1_get1",
        "value": "123"
    },
    "callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
    "notifyUrl": "", //Optional.
    "requestedReceipts": [],
    "options": {},
    "content": {
      "subject": "Subject MMS check",
        "fallbacktext": "fallback $(offerName)text as SMS",
        "name": "Internal $(offerName)Name",
        "attachments": [
            {
                "type": "image",
                "messageText": "Sample image file",
                "mediaUrl": "http://res.cloudinary.com/demo/image/upload/sample.jpg",
                "duration": 5   
            },
            {
                "type": "ical",
                "messageText": "Sample calender",
                "duration": 5,
                "mediaUrl": "https://s3.amazonaws.com/qa-appleattachment/9c49a035-17a6-4287-b97c-a3ed40c895dd_c3ccc83b-eb5d-443c-9313-49ceb004021a.ics"
            },
            {
                "type": "pdf",
                "messageText": "Sample pdf file",
                "duration": 5,
                "mediaUrl": "http://www.pdf995.com/samples/pdf.pdf"
            },
            {
                "type": "video",
                "messageText": "Sample video file",
                "duration": 5,
                "mediaUrl": "http://mirrors.standaloneinstaller.com/video-sample/small.m4v"
            },
            {
                "type": "audio",
                "messageText": "Sample audio file",
                "duration": 5,
                "mediaUrl": "https://www.easygifanimator.net/images/samples/eglite.mp3"
            },
            {
                "type": "vcard",
                "messageText": "Sample contact",
                "duration": 5,
                "mediaUrl": "https://s3.amazonaws.com/appleattachment/34343/86078a53-4530-4811-9b47-a406a2b8bb5b/OO2ZtXTj.vcf"
            }
        ]
    }
}

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

ParameterDescription
channelMMS
fromThe number from which the MMS is sent

The from number can only be one of the MMS enabled numbers provisioned for the account
toThe 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 TypeFile ExtensionMaximum File Size
Overall MMS payload size750 KB
ImageThe 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
AudioThe URL must be publicly accessible and end with one of the following file types:
.mp3 = audio/mp3, audio/mpeg
750 KB
VideoThe 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-pdf750 KB
Texttext/plain750 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

  • Video will 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 supports up to 80 characters in the MMS subject.
  • Message Subject is not supported in incoming MO messages and the subject will be added to the general message content received.
  • The API supports up to 9 slides for each MMS submission.
  • The API does not support multiple files of the same MIME type in the same slide.
  • Slides with images does not support video but supports audio.
  • Slides with audio does not support video. Slides with video only supports text.
  • Slides with text supports up to 5000 characters in any slide.
  • Slides with vCard/iCal/PDF objects do 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 or video can be used only when the audio or video encoding is completed.

HTTP Response Codes

HTTP Response CodesDescriptions
200 OKSuccessful
201 CreatedCreated
400 Bad RequestBad input parameter. Error description should indicate which one and why
401 UnauthorizedThe client passed in the invalid key/token
403 ForbiddenThe customer doesn’t exist. * Customer account over quota.
404 Not FoundResource not found
405 Method Not AllowedThe resource doesn't support the specified HTTP verb
409 ConflictConflict
429 Too Many RequestsToo many requests for rate limiting
500 Internal Server ErrorThe servers are not working as expected. The request is probably valid but needs to be requested again later
503 Service UnavailableService 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

CodeMessageDelivery Status
7500DeliveredDelivered
7501SubmittedSubmitted
7208Un-deliveredMessage expired
7524OpenedOpened
7525Link|IPClicked
7552Address errorFailed
7553Address not foundFailed
7554Multimedia content refusedFailed
7555Message format corruptFailed
7556Message rejectedFailed

API Error Codes - HTTP 400 Bad Request

CodeMessage
7000Invalid JSON
7003Dynamic Format

“Mandatory parameter missing: {{parameter}}”
7004Dynamic Format

“Invalid parameter: {{parameter}}”
7127Source IP is not in the allowed listed
7016Unknown exception
7020You have reached the maximum transaction limit
7101Invalid sender ID
7102Invalid destination address
7104Invalid app ID
7107Message length exceeded
7108Invalid template ID
7126Invalid content type
7009Maximum number of destinations reached
7022JSON size exceeded
Language
Click Try It! to start a request and see the response here!