Save MMS API

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