Sending MMS Messages

MMS ALPHA Release Notes

Bulletin Connects MMS service is in ALPHA release. Contact Bulletin if you would like to try the service and provide your feedback and we will provide you with the necessary credentials and URLs to use.

MMS messages can include media such as sound and image files as well as long form text making it a powerful way to get your message across. While not as ubiquitous as SMS, MMS support on handsets has increased dramatically over the past few years and carriers are increasingly becoming more connected and therefore more suitable for marketing and information services.

Bulletin uses Vodafone NZ as its MMS partner. Your messages are submitted to Vodafone who then distribute it to their partner networks and onto the handsets. Because the media messages are changed to suit the client handsets the delivery process from the carriers is not as efficient as you have come to expect from SMS. Messages may also be formatted differently on consumer handsets so if you have any specific requirements for formatting you should test your messages on handsets in your target market.

Bulletin Connect MMS Messaging URLs

The Bulletin Connect MMS HTTP interface is composed of two methods: one to send a message and one to receive receipts.

Action	URL to Use
Sending Messages	http://mms.alpha.bulletinconnect.net/api/1/mms/out
Polling for Incoming Messages	not available
Receiving Status Updates	not available

Sending MMS Messages

To send a MMS message, the user has to provide two types of information:

Method parameters. (userId, password, to and subject)
Uploaded files: The SMIL file and attachments.

Use HTTP POST to send messages to http://service.bulletinconnect.net/api/1/mms/out.

The HTML specification describes form encoding like this:
application/x-www-form-urlencoded
Forms submitted with this content type must be encoded as follows:

Control names and values are escaped. Space characters are replaced by '+', and then reserved characters are escaped as described in RFC1738, section 2.2: Nonalphanumeric characters are replaced by '%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character
The control names/values are listed in the order they appear in the document. The name is separated from the value by '=' and name/value pairs are separated from each other by '&'.

Most HTTP libraries include convenient methods to make form encoding easy.

N.B. The number and order of parameters may vary. While the parameter names described in this document will not change, additional parameters may be added to the API from time to time

The files have to be uploaded to the Bulletin Connect server by using multipart/formdata
web post rfc1867 and the SMIL file has to be the first one to submit.

Recognised URL encoded parameters for sending MMS messages are:

Name (case sensitive)	Description	Required?
userId	User name for authentication	YES
password	Password for authentication	YES
to	Destination MSISDN(s)	YES Use International Format
subject	The subject of the MMS message	NO
messageId	Client message identifier Use this for tracking message status information for retrying due to errors or delays.	NO

Required uploads: SMIL and attachments

The SMIL file has to meet the SMIL2.0 Specification defined at http://www.w3.org/TR/smil20/. To enforce that, Bulletin Connect checks the user provide SMIL file against schemas defined at http://www.w3.org/2001/SMIL20/smil20.xsd.

Note: SMIL is based on XML and the tags are case sensitive. All SMIL tags requires lowercase letters.

A SMIL file contains all the information necessary to describe a multimedia presentation.

A SMIL file contains the following:

The layout of the presentation
The time line of the presentation
The source of the multimedia elements

NB: Bulletin Connect requires the user to add the name space (xmlns="http://www.w3.org/2001/SMIL20/") in to the SMIL file, otherwise the request will be rejected with an error code 400.

Example:

<smil xmlns="http://www.w3.org/2001/SMIL20/">
  <head>
    <meta name="title" content="mms"/>
    <meta name="author" content="John Smith"/>
    <layout>
      <root-layout width="352" height="144"/>
      <region id="Image" width="176" height="144" left="0" top="0"/>
      <region id="Text" width="176" height="144" left="176" top="0"/>
    </layout>
  </head>
  <body>
    <par dur="8000ms">
      <img src="FirstImage.jpg" region="Image"/>
      <text src="FirstText.txt" region="Text"/>
      <audio src="FirstSound.amr"/>
    </par>
  </body>
</smil>

For attachments, Bulletin Connect does not make any restrictions on types of attachments that the user can upload. As a result, it is the users responsibility to tell Bulletin Connect the content type for each attachment (mime types and charset).
However, Bulletin Connect does check on all the uploaded files to see if they are of the following types by checking the magic number defined in the headers

File type	Extension	MIME type
Bzip2	bz2	application/xbzip2
GNU Zip	gz	application/xgzip
Rar	rar	application/xrarcompressed
PKWare Zip	ZIP	application/zip
Midi	MID	audio/unknown
MPEG audio	mp3	audio/mpeg
Adaptive MultiRate	AMR	audio/amr
Adaptive MultiRate Wideband	AMRWB	audio/amr
Microsoft Word File Format	DOC	application/msword
Hypertext Markup Language	HTML	text/html
Extensible Markup Language	XML	text/xml
Portable Document Format	PDF	application/pdf
PostScript	PS	application/postscript
Rich Text Format	RTF	text/rtf
Microsoft Excel Format	xls	application/vnd.msexcel
Windows Bitmap	BMP	image/bmp
Graphics Interchange Format	GIF	image/gif
Joint Photographic Experts Group	JPG	image/jpeg
Portable Bitmap	PBM	image/xportablebitmap
Portable Graymap	PGM	image/xportablegreymap
Portable Network Graphics	PNG	image/png;png
Portable Pixmap	PPM	image/xportablepixmap
Tag Image File Format	TIFF	image/tiff
Audio Video Interleave	AVI	video/xmsvideo
Quicktime video	MOV	video/quicktime
3GPP Multimedia File	3GP	audio/3gpp video/3gpp

For example, if the file uploaded is recognised as a JPG , Bulletin Connect will check if the user sets the mime type to be image/jpeg. If not, Bulletin Connect will change the mime type to image/jpeg and log an error (so the message will still be sent out).

Bulletin Connect also does some level of parsing on the SMIL file. It recognises 4 types of elements

<img>
<text>
<audio>
<ref>
So if the SMIL has elements like this:
<img src="myimage.jpg">

Bulletin Connect will expect to see a file with the same name to be uploaded. Otherwise, it will return error code 400 followed by a string:

The attachment: myimage.jpg registered in smil was not uploaded!

If the src attributes starts with string "http://" or "cid:"(case insensitive), Bulletin Connect will ignore such attachments. So absence of such attachments in the uploaded files will not cause any issue.
Due to the complexity of SMIL files, Bulletin Connect only parses the SMIL file to some degree. As a result, it is NOT judged as an error when user uploaded some files that the SMIL file does not list. Therefore, those uploaded files will be still put in the MMS message and sent out and you will be charged accordingly.

Request HTTP Responses

Bulletin Connect will respond to each and every HTTP request with one of the following result codes.

Code	Meaning	Action Required
204	Success!	No action required
400	Bad Request	examine the HTTP header value for Status-Line for further error information indicates invalid, empty (0 byte) or unsupported media or SMIL files or a subject that is too long (>=40 char)
401	Unauthorized	Check you are using the correct URL as well as userId and password values
403	Forbidden	Check available funds, Check that you are not using a rateCode or a sender number in the request. These are only available for the SMS API.
413	Uploaded files exceed the max limit. (200 KB)
500	Internal Error	Contact Bulletin Wireless

The userId and password are supplied to you by Bulletin Wireless when you sign up for a Bulletin Connect account. You may pass them to the server as form encoded parameters, or in the HTTP Authorization header in Basic format.

The optional subject is a free form string used as the subject filed in the MMS message. Any
printable ASCII character can be used in the string, and it can be upto 40 characters long.

The to parameter is the destination Number/MSISDN (Mobile Station ISDN number), i.e. the phone number to send the MMS to, including the country code. Do not include leading zeros, spaces, brackets or other formatting characters. To send a message to multiple recipients list the numbers, separated by spaces, in the to parameter (then URLencode).
Do not POST multiple to parameters.

The body parameter is used to pass the SMIL file that contains the structure and MMS formatting as well as the text component of the MMS message. Messages can be up to 3000 bytes. The allowable character set may vary depending on the destination network. In general characters from the GSM default character set are safe (see GSM 03.38). For UTF-16, messages can be up to 70 Unicode characters long which must be UTF-8 encoded (before URL Encoding). That is, for UTF-16 messages the body parameter must be UrlEncoded (UTF8Encode(Unicode message)) this will be sent through as UTF-16 to the handset.

The optional messageId is a free form string used to correlate messages with replies and read receipts. Any printable ASCII character can be used in the string, and it can be up to 36 characters long. The messageId will be returned to your application with receipts and replies.

MMS Message Costs

MMS messages are billed by message size taking into account the combined size of the media items and SMIL file content.
For example, if your message is made up of 2 image files (27560 bytes and 22154 bytes) and some captions in the SMIL file (750 bytes) the total message size is 50464 bytes. You should store the returned byte size value (statusCode;numOfBytesSent) from your status requests to reconcile with your account.

Sample Code

Here we provide two approaches to use the Bulletin Connect API. They are designed to demonstrate the idea only. Please note that the java approach is preferred than the web form one. The main reason is that web form posting is browser dependent, especially for the mime type parameter of the uploaded files.

3.1 JAVA Code to send out MMS messages and get the Bulletin Connect HTTP response.

package com.bulletinwireless.eg;
import java.io.IOException;
import java.io.File;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.StringPart;
/**
Sample code to send out an mms message and display the server returns. It uses apache
httpclient library to generate MultipartRequest.
*/
public class MmsPost {
	public static void main(String[] args) throws IOException {
		int result = send("test", "test", "614921012345 6149012346 614921012347","testing");
		System.out.println("Result code: " + result);
	}
	/**
	* Send an MMS message.
	*
	* @param user Bulletin Connect user name
	* @param pass Bulletin Connect password
	* @param to the number to send the message to. It could be space separated multiple phone numbers.
	* @param subject the subject of the mms message
	* @return the HTTP result code
	* @throws IOException if the HTTP POST fails
	*/
	public static int send(String user, String pass, String to, String subject) throws IOException {
		String url = "http://service.bulletinconnect.net/api/1/mms/out";
		PostMethod post = new PostMethod(url);
		//Load resources and create Part objects.
		File smilFile = new File("main.smil");
		File theImageFile = new File("image.jpg");
		File theAudioFile = new File("audio.amr");
		File theTextFile = new File("text.txt");
		//FileParts
		Part smil = new FilePart(smilFile.getName(), smilFile,"application/smil","UTF-8");
		Part image = new FilePart(theImageFile.getName(), theImageFile, "image/jpeg","");
		Part audio = new FilePart(theAudioFile.getName(), theAudioFile,"audio/amr","");
		Part text = new FilePart(theTextFile.getName(), theTextFile,"plain/text","UTF-8");
		//StringParts
		Part id = new StringPart("userId", user);
		Part password = new StringPart("password", pass);
		Part dest = new StringPart("to",to);
		Part sub = new StringPart("subject",subject);
		Part[] parts = {
		//Smil has to be the first FilePart to submit!!!!!
			id, password, dest,sub, smil, image, audio, text
		};
		post.setRequestEntity(
		//The post has to be a Multipart post!!
			new MultipartRequestEntity(parts, post.getParams())
		);
		HttpClient client = new HttpClient();
		client.getHttpConnectionManager().
		getParams().setConnectionTimeout(5000);
		// Execute request
		try {
		int result = client.executeMethod(post);
		// Display status code
		System.out.println("Response status code: " + result);
		// Display response
		System.out.println("Response body: ");
		System.out.println(post.getResponseBodyAsString());
		return result;
		} finally {
		// Release current connection to the connection pool once you are done
		post.releaseConnection();
		}
	}
}

Sample results from running the code provided above

Response status code: 204
Response body:
null
Result code: 204
// typical sent success response.

Sample HTML form to send MMS messages

<HTML>
	<HEAD><TITLE>Send mms</TITLE></HEAD>
	<BODY>
	<H3>MMS message sending example</H3>
		<FORM METHOD="POST" action="http://service.bulletinconnect.net/api/1/mms/out"
		ENCTYPE="multipart/formdata"
		>
			<INPUT type="hidden" name="userId" value="test">
			<INPUT type="hidden" name="password" value="test">
			<P> To <BR> <INPUT TYPE="TEXT" NAME="to" SIZE="20"> <BR>
			<P> Subject <BR> <INPUT TYPE="TEXT" NAME="subject" SIZE="20"> <BR>
			<P> Message Id <BR> <INPUT TYPE="TEXT" NAME="messageId" SIZE="20"> <BR>
			<P> File list <BR>
			<div>
			The first file has to be the smil file!
			<INPUT TYPE="FILE" name="1" accept="application/smil">
			</div>
			<div>
			<INPUT TYPE="FILE" name="2"> <BR>
			</div>
			<div>
			<INPUT TYPE="FILE" name="3"> <BR>
			</div>
			<div>
			<INPUT TYPE="FILE" name="4"> <BR>
			</div><P>
			<INPUT TYPE="SUBMIT" VALUE="Submit">
			<INPUT TYPE="RESET" VALUE="Reset">
		</FORM>
	</BODY>
</HTML>

What this code looks like.