Documentation

Sending messages

Calling the MoMS API

After completing the required setup process and optionally providing IP Addresses to white list, you are ready to test your connection to our API servers.  Requests should be sent as an HTTPS GET or POST request to:

https://api.mogreet.com/moms/object.method

With the required parameters for each object.method. 

Testing with curl and system.ping

An easy way to test API calls is with the 'curl' command in *nix. You can also paste API calls into a browser URL line to see the result. Here we will demonstrate using curl on a command line. 

Open a terminal/shell/command line and use curl with the -k flag to skip certificate checking.  Also remember to enclose the PI call in quote marks.  Use your own client_id and token.

curl -k "https://api.mogreet.com/moms/system.ping?client_id=your_id&token=your_token"

You should receive a response back as follows: 

<?xml version="1.0"?>
<response code="1" status="success">
  <message><![CDATA[pong]]></message>
</response>

Try a Few API calls

system.ping

Use the ping method to test connectivity and monitor the status of the MoMS API servers. Ping is useful to test your credentials and white-listed IPs.

Request:

https://api.mogreet.com/moms/system.ping

with the following parameters:

Name	Description
client_id	Your client id. Log onto the Campaign Manager to access your client id.
token	Your token. Log onto the Campaign Manager to access your token.

A successful call will return an HTTP 200 with XML response. See the following request and response examples:

Request	Response
https://api.mogreet.com/moms/system.ping?client_id=12345&token=abcde	<?xml version=”1.0” encoding=”UTF-8”?> <response status=”success” code=”1”> <message><![CDATA[pong]]></message> </response>
Same, with the format=json flag: https://api.mogreet.com/moms/system.ping?client_id=12345&token=abcde&format=json	{ "response": { "code": "1", "status": "success", "message": "pong" } }

transaction.send

Use the send method to initiate an SMS or MMS transaction. The delivery of the transaction depends on your campaign setup (called the campaign flow). Clients can customize their campaign flow through the Campaign Manager or with the help of their account manager. A successful request returns a message id and hash associated with the transaction created from the request. It’s important to record and track the response message id and hash if you want to check the status and history of the transaction using the transaction.lookup method later on.

Request:

https://api.mogreet.com/moms/transaction.send

with the following parameters:

Name	Description
client_id	Your client id. Log onto the Campaign Manager to access your client id.
token	Your token. Log onto the Campaign Manager to access your token.
campaign_id	An ID connected to a specific campaign setup in the Campaign Manager or provided by your account representative.
to	The mobile number (MSISDN) of the handset you would like to send to.
message	Depending on your campaign set up, the message presented to the “to” user.
content_id	An integer value associated to a piece of content ingested through the Campaign Manager. You’ll find all your content ids under the media section. (Optional, used for SMS and MMS delivering audio, image or video)
content_url	A publicly accessible URL of an image, audio or video. MOMS will automagically ingest the content and deliver it as specified by the campaign flow. (Optional, used for SMS and MMS delivering audio, image or video)
callback	If provided with a valid URL, any errors with the transaction will be sent to this URL via XML over HTTP. See description below.

A successful call will return an HTTP 200 with XML response. See the following request and response examples:

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>

Note: you can also set up a callback URL to catch MO messages sent in by consumers to your campaign. See the section 'Processing MO messages'.
user defined parameters Clients may also add user defined parameters (udp) to further customize their campaigns. Since campaigns differ from client to client and even from one client’s campaign to another, the API allows you to customize the experience by submitting your own user defined parameters (udp). The parameters enable you to customize your message flow with our product team. The udp data is most commonly used to insert some custom text into the messaging dynamically: i.e. – product description or some other dynamic data.

A successful call will return an HTTP 200 with XML response. See the following request and response examples:

Request	Response
https://api.mogreet.com/moms/transaction.send?client_id=12345&token=abcde&campaign_id=123&to=5551236789 &from=5551236543&message=hello%20world&content_id=321	<?xml version=”1.0” encoding=”UTF-8”?> <response status=”success” code=”1”> <message><![CDATA[Mogreet successfully sent!]]></message> <message_id>123456789</message_id> <hash>a12b3c4d</hash> </response>
a bad MSISDN (mobile number) https://api.mogreet.com/moms/transaction.send?client_id=12345&token=abcde&campaign_id=123&to=1236789 &from=5551236543&message=hello%20world&content_id=456	<?xml version=”1.0” encoding=”UTF-8”?> <response status=”error” code=”603”> <message><![CDATA[Invalid to destination]]></message> </response>
with response set to json:	{ "response": { "code": "1", "status": "success", "message": "Your message is on its way.", "message_id": "118277728", "hash": "9g5efkxo" } }

Reply Y, Help and Stop

SMS and MMS messaging is allowed by opt-in only. That means that your users need to consent to receive content from you and your campaign. This consent is managed by the Mogreet service platform.  When you send to a mobile device, we check to see whether that user has consented to receive content from your account on the shortcode you will be delivering messages on. If we don't have a record of that user, we will first send an SMS requesting permission to deliver the content. If the user consents, they reply with a 'y' in the body of the message. When we receive the reply Y, we continue on with the delivery of your content. 
The API platform automatically appends the required language 'reply STOP (your keyword) to cancel' to each message.
If a user decides to no longer receive content, they can text in the word 'stop' (or 'end', 'quit', 'cancel', 'unsubscribe', 'arete', or 'alto') followed by your keyword and they will be unsubscribed from your message list. If a user issues a stop command without any keyword, we will opt them out of all messaging from that shortcode. One additional message confirming the change in status will be sent.

Standard messaging rates may apply

The copy 'message and data rates may apply' will automatically be appended to each message. This langauge is required by the carriers, and indicates that the end user is responsible for paying the carriers any charges or fees incurred by receiving SMS or MMS messages, or data.  The majority of consumers in the U.S. have messaging plans and do not incur any per-message costs.

url encode your message
Remember to url-encode your message, any other text such as names, and the content url and udp parameters if used, before sending the API call. Since the API calls are made over HTTP, all the content must be safe to pass in a URL line, therefore, url-encoded.  Here are two samples.

Not URL-encoded: This isn't my day, I need A&M root-beer/cola

URL-encoded: This%20isn't%20my%20day%2C%20I%20need%20A%26M%20root-beer%2Fcola%20

Sending Multimedia Content via MMS

You can send Images, Audio and even short videos via MMS using the Mogreet API platform. There are generally speaking two ways to ingest content and send it using the APIs.

1. on-demand ingestion with the content_url
2. ingestion via the media APIs

When you use the content_url parameter in the transaction.send API call, you provide a URL locating a piece of content on the web. Our platform ingests that media, transcodes it, and delivers the message. The media is cached for efficiency and reuse for 30 days, then it is deletes. There is NO ADDITIONAL COST for using the content_url and on-demand ingestion to deliver multimedia MMS. 

If you want to programatically ingest content into your media library, and use it in sends, the media APIs allow you to post (or use an URL) content into the Mogreet API service. That content is transcoded and hosted, and a content id and unique content hash are provided back in the response of the API call. This content is permanent, and you may use the content id in APi calls, and the unique hash in Smart URLs to deliver that content in app, on web sites, etc. Refer to the API reference documentation for complete details.