(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.data-privacy-src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TT9ZP96');

Knowledge Base

Save MMS API V2

8 min read

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, image, 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. Not all messaging clients will render the order properly when received.

Content Transcoding

Every MMS template stored using the SaveMMS API will be transcoded to various sizes and formats so that they are readily available to use with SendSavedMMS API to deliver it with correct size and format to the destination handset.

Postback Notification

When an MMS is saved and transcoded successfully, the system will generate an N003 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 are 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 MMS MT POSTBACK: N003 for more detailed information concerning this postback notification.

Fallback SMS

There is a ‘fallback-sms-text’ node whose value is used as the SMS text in the case of MMS is delivered as SMS with an embedded link. If your account is allowed to send fallback sms then this field becomes mandatory. Otherwise, it’s optional.

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 “fallback-sms-text” node. If the “disable-fallback-sms” node is set to boolean value true 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 the boolean value true to the “disable-fallback-sms-link” 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 the boolean value true to the “disable-fallback-sms” 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, this API shall reformat the content so that it can be delivered to the end-users handset in the best possible way when this content is sent using SendSavedMMS API.
  • 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 objects such as contact, calendar or pdf.
  • The API supports 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 the 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 representable 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 audio/video 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, audio/wav, audio/wave
      • .amr = audio/amr
    • Video:
      • .mp4 = video/mp4
      • .mpg, .mpeg = video/mpeg, video/mpg
      • .avi = video/x-msvideo, video/avi
      • .wmv = video/x-ms-wmv, video/x-ms-asf
      • .mov = video/quicktime
      • .3gp = video/3gpp, video/3gp
    • 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 the current maximum limits from your Account Manager.

Request: JSON

curl -X POST \ 
     -H "x-api-key: {Api Key}" \
     -H "content-type: application/json" -d '
      {
          "action": "savemms",
          "message-subject": "MMS_SUBJECT_TEXT",
          "fallback-sms-text": "FALLBACK_SMS_TEXT",
          "disable-fallback-sms-link": true/false
          "disable-fallback-sms": true/false,
          "client-reference": "CLIENT_REFERENCE",
          "name": "MMS_TEMPLATE_NAME",
          "slide": [
              {
                  "image": {
                      "url": "IMAGE_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "audio": {
                      "url": "AUDIO_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "video": {
                      "url": "VIDEO_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "contact": {
                      "url": "CONTACT_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "calendar": {
                      "url": "CALENDAR_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "pdf": {
                      "url": "PDF_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Success Response: JSON

{
    "status": "success",
    "mms-id": "MMS_ID_OF_NEW_MMS_TEMPLATE_CREATED"
}

Failure Response: JSON

{
    "status": "failure",
    "error-code": "ERROR_CODE",
    "error-info": "ERROR_INFO"
}

Request Parameters

Param NameOptional/Mandatory; DatatypeDescription
x-api-keyMandatory; StringAuthentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
actionMandatory; StringExplains the action for this API Request. Value is Case-Insensitive.
message-subjectOptional; StringMMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject.
fallback-sms-textOptional, Mandatory if “disable-fallback-sms” node is set to “false”; StringText which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability.
disable-fallback-smsOptional; BooleanSet to true/false to disable the SMS fallback.
disable-fallback-sms-linkOptional; BooleanSet to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text.
client-referenceOptional; StringCustomer Transaction ID for the request. Use it to match the postbacks received for this API request. It accepts a maximum length of 64 characters.
nameMandatory; StringMMS template name for internal reference only.
slideMandatorySlide node containing all the contents of the slides. Max 9 slides. Each slide may contain one content URL and/or a message text.
slide:$contentOptional; StringSlide content node which contains the content URL. Acceptable slide content includes:

image
audio
video
contact
calendar
pdf
message-text
slide:$content:urlMandatory; StringPublic content URL where the content is accessible.
slide:message-textOptional; StringText 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.

Response Parameters

Param NamePresenceDescription
statusAlways“success” or “failure”.
status-detailsSuccess response onlyMore details about the status.
mms-idSuccess response only MMS Template ID.
error-codeError response onlyError code associated with the error.
error-infoError response onlyError message explaining the error code.

Request Examples

Example 1:
curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "savemms",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "name": "deal1234",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermifflinco.com"
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 2:
curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
            {
          "action": "savemms",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "disable-fallback-sms": false,
          "disable-fallback-sms-link": false,
          "client-reference": "5ZY7Cx1Xy0vs",
          "name": "deal1234",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! "
              },
              {
                  "audio": {
                      "url": "https://fake-content-url.com/audio.mp3"
                  },
                  "message-text": "Please listen to the audio for more info. "
              },
              {
                  "video": {
                      "url": "https://fake-content-url.com/video.mp4"
                  },
                  "message-text": "Or watch the video for more info instead. "
              },
              {
                  "contact": {
                      "url": "https://fake-content-url.com/contact.vcf"
                  },
                  "message-text": "Contact us if you have any questions. "
              },
              {
                  "calendar": {
                      "url": "https://fake-content-url.com/calendar.ics"
                  },
                  "message-text": "Check the calendar for upcoming events. "
              },
              {
                  "pdf": {
                      "url": "https://fake-content-url.com/pdf.pdf"
                  },
                  "message-text": "And check the pdf for all other details."
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Response Example: Success

{
    "status": "success",
    "mms-id": "123456"
}

Response Example: Failure

{
    "status": "failure",
    "error-code": "E311",
    "error-info": "Invalid MMS Name or MMS Name is required."
}
Go to Top