Contribute in GitHub:

Setting up MMS messaging with SMS Gateway

SMS Gateway can send or receive images to and from Voice Gateway (VGW), Watson Assistant (WA), or a service orchestration engine (SOE).

The Multimedia Messaging Service (MMS) is a standard way to send multimedia, such as images, over text messaging channels. Users can send and receive MMS messages via SMS Gateway, if they set up their phone number (or numbers) with Twilio Programmable SMS. Twilio imposes restrictions on the size, number, and content type of MMS messages. Currently, Twilio fully supports .jpeg, .gif and .png image formats, and accepts other MIME content types. Users can include up to 10 images in a single message request, but the total message size must not exceed 5 MB. MMS messaging with SMS Gateway is only supported for phone numbers in the US and Canada.

Outbound MMS support

When a service orchestration engine or Watson Assistant sends an MMS message to the user (with or without an SMS text message), one or more publicly accessible media URLs are sent to Twilio. Twilio does not support non-public URLs.

Enable MMS from an SOE or Watson Assistant with SMS Gateway

The SOE or WA adds an smsActSendMedia action command that includes the mediaURL parameter. For more information, see API for SMS Gateway.

Enable MMS with the Pipe request

The SOE or WA configured in Watson Assistant updates the existing vgwActSendSMS action and adds the mediaURL parameter to this action. For more information, see Action tags and state variables in the Voice Gateway API.

The existing REST Pipe APIs are updated with an optional smsMediaURL request variable. The smsMediaURL request variable specifies the publicly accessible URL of the media that is sent in an MMS message. For more information, see Using the REST API to control SMS sessions.

Inbound MMS support

When SMS Gateway receives an MMS request from an SMS provider, the smsMedia state variable is added to the request context. SMS Gateway then either sends the request directly to the WA or SOE, or relays it to Voice Gateway via Pipe request. If Voice Gateway is enabled, it adds the vgwSMSMedia state variable to the context and sends the request to the WA or SOE. For more information, see API for SMS Gateway and Action tags and state variables in the Voice Gateway API.

The following example shows the context of an MMS message request from an SMS Provider containing two image URLs. SMS Gateway adds the smsMedia state variable and a mediaContentType parameter for each URL. It then sends the request to the SOE or WA, or to VGW via Pipe Request.

"smsMedia":[
{"mediaURL":"https://api.twilio.com/2010-04-01/Accounts/ACxxxxxxxxxxxxxxxcac7a6f05427c4bff3/Messages/MM7d78f699365a682f2441cd45496cb3d9/Media/ME61e988e5132dac150axxxxxfaea4a364",  
"mediaContentType":"image/jpeg"},
{"mediaURL":"https://api.twilio.com/2010-04-01/Accounts/ACxxxxxxxxxxxxxxxcac7a6f05427c4bff3/Messages/MM7d78f699365a682f2441cd45496cb3d9/Media/MEaaf3424e479605cbdxxxxx7360cf6ede",   
"mediaContentType":"image/jpeg"}
]

Troubleshooting

If you're using Twilio to send or receive MMS messages via SMS Gateway, the media are stored in your Twilio account. To learn more about managing images, and how to delete them, visit Twilio's Media Resource page.

If an MMS request is successfully sent to the SMS provider but fails to reach the user, check the error log in the MMS provider account that is associated with the request (e.g. Twilio).

Some common errors

Twilio accounts are enabled to send a maximum of 10 media URLs in an MMS message. An MMS message that contains more than 10 URLs produces an error, as shown in the following example.

Error = {\"code\": 21623, \"message\": \"The number of media URLs 13 exceeds the max allowed (10)\", \"more_info\": \"https://www.twilio.com/docs/errors/21623\"

Twilio fully supports only .jpeg, .gif and .png image formats, although other content types might be accepted. If an MMS message contains an unacceptable content type, the following error occurs.

Error
     12300 Twilio is unable to process the Content-Type of the provided URL. Please see the <a href="/docs/api/twiml/">Twilio Markup XML Documentation</a> for more information on valid Content-Types.

For more information about content types, see Twilio's Accepted Content Types for Media.