Processing MMS Receipts

To Receive a MMS Receipt

While it is not possible to know when a recipient has read your messages, it is often possible to get information about whether the message has been delivered to the phone or is waiting on the carrier network.

Bulletin can provide message status information if required. Contact Bulletin if you require status information.

Clients can GET incoming receipts (status updates) from

MMS	http://service.bulletinconnect.net/api/1/mms/status

Required Input parameters are:

Name (case sensitive)	Description	Required?
userId	User name for authentication	YES
password	Password for authentication	YES

The userId and password are supplied to you by Bulletin Wireless when you sign up for a Bulletin Connect account.

Bulletin Connect will respond to HTTP requests with one of the following result codes.

Code	Description	Notes
200	OK (normal result)	Parse the results for the incoming status details as described below then re poll to get another status
204	No content (no messages)	No status messages waiting. Pause processing and retry after 30 seconds
401	Unauthorized	Check userId and password
405	Incorrect Connection Method Used	Use the HTTP GET Method rather than POST
500	Internal Error	Contact Bulletin Wireless

For 200 codes (success) Bulletin Connect will include a form encoded parameter list containing status information for a single message as described here

List Item	Description	Notes
messageId	A unique identifier for the receipt	Bulletin Connect Unique ID. Check this ID to ensure you have not already processed this status update (50 character (max) string).
to	A MSISDN or Short Code from Bulletin's range used to send the Message
from	Destination MSISDN (phone number) of message	The recipients number of an outbound message sent by you (international format).
statusCode	Message status	See Message Status Codes for simple descriptions of Codes used
inReplyToId	Correlation ID of the message	Matches the messageId sent by you in an outbound message. If no messageId was set then this will contain default.
error	Descriptive text	More (readable) information about the Message Status For SNT messages the byte size of the submitted message is stored in this field*

* Reporting of byte size may change in future. If you have any questions please contact us.

N.B. The order of the parameters may change so use value/pair matching rather than location mapping.

Message Status Codes

Possible values of statusCode are:

Code	Basic Description	What this means to your Application	Final Status?
NUR	Number Unreachable	Check the number is correct and in International Format and then resend. The error string will also provide some more useful information such as whether the recipient is blocked. Be careful about infinite loops, only retry a couple of times.	Yes
SNT	Message Passed to Network	Wait. Give it a few minutes and then poll for more Status Messages.	No
ERR	Internal Error	An error occurred. It may be recoverable so try sending the message again in a few minutes. Be careful about infinite loops in your code.	Yes
NRCV or NRC	Not Received	Check the number is correct and in International Format and then resend. Be careful about infinite loops though.	Yes
RCV	Message Received	Excellent. This is a final status for this message and the handset has received it.	Yes
EXP	Message was not delivered within allowed time	This is a final status for this message and the handset has not received it. Retry if you want but for a lot of carriers this status may take days to return so the message may no longer be relevant.	Yes
INF	Insufficient funds	A billing error has occurred. If you get this error then your Bulletin Online account has reached its credit limit. This is very rare and you need to contact Bulletin Wireless immediately. No more messages can be sent until this is rectified.	Yes

Handy Hint

To ensure you know the current status or your message, ensure that you set a unique messageId in your outbound message and correlate it with the receipts (inReplyToId field) as you process them.

Sample Java Code to retrieve status updates

package com.bulletinwireless.eg;
/**
* Example to show how to retrieve status back from Bulletin Connect.
*Again, this example requires the apache commons httpclient library to compile.
*/
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.*;
import org.apache.commons.httpclient.params.HttpMethodParams;
import java.io.*;
public class MmsRetrieveStatus {
	private static String url = "http://service.bulletinconnect.net/api/1/mms/status";
	public static void main(String[] args) {
		HttpClient client = new HttpClient();
		AuthScope ourScope = new AuthScope(AuthScope.ANY_HOST,AuthScope.ANY_PORT, AuthScope.ANY_REALM);
		UsernamePasswordCredentials credentials = new
		UsernamePasswordCredentials("userId","password");
		client.getState().setCredentials(ourScope, credentials);
		GetMethod method = new GetMethod(url);
		// Provide custom retry handler is necessary
		method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER,
			new DefaultHttpMethodRetryHandler(3, false));
		try {
			int statusCode = client.executeMethod(method);
			if (statusCode == HttpStatus.SC_NO_CONTENT) {
				System.out.println("No more status!");
				return;
			}else if(statusCode != HttpStatus.SC_OK){
				System.err.println("Method failed: " + method.getStatusLine());
			}
			// Read the response body.
			byte[] responseBody = method.getResponseBody();
			if(responseBody == null){
			System.out.println("");
			}
			String response = new String(responseBody);
			/* A typic response looks like:
			from=6149822801&inReplyToId=default&messageId=00000000000001f4&statusCode=ERR&to=4411441141&userId=test
			*/
		if(response!=null && response.length()!=0){
			String[] parsedStatus = response.split("&");
			for (String detail : parsedStatus) {
				System.out.println(detail);
			}
			}
		} catch (HttpException e) {
			System.err.println("Fatal protocol violation: " + e.getMessage());
			e.printStackTrace();
		} catch (IOException e) {
			System.err.println("Fatal transport error: " + e.getMessage());
			e.printStackTrace();
		} finally {
			method.releaseConnection();
		}
	}
}