sendMMS

Synopsis:

Sends an MMS defined in the XML containing slides of embedded with video, audio, images and/or text to a single mobile number in international number format. SendMMS is a minor extension of the saveMMS function. This API function is only available on Dedicated Shortcodes.

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 and is required if the subject is not passed in the request.
  • 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 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.
  • MMS Link Expiration Date is used to expire the link. Depending on this expiration date, the content is disabled on this link. By default it expires 365 days from the date the original MMS was created.

If “Enforce Campaign Check” is turned ON, then this function will require the campaign reference ID of the messaging campaign that the recipient’s phone number is subscribed into to be passed inside the campaignref node.

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

Request: XML

<REQUEST>
    <ACTION>sendMMS</ACTION>
    <API_KEY>apiKey</API_KEY>
    <TO>Recipient phone number</TO>
    <FROM>shortcode</FROM>
    <FROM_MASK>*shortcodeMask</FROM_MASK>
    <OPERATORID>OPERATORID</OPERATORID>
    <CAMPAIGNREF>CampaignReferenceID</CAMPAIGNREF>
    <SUBJECT>MMS Subject</SUBJECT>
    <NAME>Internal Name</NAME>
    <SLIDE> 
        <IMAGE>
            <URL>URL</URL> 
        </IMAGE>
        <AUDIO>
            <URL>**URL</URL>
        </AUDIO>
        <VIDEO>
            <URL>**URL</URL>
        </VIDEO>
        <VCARD>
            <URL>URL</URL>
        </VCARD>
        <ICAL>
            <URL>URL</URL>
        </ICAL>
        <PDF>
            <URL>URL</URL>
        </PDF>
        <PASSBOOK>
            <URL>URL</URL>
        </PASSBOOK>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        ...
    </SLIDE>
    <FALLBACKSMSTEXT>This text replaces the MMS subject when MMS is sent as SMS link</FALLBACKSMSTEXT>
    <DISABLEFALLBACKSMSLINK>'yes' to disable fallback SMS link</DISABLEFALLBACKSMSLINK>
    <MMSLINK_EXPIRATION_DATE>Date in ISO8601 format</MMSLINK_EXPIRATION_DATE>
</REQUEST>

*ShortcodeMask (Alphanumeric sender) is allowed only in few countries. Not supported in United States.
**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=sendmms
&api_key=API key
&to=recipient phone number
&from=shortcode
&from_mask=shortcode mask
&operatorid=operator ID
&campaignref=campaign reference ID
&subject=MMS subject
&name=internal name
&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_duration_#=duration in seconds   (replace '#' with slide number)
&slide_text_value_#=plain text          (replace '#' with slide number)
&fallbacksmstext=this text replaces the MMS subject when MMS is sent as SMS link
&disablefallbacksmslink='yes' to disable fallback SMS link
&mmslink_expiration_date=date in ISO8601 format

Request Parameters:

Mandatory: action, api_key, to, from, name, slide, campaignRef (if "Enforce Campaign Check" is enabled), fallbackSmsText (if subject is not passed)
Optional: operatorid, campaignRef, subject, image, audio, video, url, text, duration, vcard, ical, pdf, passbook, disableFallbackSmsLink

Response Parameters:

status, to, mmsId, trackingId, errorCode, errorInfo

Request Example: XML

<REQUEST>
    <ACTION>sendMMS</ACTION>
    <API_KEY>ea7966f90de2bf520e3f0042053e6ec3</API_KEY>
    <TO>15551234888</TO>
    <FROM>60856</FROM>
    <OPERATORID>000189</OPERATORID>
    <SUBJECT>Free coupon!</SUBJECT>
    <CAMPAIGNREF>Campaign123</CAMPAIGNREF>
    <NAME>Membership coupon</NAME>
    <SLIDE>
        <IMAGE>
            <URL>http://www.yoursite.com/images/welcome.jpg</URL>
        </IMAGE>
        <TEXT>Hi! Thank you for joining us!</TEXT>
        <DURATION>5</DURATION>
    </SLIDE>
    <SLIDE>
        <PASSBOOK>
            <URL>http://www.yoursite.com/pass/coupon.pkpass</URL>
        </PASSBOOK>
        <TEXT>As a new member, here's a free coupon from us!\nPlease enjoy!</TEXT>
        <DURATION>5</DURATION>
    </SLIDE>
</REQUEST>

Request Example: GET

https://secure.skycore.com/API/wxml/1.3/index.php?action=sendmms
&api_key=ea7966f90de2bf520e3f0042053e6ec3
&to=15551234888
&from=60856
&operatorid=000189
&campaignref=Campaign123
&subject=Free coupon!
&name=Membership coupon
&slide_image_url_0=http://www.yoursite.com/images/welcome.jpg
&slide_text_value_0=Hi! Thank you for joining us!
&slide_duration_0=5
&slide_passbook_url_1=http://www.yoursite.com/pass/coupon.pkpass
&slide_text_value_1=As a new member, here's a free coupon from us!\nPlease enjoy!
&slide_duration_1=5

Response Example: Success

<RESPONSE>
    <STATUS>Success</STATUS>
    <TO>15551234888</TO>
    <MMSID>35674</MMSID>
    <TRACKINGID>MMS_12345</TRACKINGID>
    <STATUSDETAILS>MMS request accepted and queued for delivery</STATUSDETAILS>
</RESPONSE>

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E111</ERRORCODE>
    <TO>15551234888</TO>
    <ERRORINFO>Invalid shortcode</ERRORINFO>
</RESPONSE>

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 rights 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.


All saveMMS Error Codes plus E110, E111, E241, E617, E618, E619, E627, E628, E629, E650

Code Description
E110 Invalid receiver number.
E111 Invalid shortcode.
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.
E230 Bad X slide duration.
E241 This content does not exist.
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.
E338 Passbook file 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.
E358 Could not copy Passbook file in slide X.
E617 mmslink_expiration_date is invalid.
E618 Carrier lookup failed. Please retry.
E619 Carrier not provisioned.
E622 The ‘fallbacksmstext’ is required.
E627 Invalid serviceid / serviceid is required
E628 Operator Not supported.
E629 Unrecognized content type.
E650 The ‘operator id’ is required.
E715 Number is not subscribed in this campaign
E718 The ‘campaignref’ is required
E721 Invalid campaignref


Key Term Definitions:

Term Description
ACTION This is the name of the function you want to execute with the API.
API_KEY 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.
CAMPAIGNREF Depending on your API settings, you may be required to subscribe users into a campaign first before sending them messages. If you are required to subscribe a user first, then a valid Campaign Reference is required. This would be the campaign reference ID (string) to which the user is subscribed.
DURATION The duration of a slide displayed in seconds (integer).
FROM A valid shortcode or longcode for the sender address(string). When sending to a list of many numbers using the ‘sendSavedContent’ function and if the ‘FROM’ value cannot be used for a certain country, then the system will re-write the sender address to use a valid shortcode for those numbers.
MMSID The ID(integer) of a saved MMS.
SLIDE This 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).
TEXT The SMS message limit is 160 characters(string).
TO This is the message recipient’s phone number in an international format.
TRACKINGID On success, the API returns with the tracking ID to identify sent messages. Upon API call failure, no tracking ID is returned. Once the message sending is processed you shall receive a postback containing TRACKINGID and the message status.