Table of Contents
SaveMMS
Synopsis
This API creates an MMS template, transcodes the content, and stores it for later use. The MMS may contain slides embedded with text, video, audio, images, contact, calendar, and PDF. Once the MMS is saved, an mms-id is returned enabling it to be utilized in the future by other API functions such as the SendSavedMMS API. The slides are stored based on the order given in the API call. Please note that not all devices will honor the exact order directed in the MMS message.
If the MMS message is too large to be delivered or the carrier does not support MMS delivery, we will deliver the MMS as fallback SMS. The fallback SMS consists of two parts: the “fallback SMS text” and the “fallback SMS link”.
- The fallback SMS text is the SMS text that will be sent instead of the MMS along with the Fallback SMS Link to view the MMS Content. You can dynamically change the fallback SMS text by setting up the “FALLBACKSMSTEXT” node. If the “DISABLEFALLBACKSMS” node is set to ‘yes’ then the fallback SMS text is not required.
- The fallback SMS link is the link that hosts the MMS content. The fallback SMS link may be disabled by passing ‘yes’ to the “DISABLEFALLBACKSMSLINK” node. In this case only the fallback SMS Text is sent. By default, we always send the fallback SMS link along with the fallback SMS text.
- The fallback SMS can be completely disabled by passing ‘yes’ to the “DISABLEFALLBACKSMS” node. By default, the fallback SMS is enabled. If the MMS was attempted to be sent as SMS and the fallback SMS is disabled, the message sending will fail.
Special Considerations
- If the Transcoding is ON for the account, then the API SHALL reformat the content when necessary so that it can be delivered to the end-users handset in the best possible way.
- Video SHALL be reduced in quality to fit delivery limitations and if it still does not fit it the entire MMS message may be delivered as SMS Fallback, if configured.
- 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 80 characters in the MMS subject. Extra characters MAY be cut-off from the MMS subject. Unicode characters may not be supported in the Subject. Unicode characters that are not supported will be stripped out.
- The API SHALL support up to 9 slides for each MMS submission.
- The API SHALL NOT support multiple files of similar type on the same slide. In case, if multiple files of similar type are passed then by default only the first file is considered and the rest are ignored.
- Slides with images SHALL NOT support video but SHALL support audio.
- Slides with audio SHALL NOT support video.
- Slides with video or audio SHALL support text.
- Slides with object type (i.e. contact, calendar, PDF) SHALL NOT support other media types (i.e. audio, video, image).
- Slides with object type (i.e. contact, calendar, PDF) SHALL support text.
- On an IOS device, contact, calendar, and PDF objects are delivered as binary attachments in the MMS. On an Android device, only contact is delivered as binary attachment in the MMS and calendar/PDF are delivered as downloadable web links in the MMS. All other devices, contact, calendar, and PDF are delivered as downloadable web links in the MMS. In the case when handset is unknown, then by default contact is delivered as binary attachment and calendar/PDF are delivered as downloadable web links in the MMS.
- Slides with text SHALL support up to 5000 characters in any slide however some devices will not render all 5000 characters.
- Slides with text SHALL support characters that can be represented in Unicode including emoji or emoticon. It should however be noted that destination devices may have limited Unicode capabilities. The preferred encoding is UTF-8.
- URLs provided MUST contain the full absolute path to the files including http or https.
- When retrieving each file from the URLs the content-type header MUST be set to the correct MIME type for the file.
- If the Transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
- The status of encoding after it has been completed will be sent to your postback URL.
- Supported media extensions and MIME types:
- Text: text/plain
- Image:
- .jpg = image/jpg, image/jpeg
- .png = image/png
- .gif = image/gif
- .webp = image/webp
- Audio:
- .mp3 = audio/mp3, audio/mpeg
- .wav = audio/x-wave, audio/x-wav
- .amr = audio/amr
- Video:
- .mp4 = video/mp4
- .mpg, .mpeg = video/mpeg
- .avi = video/x-msvideo
- .wmv = video/x-ms-wmv
- .mov = video/quicktime
- .3gp = video/3gpp
- Contact:
- .vcf, .vcard = text/vcard, text/v-card, text/x-vcard
- Calendar:
- .ics, .ical, .ifb, .icalendar = text/calendar
- Pdf:
- .pdf = application/pdf, application/x-pdf
- Content validation rules:
- Supported MIME TYPE and Supported Extension SHALL pass at validation and transcoding.
- Supported MIME TYPE and Invalid Extension SHALL pass at validation and transcoding.
- Supported MIME TYPE and No Extension SHALL pass at validation and transcoding.
- “Octet-stream” MIME TYPE and Supported Extension SHALL pass at validation and transcoding assuming the content is what the extension says. Otherwise it SHALL fail at transcoding.
- “Octet-stream” MIME TYPE and Invalid Extension SHALL fail at validation.
- “Octet-stream” MIME TYPE and No Extension SHALL fail at validation.
- The following content is never transcoded: contact, calendar, PDF.
- There is a maximum source file size for each supported source file submitted. You can find out what the current maximum is by visiting your API settings.
Request: XML
<REQUEST>
<ACTION>saveMMS</ACTION>
<API_KEY>apiKey</API_KEY>
<SUBJECT>Subject</SUBJECT>
<NAME>Name to save it as</NAME>
<FALLBACKSMSTEXT>Fallback Text if this MMS is sent as SMS</FALLBACKSMSTEXT>
<DISABLEFALLBACKSMS>'yes' to disable fallback SMS</DISABLEFALLBACKSMS>
<DISABLEFALLBACKSMSLINK>'yes' to disable fallback SMS link</DISABLEFALLBACKSMSLINK>
<SLIDE>
<IMAGE>
<URL>URL</URL>
</IMAGE>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<AUDIO>
<URL>*URL</URL>
</AUDIO>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<VIDEO>
<URL>*URL</URL>
</VIDEO>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<VCARD>
<URL>URL</URL>
</VCARD>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<ICAL>
<URL>URL</URL>
</ICAL>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<PDF>
<URL>URL</URL>
</PDF>
<TEXT>Plain Text</TEXT>
</SLIDE>
<SLIDE>
<PERSONALIZED-IMAGE>
<TEMPLATE-ID>Personalized image template id</TEMPLATE-ID>
</PERSONALIZED-IMAGE>
<TEXT>Plain Text</TEXT>
</SLIDE>
<CLIENT_REFERENCE>Client Reference</CLIENT_REFERENCE>
</REQUEST>
*Any parameters passed in the URL are not supported and will be stripped out. To pass unique IDs, you must do so in the filename or in the file path.Request Parameters
| Term | Mandatory/Optional | Description |
|---|---|---|
| ACTION | Mandatory | This is the name of the function you want to execute with the API. |
| API_KEY | Mandatory | Random key that is assigned to an account that can be used for authorization instead of USER/PASS. You can find and regenerate this key on the ‘API Settings’ page. |
| SUBJECT | Optional | MMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject. |
| NAME | Mandatory | MMS template name for internal reference only. |
| FALLBACKSMSTEXT | Mandatory if subject is not passed | Text which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability. |
| DISABLEFALLBACKSMS | Optional | Set to ‘yes’/’no’ to disable the SMS fallback. |
| DISABLEFALLBACKSMSLINK | Optional | Set to ‘yes’/’no’ to disable appending a link to the MMS Content at the end of the SMS fallback text. |
| SLIDE | Mandatory | This represents a single slide within the MMS sequence that could include IMAGE/URL/TEXT/PIC etc. (There are special rules for slides within the ‘saveMMS’ special consideration section). |
| SLIDE:$CONTENT | Optional | Slide content node which contains the content URL. Acceptable slide content includes: image audio video vcard ical text personalized-image:template-id |
| SLIDE:$CONTENT:URL | Optional | Public content URL where the content is accessible. |
| SLIDE:TEXT | Optional | Text that is delivered alongside the content if added in a slide of the MMS. Line breaks are supported in the slide texts of the MMS. |
| CLIENT_REFERENCE | Optional; String | Customer Transaction ID for the request. Use it to match the postbacks received for this API request. It accepts a maximum length of 64 characters. |
Response Parameters
| Param Name | Presence | Description |
| STATUS | Always | “Success” or “Failure”. |
| MMSID | Success response only | The ID (bigint) of a saved MMS. |
| ERRORCODE | Error response only | Error code associated with the error. |
| ERRORINFO | Error response only | Error message explaining the error code. |
Request Example: XML
<REQUEST>
<ACTION>saveMMS</ACTION>
<API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/API_KEY>
<SUBJECT>The subject</SUBJECT>
<NAME>The name</NAME>
<FALLBACKSMSTEXT>Fallback Text if this MMS is sent as SMS</FALLBACKSMSTEXT>
<SLIDE>
<IMAGE><URL>https://fake-content-url.com/image.png</URL></IMAGE>
<AUDIO><URL>https://fake-content-url.com/audio.mp3</URL></AUDIO>
<TEXT>Here is some text\rHere is some more text</TEXT>
</SLIDE>
<SLIDE>
<TEXT>This is my contact</TEXT>
<VCARD><URL>https://fake-content-url.com/vcard.vcf</URL></VCARD>
</SLIDE>
<CLIENT_REFERENCE>5ZY7Cx1Xy0vs</CLIENT_REFERENCE>
</REQUEST>Response Example: Success
<RESPONSE>
<STATUS>Success</STATUS>
<MMSID>35674</MMSID>
</RESPONSE>Response Example: Failure
<RESPONSE>
<STATUS>Failure</STATUS>
<ERRORCODE>E225</ERRORCODE>
<ERRORINFO>Too many Slides.</ERRORINFO>
</RESPONSE>Postback Notification
When an MMS is saved and transcoded successfully, the system will generate a postback notification and unlock the MMS template for sending messages. If an MMS contains audio/video, the postback will be sent when the encoding of the MMS audio/video is finished, otherwise, the postback notification will be sent instantly after the image and other content is transcoded in real-time and stored. If you attempt to send an MMS-ID which has not finished encoding, an API error E626 will be returned.
Please see Delivery Report Postback – saveMMS Encoding Status for more detailed information concerning this postback notification.
Merge Tags
You can save an MMS Template with merge tags and those tags will be replaced during delivery of the MMS as long as you pass the variables in the SendSavedMMS request.
For example, here is a saveMMS request with merge tags in the TEXT node:
<REQUEST>
<ACTION>saveMMS</ACTION>
<API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
<SUBJECT>Text with the dynamic variables</SUBJECT>
<NAME>MMS with DynVars</NAME>
<SLIDE>
<IMAGE>
<URL>https://fake-content-url.com/image.png</URL>
</IMAGE>
<TEXT>
Hello {$firstname|customer}, here is a free coupon to celebrate your birthday {$birthday|today}!
</TEXT>
</SLIDE>
</REQUEST>Then in the sendSavedMMS request, the variables are passed inside the DATA node:
<REQUEST>
<ACTION>sendsavedMMS</ACTION>
<API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
<MMSID>43615</MMSID>
<FROM>00000</FROM>
<TO>11111111111</TO>
<CAMPAIGNREF>1807</CAMPAIGNREF>
<DATA>
<FIRSTNAME>Bill</FIRSTNAME>
<BIRTHDAY>1/13/1991</BIRTHDAY>
</DATA>
</REQUEST>General Error Codes
| Code | Description |
|---|---|
| E100 | Invalid request. Make a valid request via GET/POST/XML with all the required variables. |
| E104 | User Authentication Failed. |
| E105 | This account has no API rights. |
| E106 | You can call API every X seconds. |
| E107 | This account has no right to use this action. |
| E108 | XML Parse error: $error. |
| E109 | API not activated. |
| E112 | IP was not whitelisted. API call rejected. |
| E113 | Set throughput exceeded for this API action. API call rejected. |
| E114 | Phone number is blacklisted. API call rejected. |
| E120 | Account has reached the API request limit. |
| E503 | Internal error. |
Related Error Codes
| Code | Description |
|---|---|
| E223 | More than one object is not allowed in the same slide. |
| E224 | MMS audio/video/image are not allowed with object in the same slide. |
| E225 | Too many Slides. |
| E226 | Audio and Video not allowed in same slide. |
| E227 | Video and Image not allowed in same slide. |
| E228 | Text more than X characters. |
| E229 | Content not allowed. |
| E311 | The ‘name’ is required. |
| E312 | No slides. |
| E313 | Slide X is empty. |
| E331 | Image in slide X is too big. |
| E332 | Audio in slide X is too big. |
| E333 | Video in slide X is too big. |
| E334 | Text in slide X is too long. |
| E335 | vCard in slide X is too big. |
| E336 | iCal in slide X is too big. |
| E337 | PDF in slide X is too big. |
| E341 | Image file in slide X is corrupted. |
| E351 | Could not copy Image in slide X. |
| E352 | Could not copy Audio in slide X. |
| E353 | Could not copy Video in slide X. |
| E355 | Could not copy vCard in slide X. |
| E356 | Could not copy iCal in slide X. |
| E357 | Could not copy PDF in slide X. |
| E622 | The ‘fallbacksmstext’ is required. |
| E626 | This content is unavailable at the moment. Encoding is in progress. Please try again later. |
| E652 | Incorrect disablefallbacksms value. It is optional, but accepts only ‘yes’, ‘no’ or ‘’ if set. |
| E1130 | The personalized image template id in slide X is invalid |
| E1131 | Only one personalized image template is allowed per MMS |