Documentation

Receiving messages

Receiving Notifications and Messages from users

The Mogreet Messaging API is a two-way system: you can send messages to users, and your users can send messages to you.   You can also set up a callback URL to catch incoming messages sent in by consumers to your application.  You can even receive in images sent via MMS from mobile phones.

This is accomplished with a 'callback url' or 'web hook', which is a URL you provide us in the Developer Dashboard.

When a user texts in (either SMS or MMS) to your keyword on your assigned shortcode, that callback URL will be sent an HTTP POST request (XML or JSON) with the data from the user message.

These user messages (called MO in text-speak) can also contain image content. For instance, if a developer wanted to run an 'ugly dog' contest, he could promote a call to action requesting users to take a picture of their pooch and send it in to a shortcode and keyword via MMS. The Mogreet platform will receive the message, including any data, extract the picture, host it temporarily for your access, and post a request to the URL specified containing the user phone number, what message text was sent in and a URL to access the image data. 

See the following response XML examples:

Request Response
The user sent in an image via MMS
<?xml version="1.0"?>
<mogreet>
  <event>message-in</event>  
  <campaign_id>xxxxx</campaign_id>  
  <msisdn>15555555555</msisdn>  
  <carrier><![CDATA[Verizon Wireless]]></carrier> 
  <message><![CDATA[user's message blah blah blah]]></message>  
  <subject><![CDATA[]]></subject> 
  <images>        
    <image><![CDATA[http://d2c.bandcon.mogreet.com/mo-mms/images/some_image.jpeg]]></image>  
  </images>
</mogreet>
The user texts 'STOP'
<?xml version="1.0"?>
<mogreet>
  <event>stop</event>  
  <campaign_id>xxxxx</campaign_id>  
  <msisdn>15555555555</msisdn>   
  <message><![CDATA[Stop YOUR_KEYWORD]]></message>   
</mogreet>
The user replies 'Y' to opt-in
<?xml version="1.0"?>
<mogreet>
  <event>reply-y</event>  
  <campaign_id>xxxxx</campaign_id>  
  <msisdn>15555555555</msisdn>   
  <message><![CDATA[Y]]></message>   
</mogreet>

See the API Reference documentation section 'Processing MO messages' for complete details.

You can also use the callback system to get more information about the result of your sends, including error reports. To get feedback on a send, just include the callback parameter in the transaction.send API call. 

Here are examples of a successful and unsuccessful send:

Request Response
a successful transaction.send
<?xml version="1.0"?>
<response code="1" status="success">
<message><![CDATA[Content MMS Sent]]></message>
</response>
a failed transaction.send
<?xml version="1.0"?>
<response code="603" status="error">
<message><![CDATA[We could not determine the mobile phone carrier you are attempting to send to. Please make sure you entered the receiver's phone number correctly and try again. Thank you.]]></message>
</response>
  • If you want your users to receive an automatic response everytime they send a message, have a look at the automated-campaign section.
  • You can download a pdf version of the full API reference here: Mogreet Messaging System API 4.01.pdf