Messenger can call URLs you provide when certain events occur. These events are:

  • An inbound 'reply' message is received for your organisation.
  • The status of an outbound message has changed (e.g. it has been received).

Note that default values can be defined for your organisation from within Messenger, on the API Settings page, and only need to be defined when using the API if they need to vary from the defaults.

Each time an appropriate event occurs, Messenger will call your provided URL.

If your service returns an http result code in the 400+ range we will retry for up to 48 hours. To avoid duplicate messages being posted to your service we recommend you issue an http 200 status code. If the reply has NOT been successfully acknowledged within 48 hours it will be removed from the retry queue and can viewed on-line only.

The currently supported delivery protocols are http POST, https POST, and, for callbackUrl only, mailto.

Callback URLs can include variables that Messenger will populate dynamically at runtime. These are as follows:

Variable Purpose Reply or Status?

{!messageId}

Indicates the message that this reply is associated with.
Either the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used.
Not valid with Virtual Numbers or Short Codes.

Both

{!body}

The body of the message that has been received.

Reply

{!recipient.msisdn}

The msisdn that has triggered this callback

Both

{!recipient.displayname}

The name of the entity that triggered this callback, when available

Both

{!status}

The status of the message that was sent to {!recipient.msisdn}

Status

Some http examples:

http://example.com/sms-reply?msg={!messageid}&from={!recipient.msisdn}&body={!body}
http://example.com/sms-state?msg={!messageid}&from={!recipient.msisdn}&status={!status}

The mailto: protocol supports standard parameters 'Subject' and 'Body':

Parameter Name Purpose Required

Subject

Controls the Subject used in the email notification

NO. If undefined will default to "RE:"

Body

Controls the Body of the email sent in the email notification

NO. If undefined will default to the body of the message sent by the recipient

Some mailto: examples:

mailto://someone@example.com?Subject=Message+from+{!recipient.msisdn}&Body={!recipient.displayname}+says:+{!body}
mailto://someone@example.com

The http and https response sent to your callbackUrl, called when a message arrives for your Organisation, is available in two different formats. One is based on XML, and the other is an FORM POST format.

The format used in the callback is defined by your Organisation on the Messenger, and are labelled "XMLv3" and "FORMv1".

Handling a Reply callback

When we call your server the data we provide to you depends on the format selected. These properties are:

XMLv3 Property FORMv1 Property Purpose

messageId

InReplyToId

This is the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Blank if this is not a reply. Not valid with Virtual Numbers or Short Codes

receivedDate

n/a

The date the reply message was received, formatted as ISO-8601 in the UTC Timezone

displayName

n/a

The human-readable version of the msisdn, if available

msisdn

from

The phone number that sent the message.

n/a

to

The phone number that Messenger received the message on

body

body

The content of the SMS message received from the MSISDN (formatted as CDATA for XML)

The "XMLv3" reply document is formatted as in the following example:

<?xml version="1.0" ?>
<inbound-message messageId="FebPromo" receivedDate="2012-03-20T01:36:00Z">
   <recipient displayName="Big Bob" msisdn="6421333333">
      <body><![CDATA[Thanks for that]]></body>
   </recipient>
</inbound-message>

The "FORMv1" reply document is simply an http post containing the following form properties, as described above:

  • messageId
  • to
  • from
  • inReplyToId
  • body

Handling a Status callback

The data available in the status callback depends on the format selected. These properties are:

XMLv3 Property FORMv1 Property Purpose

messageId

InReplyToId

This is the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Blank if this is not a reply. Not valid with Virtual Numbers or Short Codes.

to

to

A MSISDN or Short Code from Bulletin's threading range

from

from

The number of the handset that the status change is associated with. e.g. Who received the message.

statusCode

statusCode

See Message Status Codes for simple descriptions of Codes used.

statusDate

n/a

The date the status message was received, formatted as ISO-8601 in the UTC Timezone

statusId

messageId

A unique identifier for this status message. Check this ID to ensure you have not already processed this status update.

error

error

More readable information about the Message Status, when available.

The "XMLv3" status document is formatted as in the following example:

<?xml version=\"1.0\" ?>
<status-update>
    <messageId>summerpromo76</messageId>
    <to>4040</to>
    <from>021333333</from>
    <statusCode>RCV</statusCode>
    <statusDate>2012-03-20T01:36:00Z</statusDate>
    <statusId>9182</statusId>
    <error></error>
</status-update>

The "FORMv1" reply document is simply an http post containing the following form properties, as described above:

  • messageId (please note that this is, unfortunately, the same as the XMLv3 property "statusId", not the XMLv3 property "messageId")
  • to
  • from
  • statusCode
  • inReplyToId
  • error

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