Messaging - Send media with MMS

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use Telesign Messaging to send an MMS message to an end-user that includes an embedded image, audio file, or video file. The media file is hosted by you.

Before you begin

Make sure you have the following before you start:

• Transaction Callback Service: You need to have this set up so Telesign can send you delivery status updates for the message you send through the Messaging API. See Transaction Callback Service for setup instructions.

🚧

CAUTION:

You can only send MMS messages from US sender IDs and only with short codes.

Steps

1. Send a POST /v1/omnichannel request. Include the following param values:

Request Example

POST /v1/omnichannel HTTP/1.1
Content-Type: application/json
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
  "channels": [
    {
      "channel": "mms",
      "fallback_time": 600
    },
    {
      "channel": "sms"
    }
  ],
  "phone_number": "15558675309",
  "message": {
    "mms": {
      "template": "image",
      "parameters": {
        "url":"https://s3.amazonaws.com/viatu-mktg/bogo_coupon_52359.jpg"
      }
    },
    "sms": {
      "template": "text",
      "parameters": {
        "text": "Buy one get one free! Use code 'BOGO' at checkout on viatushop.com."
      }
    }
  },
  "message_type": "MKT"
}

2. If the request is processed successfully, you should see a response with a 3001 status code.

Response Example

HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 14 Oct 2020 21:25:54 GMT
Content-Type: application/json
Content-Length: 137
Connection: keep-alive
Allow: GET,POST,HEAD
{
  "status": {
    "code": 3001,
    "description": "Message in progress"
  },
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": null
}

3. If the send in MMS format is successful, your end user receives a message on their device that looks like this.

4. If the send in MMS format fails, the service tries to send the next specified backup channel (if any).

5. Updates on the status of this message are sent to the callback URL for your Transaction Callback Service. The general callback schema common to both this and other products is described on Transaction Callback Service. Modifications to the callback schema for this product are described on Callback service. Search for these callbacks based on the reference ID in the response to your original Messaging API request. Each callback payload includes an object with the status of the send for each channel that is tried.

Callback Example

GET /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": "null",
  "status": {
    "code": 3000,
    "description": "Delivered",
    "last_channel": "sms",
    "updated_on": "2020-05-04 22:07:01:226"
  },
  "channel_status": [
    {"mms": {
      "code": 3056,
      "description": "Message failed to deliver in specified fallback time",
      "reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
      "updated_on": "2020-05-04 22:05:00.325"
    }},
    {"sms": {
      "code": 3000,
      "description": "Delivered",
      "reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
      "updated_on": "2020-05-04 22:07:01:226"
    }}
  ]
}

📘

NOTE:

In addition to the reference ID for the Messaging transaction itself, the delivery status payload also includes a reference ID for the message-send on each channel. These can be useful for troubleshooting purposes.