post https://api.us.webexconnect.io/v2/messages
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":"", //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
| 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 = 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
- 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 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 |