Save MMS API

Table of Contents

SaveMMS

Synopsis:

This API stores an MMS from XML. The MMS may contain slides embedded with video, audio, images and text. Once the MMS is saved, it can be utilized by other functions through the MMSID returned. The legacy format is still supported at this time, but it is recommended that developers update to the most recent format at their earliest convenience.

When MMS is sent as SMS, the fallback SMS text and link are sent.

  • The fallback SMS text is the text used in place of the MMS subject when MMS is sent as SMS. It is required if the subject is empty.
  • The fallback SMS link is the link that hosts the MMS content. The fallback SMS link may be disabled for this MMSID by passing ‘yes’ to the DISABLEFALLBACKSMSLINK node. In this case only the MMS subject or the fallback SMS Text is sent. By default, we always send the fallback SMS link along with the fallback SMS text or the MMS subject.
  • The fallback SMS can be completely disabled by passing ‘yes’ to the DISABLEFALLBACKSMS node. By default the fallback SMS is enabled. If the MMS will be sent as SMS while the fallback SMS is disabled, then the message will fail to send instead.

Line breaks are supported in the slide texts of the MMS.

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>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <AUDIO>
            <URL>*URL</URL>
        </AUDIO>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <VIDEO>
            <URL>*URL</URL>
        </VIDEO>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <VCARD>
            <URL>URL</URL>
        </VCARD>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <ICAL>
            <URL>URL</URL>
        </ICAL>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <PDF>
            <URL>URL</URL>
        </PDF>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <PASSBOOK>
            <URL>URL</URL>
        </PASSBOOK>    
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        <PERSONALIZED-IMAGE>
            <TEMPLATE-ID>Personalized image template id</TEMPLATE-ID>
        </PERSONALIZED-IMAGE>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        ...
    </SLIDE>
</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: GET

API_URL?action=savemms
&api_key=API key
&subject=subject
&name=name to save it as
&fallbacksmstext=fallback Text if this MMS is sent as SMS
&disablefallbacksms='yes' to disable fallback SMS
&disablefallbacksmslink='yes' to disable fallback SMS link
&slide_image_url_#=image URL                                            (replace '#' with slide number)
&slide_audio_url_#=audio URL                                            (replace '#' with slide number)
&slide_video_url_#=video URL                                            (replace '#' with slide number)
&slide_vcard_url_#=vCard URL                                            (replace '#' with slide number)
&slide_ical_url_#=iCal URL                                              (replace '#' with slide number)
&slide_pdf_url_#=PDF URL                                                (replace '#' with slide number)
&slide_passbook_url_#=passbook URL                                      (replace '#' with slide number)
&slide_personalized_image_template_id_#=personalized image template id  (replace '#' with slide number)
&slide_duration_#=duration in seconds                                   (replace '#' with slide number)
&slide_text_value_#=plain text                                          (replace '#' with slide number)

Request Parameters:

Mandatory: action, api_key, name, slide, fallbackSmsText
Optional: disableFallbackSms, disableFallbackSmsLink, subject, image, audio, video, url, text, duration, vcard, ical, pdf, passbook, personalized-image, template-id

Response Parameters:

status, mmsId, errorCode, errorInfo

Request Example: XML

<REQUEST>
    <ACTION>saveMMS</ACTION>
    <API_KEY>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</API_KEY>
    <SUBJECT>The subject</SUBJECT>
    <NAME>The name</NAME>
    <FALLBACKSMSTEXT>Fallback Text if this MMS is sent as SMS</FALLBACKSMSTEXT>
    <SLIDE>
        <IMAGE><URL>http://www.yoursite.com/images/1.jpg</URL></IMAGE>
        <AUDIO><URL>http://www.yoursite.com/audio/1.mp3</URL></AUDIO>
        <TEXT>Here is some text\rHere is some more text</TEXT>
        <DURATION>5</DURATION>
    </SLIDE>
    <SLIDE>
        <TEXT>This is my contact</TEXT>
        <VCARD><URL>http://www.yoursite.com/vcard/2.vcf</URL></VCARD>
        <DURATION>5</DURATION>
    </SLIDE>
</REQUEST>

Request Example: GET

API_URL?action=savemms
&api_key=qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ
&subject=The subject
&name=fishtank
&fallbacksmstext=Fallback Text if this MMS is sent as SMS
&slide_image_url_0=http://www.yoursite.com/images/1.jpg
&slide_audio_url_0=http://www.yoursite.com/audio/1.mp3
$slide_text_value_0=Here is some text\rHere is some more text
&slide_duration_0=5
&slide_text_value_1=This is my contact
&slide_vcard_url_1=http://www.yoursite.com/vcard/2.vcf
&slide_duration_1=5

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, the system will generate a Postback notification and unlock MMS for further use. If an MMS contain audio/video, Postback will be sent when the encoding of the MMS audio/video is finished, otherwise Postback notification will be sent instantly. For more information, please visit the SaveMMS Encoding Status section of the Delivery Report Postback documentation.

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:

<REQUEST>
    <ACTION>saveMMS</ACTION>
    <API_KEY>*********************************************</API_KEY>
    <SUBJECT>Text with the dynamic variables</SUBJECT>
    <NAME>MMS with DynVars</NAME>
    <SLIDE>
        <IMAGE>
            <URL>http://www.destination360.com/caribbean/bahamas/images/s/bahamas-boat-rental.jpg</URL>
        </IMAGE>
        <TEXT>
            Hello {$firstname|Sir}, your gender is {$gender|unknown}.
        </TEXT>
    </SLIDE>
</REQUEST>

Then inside sendsavedMMS we do call this:

<REQUEST>
    <ACTION>sendsavedMMS</ACTION>
    <API_KEY>*********************************************</API_KEY>
    <MMSID>43615</MMSID>
    <FROM>66666</FROM>
    <TO>16502426058</TO>
    <CAMPAIGNREF>1807</CAMPAIGNREF>
    <DATA>
        <FIRSTNAME>Bill</FIRSTNAME>
        <GENDER>Male</GENDER>
    </DATA>
</REQUEST>

and within the delivered MMS we will have this: “Hello Bill, your gender is male.”

Special Considerations for saveMMS:

  • The API SHALL reformat the content when necessary so that it can be delivered to the end users handset in the best possible way.
  • 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 XHTML/SMS.
  • Each request MUST contain at least one slide which MAY contain text and/or image and/or video and/or audio and/or objects (vcard/ical/pdf/passbook/personalized image).
  • The API SHALL support up to 80 characters in the MMS subject.
  • The API SHALL support up to 8 slides for each MMS submission.
  • The API SHALL NOT support multiple files of the same MIME type on the same slide.
  • Slides with image 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/passbook/personalized image object SHALL NOT support media type audio/video/image and vice-versa.
  • Only one personalized image template is allowed per MMS template.
  • All slides MAY contain a duration for playback.
  • Default slide duration is 10 seconds.
  • Slide duration will be overwritten with the audio/video file duration after encoding is completed.
  • URLs provided MUST contain the full path to the mime files.
  • Slide Duration SHOULD NOT exceed 30 seconds.
  • MMS subject is required.
  • MMS containing audio/video can be used only when audio/video encoding is completed.
  • After submission you will not be given a successful acknowledgement of audio/video encoding when a message is submitted
  • The HTTP status of audio/video encoding after it has been completed will be sent to your Postback URL.
  • Supported Media: TEXT/PLAIN, GIF/JPG/PNG, MP3/WAV, 3GP, MP4, MPEG, MPG, AVI, WMV.
  • 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.
  • MMS messages are delivered in B64 encoding To estimate the final size of Base64-encoded binary data multiply the filesize by 1.37 times the original data size + 814 bytes (for headers).

General Error Codes:

CodeDescription
E100Invalid request. Make a valid request via GET/POST/XML with all the required variables.
E104User Authentication Failed.
E105This account has no API rights.
E106You can call API every X seconds.
E107This account has no rights to use this action.
E108XML Parse error: $error.
E109API not activated.
E112IP was not whitelisted. API call rejected.
E113Set throughput exceeded for this API action. API call rejected.
E114Phone number is blacklisted. API call rejected.
E120Account has reached the API request limit.
E503Internal error.
CodeDescription
E223More than one object is not allowed in the same slide.
E224MMS audio/video/image are not allowed with object in the same slide.
E225Too many Slides.
E226Audio and Video not allowed in same slide.
E227Video and Image not allowed in same slide.
E228Text more than X characters.
E229Content not allowed.
E230Bad X slide duration.
E311The ‘name’ is required.
E312No slides.
E313Slide X is empty.
E331Image in slide X is too big.
E332Audio in slide X is too big.
E333Video in slide X is too big.
E334Text in slide X is too long.
E335vCard in slide X is too big.
E336iCal in slide X is too big.
E337PDF in slide X is too big.
E338Passbook file in slide X is too big.
E341Image file in slide X is corrupted.
E351Could not copy Image in slide X.
E352Could not copy Audio in slide X.
E353Could not copy Video in slide X.
E355Could not copy vCard in slide X.
E356Could not copy iCal in slide X.
E357Could not copy PDF in slide X.
E358Could not copy Passbook file in slide X.
E622The ‘fallbacksmstext’ is required.
E652Incorrect disablefallbacksms value. It is optional, but accepts only ‘yes’, ‘no’ or ‘’ if set.
E1130The personalized image template id in slide X is invalid
E1131Only one personalized image template is allowed per MMS

Key Term Definitions:

TermDescription
ACTIONThis is the name of the function you want to execute with the API.
API_KEYRandom 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.
DURATIONThe duration of a slide displayed in seconds (integer).
MMSIDThe ID(integer) of a saved MMS.
SLIDEThis represents a single slide within the MMS sequence the could include IMAGE/URL/TEXT/PIC etc. (There are special rules for slides within the ‘saveMMS’ special consideration section).
TEXTThe SMS message limit is 160 characters(string).