Before you start

You must have an MMS-enabled number before you can use MMS
You need an MMS-enabled phone number to be able to send MMS from your account. Contact your customer success manager to arrange one.
Supported countries
The MMS channel can deliver messages to phone numbers registered in the following countries only:
- Canada
- The USA

Channel identifier

In the API this channel can be referenced using: mms

This identifier can be used in the rules array, and customBody sections.

Send an MMS

To send an MMS through the API:

ensure that your channel rules include the mms channel.
specify either a phoneNumber in international format or a profileId with a phone number in the to section of your request.
This must be a number registered in one of the supported countries for the MMS channel.
provide a body message:
- define a text/plain message part with the text element of your MMS.
- define 1-10 image parts to be delivered with the text message.

{
  "to": {
    "phoneNumber": "17123123123"
  },
  "channelOptions": {
    "mms": {
      "from": "15166668399"
    }
  },
  "rules": [
    "mms"
  ],
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Check out our latest laptop deals!"
    },
    {
      "name": "Laptop",
      "type": "image/png",
      "url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png"
    }
  ]
}

Sending a vCard

vCard's can be sent via MMS to distribute contact cards.

To send a vCard you will need to create a compliant vCard .vcf file and ensure it is hosted on a publicly accessible secure (HTTPS) url.

Recommended .vcf file structure

You need to create a text file and save it with the .vcf extension.
To be a valid VCF file it needs to contain the following properties:

BEGIN:VCARD
VERSION:3.0
...
END:VCARD

Example fully formed VCF file:

BEGIN:VCARD
VERSION:3.0
FN:{company-name}
ORG:{company-name}
PHOTO;TYPE=JPEG;ENCODING=BASE64:{base64-encoded-logo}
TEL;TYPE=WORK,VOICE:{phone-number}
EMAIL:{email-address}
URL:{url}
ADR;TYPE=WORK:{address};;;;;;;
END:VCARD

Where the following variables are present, data should be adherant to the VCF 3.0 specifications

Variable	Description
{company-name}	Name of the company
{base64-encoded-logo}	A JPEG or PNG logo which has been encoded with base64 and is no larger than 750KB and 800x800px
{phone-number}	Company phone number in E.164 format
{email-address}	Company email address
{url}	Company web site

To send simply include the vCard as a message part of type text/vcard in your send request as demonstrated below:

{
  "to": {
    "phoneNumber": "17123123123"
  },
  "channelOptions": {
    "mms": {
      "from": "15166668399"
    }
  },
  "rules": [
    "mms"
  ],
  "messageParts": [
    {
      "type": "text/plain",
      "data": "Hello 👋 this is a contact card MMS"
    },
    {
      "name": "Dotdigital",
      "type": "image/png",
      "url": "https://upload.wikimedia.org/wikipedia/en/c/c4/Dotdigital_logo_2019.png"
    },
    {
      "name": "Dotdigital.vcf",
      "type": "text/vcard",
      "url": "{URL to hosted .vcf file}"
    }
  ]
}

MMS message limits

When sending MMS messages you must stay within the following constraints:

The maximum length of text part of the MMS is 1600 characters.
Only a single text/plain part can be included.
A minimum of one and a maximum of 10 image parts can be included.
The maximum size of each image cannot exceed 750,000 bytes or 732KB.
You can only send to phone numbers registered in supported countries.

Channel options

The following additional channel options can be used to control the MMS channel’s most common options.

To use the channel options create a object with your options in the requests channelOptions section in the mms property:

Property	Type	Description
from	string	The MMS-enabled phone number you are sending from.
allowUnicode	Boolean	Determines whether Unicode characters are allowed in the message body or not.
unicodeConversion	Unicode conversion settings object	The settings for controlling automatic Unicode conversion

Unicode conversion settings object

Property	Type	Description
convertUnicodeToGsm	Boolean	Determines whether we try to convert Unicode characters to their closest match in the GSM character set or not.
customReplacements	array (Replacement object)	A list of specific Unicode character mappings to apply to the Unicode conversion, overriding the default mappings.

Replacement object

Property	Type	Description
from	string	The single Unicode character to map from.
to	string	The GSM character to map to.

{
  "body": "Sending SMS with the One API is easy!",
  "to": {
    "phoneNumber": "447123123123"
  },
  "channelOptions": {
  	"sms": {
  		"from": "Acme",
  		"allowUnicode": true
  	}
  },
  "rules": [
    "sms"
  ]
}

{
  "body": "Dzień dobry, w czym mogę pomóc?",
  "to": {
    "phoneNumber": "447123123123"
  },
  "channelOptions": {
    "sms": {
      "from": "Comapi",
      "allowUnicode": false,
      "unicodeConversion": {
        "convertUnicodeToGsm": true
      }
    }
  },
  "rules": [
    "sms"
  ]
}

{
  "body": "Dzień dobry, w czym mogę pomóc?",
  "to": {
    "phoneNumber": "447990766636"
  },
  "channelOptions": {
    "sms": {
      "from": "Comapi",
      "allowUnicode": false,
      "unicodeConversion": {
        "convertUnicodeToGsm": true,
        "customReplacements": [
          {
            "from": "ó",
            "to": "o"
          },
          {
            "from": "ń",
            "to": "n"
          }
        ]
      }
    }
  },
  "rules": [
    "sms"
  ]
}

Automatically remove Unicode characters

We offer an optional feature for the MMS channel to convert Unicode characters to GSM-based characters. This feature tries to map Unicode characters to a visually similar character in the GSM alphabet, for example, the character ą would be mapped to a, or ś to s.

To enable this feature, specify a unicodeConversion object and ensure the convertUnicodeToGsm is set to true. You can specify custom replacement character mappings if you want to.

With the option enabled, the following message is converted from "Dzień dobry, w czym mogę pomóc?" to "Dzien dobry, w czym moge pomoc?" removing all the Unicode characters automatically.

🚧
Replacements not guaranteed
The library tries to convert most common Unicode characters used in Latin-based character sets to a GSM equivalent, but we cannot guarantee that it can detect and replace them all.
If there are specific mappings you want to address, you can add your own character mappings by specifying an array of mappings in the customReplacements array under the unicodeConversion node. A custom set of mappings replaces the default set.

Receipts and inbounds

To receive feedback or inbound messages from MMS sends please see the following:

📘
Inbound MMS
We don’t support receiving MMS; usually if a customer replies to an MMS it is text-based and is sent as an SMS.

Receipts

If you need to to know the status of messages you've sent using one of our APIs, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system.

You can receive the following types of receipts:

Sent
Delivered
Expired
Failed