You need a MMS enabled number before you can use MMS
You need a MMS enabled phone number to be able to send MMS from your account. Please contact your customer success manager to arrange one.
Send MMS messages with text and up to 10 images to recipients in supported countries.
Channel Identifier
In the API this channel can be referenced using: mms
This identifier can be used in the rules array, and customBody sections.
Supported countries
The MMS channel can deliver messages to phone numbers registered in the following countries only:
- Canada
- U.S.A
Sending an MMS
Sending an MMS via the API is very simple all you required to is:
- 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, and provide a body message to send the MMS to. This would need to be number registered in one of the supported countries for the MMS channel.
- 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"
}
]
}
MMS Message Limits
When sending MMS messages you must stay within the following constraints:
- The maximum length of text part of the MMS 1600 characters.
- Only a single
text/plain
part may be included. - A minimum of 1 and a maximum of 10 image parts may be included.
- The maximum size of each image sent via MMS 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 SMS channels most common options. To use the channel options create a object with your options in the requests channelOptions section in the sms property:
Property | Type | Description |
---|---|---|
from | string | The MMS enabled phone number you are sending from |
allowUnicode | boolean | This toggles whether having Unicode characters in the text part of the MMS message will be allowed or not |
unicodeConversion | Unicode conversion settings object | The settings for controlling automatic Unicode conversion |
Unicode conversion settings object
Property | Type | Description |
---|---|---|
convertUnicodeToGsm | boolean | This toggles whether we will 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"
]
}
How to remove Unicode characters automatically
We offer an optional feature for the SMS channel to convert Unicode characters to GSM based characters, which could possibly save you money on your messaging. This feature will try to map Unicode characters to a visually similar character in the GSM alphabet e.g. 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, and specify a custom replacement character mappings if required.
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 will try to convert most common Unicode characters used in Latin based character sets to a GSM equivalent, but we cannot guarantee it will detect and replace them all. You may however add your own character mappings if there are specific mappings you want to address 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:
We do not support receiving MMS; usually if a customer replies to an MMS it is text based and is sent as an SMS.
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. See the events in the Message Events section for more details on the receipt events you can receive.
You can receive the following types of receipts:
- Sent
- Delivered
- Expired
- Failed