MMS Channel

MMS support in Conversation API is integrated via the Sinch MMS MM7 API: MM7 API

To be able to use the MMS channel in Conversation API, you need to have an MMS Account at Sinch. More information in the MMS documentation.

Channel Configuration

You need a Sinch MMS Account in order to integrate with MMS channel. Your account manager can help you with the creation and configuration of MMS for your Conversation API app. You can request this through the Sinch Portal. Just select your app and click on "SET UP CHANNEL" beside the MMS channel.

You will receive four pieces of credentials which you can then use in the Sinch Portal to finish the MMS integration for your Conversation API app. These credentials are:

• MMS Account ID
• MMS API Key
• Default Sender
• Basic Authentication Username
• Basic Authentication Password

Alternatively, you can use the management API to configure your app with channel_credentials for the MMS channel. The example snippet below shows the credentials configuration for the MMS channel:

{
  "channel_credentials": [
    {
      "channel": "MMS",
      "mms_credentials": {
        "account_id": "{{MMS_ACCOUNT_ID}}",
        "api_key": "{{MMS_API_KEY}}",
        "default_sender": "{{DEFAULT_SENDER}}",
        "basic_auth": {
          "username": "{{BASIC_AUTH_USERNAME}}",
          "password": "{{BASIC_AUTH_PASSWORD}}"
        }
      }
    }
  ]
}

You need to replace:

• {{MMS_ACCOUNT_ID}} with your MMS Account ID
• {{MMS_API_KEY}} with your MMS API Key
• {{DEFAULT_SENDER}} with your Default Sender (shortcode or longnumber), will be used when {{YOUR_MMS_SENDER}} in a message is empty
• {{BASIC_AUTH_USERNAME}} with your Basic Authentication username for the MMS API
• {{BASIC_AUTH_PASSWORD}} with your Basic Authentication password for the MMS API

Don't forget to create at least one Conversation API webhook which will trigger POST callbacks to the given URL. You can do that from the Sinch Portal or programmatically using the management API.

Sending Messages

Some rich messages are natively supported by MMS channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way MMS renders the messages on mobile devices.

When sending a message on MMS channel you're expected to specify a sender - a shortcode or longnumber. This information should be passed in each message request under channel_properties -> `MMS_SENDER. See a full request example below.

Conversation API POST messages:send

{
  "app_id": "{{APP_ID}}",
  "recipient": {
    "contact_id": "{{CONTACT_ID}}"
  },
  "message": {
    "text_message": {
      "text": "Text message from Sinch Conversation API."
    }
  },
  "channel_priority_order": ["MMS"],
  "channel_properties": {
    "MMS_SENDER": "{{YOUR_MMS_SENDER}}"
  }
}

You need to replace {{YOUR_MMS_SENDER}} with your shortcode or longnumber.

Text Messages

MMS channel supports text messages natively.

The following image gives an example of a text message.

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Messages

MMS supports media messages natively. The content of the media message will be validated when sending messages, and checked against the recommendations for MMS messages listed in the MMS documentation if you use the MMS_STRICT_VALIDATION flag.

In this message you can send the following media types on MMS channel:

• image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
• video: .mp4, .gif, .mov
• vCard (Virtual Contact File): .vcf
• PDF files: .pdf

We recommend you to keep media file sizes under 1MB as MMS providers usually use this limit.

The following image gives an example of a media message.

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Messages

MMS doesn't natively support Choice messages therefore they're transcoded and sent as text messages by Conversation API.

The following image gives an example of a choice message.

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Messages

MMS natively supports card messages.

The title of the card message will be used as the Subject of the MMS message. The title will not be duplicated in the message body content. The maximum length of the title is 80 characters, though 40 characters and under is recommended for best deliverability.

Using media in a card message is optional. If you choose to add media, the content can be checked against the recommendations for MMS messages listed in the MMS documentation if you use the MMS_STRICT_VALIDATION flag.

In this message, you can send the following media types on MMS channel:

• image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
• video: .mp4, .gif, .mov
• vCard (Virtual Contact File): .vcf
• PDF files: .pdf

We recommend you to keep media file sizes under 1MB, as MMS providers usually use this limit.

The following image gives an example of a card message (presentation may vary by device-type/carrier):

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Messages

MMS doesn't natively support Carousel messages and so they're transcoded and sent as text messages by Conversation API.

The following image gives an example of a carousel message.

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Messages

MMS doesn't natively support location messages, and so they're transcoded and sent as text messages by Conversation API.

The following image gives an example of a location message.

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Receiving Messages

Messages sent by your contacts will only arrive on MMS channel if they were recognized as MMS on the sender device. This means a contact messages that:

• contain media attachment only
• contain both media attachment and plain text
• any message that uses the MMS "Subject" field

This implies that a plain text contact message will be seen as SMS by the device, therefore it won't be routed as an MMS, and it won't reach your Conversation API App on MMS channel. However, you can use the sender that you have provisioned for MMS to be configured for your Sinch SMS service plan as well. In a setup like that the following scenario is possible:

1. You have an SMS and an MMS account at Sinch, having the same sender shortcode/longnumber configured for them
2. You have a Conversation API app configured with MMS and SMS channels with the above mentioned accounts
3. You send a message to your contact using your Conversation API App on MMS channel
4. Your contact responds with plain text SMS
5. You get the MESSAGE_INBOUND webhook for the contact message on SMS channel even though you initiated the conversation on MMS

Supported contact messages

MMS supports contact initiated messages like Text, Media, MediaCard, and Choice Responses.

If the contact message had media attachments the media content is hosted by Sinch and you get a publicly accessible URL pointing to it. Please note that the media URLs included in the contact messages are valid for 7 days. After that the media is deleted from Conversation API storage.

Conversation API POST to MESSAGE_INBOUND webhook for text message:

{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Hi from contact"
      }
    },
    "channel": "MMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}

On MMS it's possible that your contact sends you multiple media attachments. In this case Conversation API will forward these one by one to your webhook. For example, if the contact sends you 3 images you will get 3 separate media messages on your webhook.

Conversation API POST to MESSAGE_INBOUND webhook for media message:

{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "https://convapi-eu1tst.s3.eu-west-1.amazonaws.com/01EPRZJ0HXTDEH1BTYJT4417GE/01F2K124T4513Q0CCHQ5SN0DH6.png"
      }
    },
    "channel": "MMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}

On MMS it's possible that your contact sends you multiple media attachments with text included. In this case Conversation API will forward these one by one to your webhook. For example, if the contact sends you 3 images with a text you will get 3 separate media card messages on your webhook, with 3 different media urls and the same caption for each.

Conversation API POST to MESSAGE_INBOUND webhook for media card message:

{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "media_card_message": {
        "url": "https://convapi-eu1tst.s3.eu-west-1.amazonaws.com/01EPRZJ0HXTDEH1BTYJT4417GE/01F2K124T4513Q0CCHQ5SN0DH6.png",
        "caption": "caption text"
      }
    },
    "channel": "MMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}

A choice response message means that your contact responded with a suggested text reply from your previous message. Since a plaintext response won't always be routed as MMS, you might get this choice response on SMS channel (see description of this scenario at: Receiving Messages).

Conversation API POST to MESSAGE_INBOUND webhook for choice response message:

{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01EKJ2SWHGDMYA0F0F1PQJ09WQ",
        "postback_data": "postback"
      }
    },
    "channel": "MMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}

Receiving Delivery Receipts

Messages sent on MMS channel have two statuses: DELIVERED, and FAILED. READ status is not supported on the channel.

Below is an example for DELIVERED receipt - FAILED differs by the status and reason only.

Conversation API POST to MESSAGE_DELIVERY webhook:

{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-23T09:55:04.766Z",
  "message_delivery_report": {
    "message_id": "01E6K7CMXY3KHH0AGCTY6D04F2",
    "conversation_id": "01E6JY5HMCADX31SANQ0YE0CH6",
    "status": "DELIVERED",
    "channel": "MMS",
    "reason": "",
    "metadata": ""
  }
}