Child pages
  • HTTP IM User Guide
Skip to end of metadata
Go to start of metadata

 Document History

VersionDateReason
1.020.05.2014Initial version
1.130.05.2014Incorporated encryption and authentication section.
1.206.06.2014Added demonstration code
1.318.06.2014Added section on sending and receiving media files
1.402.09.2014Updated demonstration code




Abstract

This page explains the IM API defined in the API Server. Developers can use the API to send and receive IM messages to client applications running on M800. 
We allow developers to develop their own applications on their own servers which use our HTTP API to send server-to-client IM messages and receive client-to-server IM messages.
Also developers can use the API to send server-to-client push notifications.
To set up a test environment, you can use a browser plug in, such as the RESTclient on Firefox. 
It should be in Firefox extensions tab, otherwise download it here: https://addons.mozilla.org/en-US/firefox/addon/restclient/
Once you have installed a  REST client, you can send messages with server side application to mobiles running M800 SDK-enabled apps
Note that at present you cannot send SMS, make voice calls or message other apps with this API, however, our API does support PUSH

Send Text Messages

This method allows the developer to send an IM text message to a target user on the behalf of another.

Resource URL and Method

URI/api/1.0/im/messages/username@carrierIdentifier
MethodPOST

URL Parameters

NameTypeRequiredDescription
usernameStringYesUsername that receives the text message
carrierIdentifierStringYesCarrier identifier of this user

Data Structure

Body Content Type: application/json

com.maaii.developer.v100.messages.IMSendMessage Data Structure

Example

Response

HTTP status code. Will return status code 200 when the message is sent successfully.

Receive Text Messages

When a sender sends a message through IM, if the recipient's carrier

  • contains the "capabilities" list which contains "offline_message_callback" setting, and
  • "com.maaii.im.Message" extension point is set

the IM message will try to be posted to the extension point from the API server (i.e. there is no guarantee).

Offline messages are forwarded, in other words, if the user is found online, the callback will never be invoked.

 

Success Response Resource URL and Method

URI<Extension Endpoint Defined by the developer in carrier object>
MethodPOST

Response Structure

Body Content Type: application/json

com.maaii.developer.v100.messages.IMMessagesReceived Data Structure

Example




Send Media Messages

This method allows to send an IM media (file) message to a target user on the behalf of another. The media message will contain a link where the file is uploaded with the file details (e.g. content type, file size.) and the preview file details (data in base64 string and its content type). Preview file only available for image and video messages.

Only one file is included per message.

Only these MIME types are allowed to send in the message:

  • audio (audio/mp4a-latm)
  • image (image/jpeg)
  • video (video/mp4)

Resource URL and Method

The URL is the same as the one stated in the send text message.

URI/api/1.0/im/messages/username@carrierIdentifier
MethodPOST

 

URL Parameters

NameTypeRequiredDescription
UsernameStringYesUsername that receives the text message
carrierIdentifierStringYesCarrier identifier of this user

 

Data Structure

Body Content Type: application/json

com.maaii.developer.v100.messages.IMSendMessage Data Structure

Example

Response

HTTP status code. Will return status code 200 when the message is sent successfully.

 

Receive Media Messages

 

Recipient can define an endpoint too for receiving media message. The configuration is the same with the one defined in the receive text messages.

 

Success Response Resource URL and Method

 

URI<Extension Endpoint Defined by the developer in carrier object>
MethodPOST

 

Response Structure

 

Body Content Type: application/json

com.maaii.developer.v100.messages.IMMessagesReceived Data Structure

 

Example

Encryption

All interactions between the developers are encrypted using HTTPS. Maaii API server only accepts encrypted traffic, it is the responsibility of the developer to set up an HTTPS service on his side to secure the callback reception.

Authentication

All requests sent by the developer must be signed. The purpose of the signature is to ensure the identity of the developer and the authenticity of the requests. Similarly, callback requests sent to the developer server by the Maaii API server are also signed to allow the developer to verify their authenticity. 

Signature process

In order to authenticate and assert the validity of a request, all requests made by a developer have to be authenticated. The authentication uses a custom HTTP authorization scheme, based on request signing:

Where {developerKey} is the developer key, {nonce} is number used to make the request unique and prevent replay attacks and {signature} is the request's signature. This is computed based on the actual request payload and is signed using the developer secret with the following signing mechanism:

If the request does not contain a payload (no Content-Type / Content-Md5), its value should be an empty string. This means the line feed is still required in the signature computation.

The Date element of the signature is taken from the "X-M-Date".

The date mentioned in the request will be used to verify the request is not replayed, the server determines an acceptable time range for a request to be processed, if the date is not within this range, it will be rejected.

Example 

We try to post to the following example URI:

Endpoint called

With this JSON payload

Example payload, Content-Md5 = 2aa2f9b90fea8843a78e434dff26f6b6

Assuming the developer key is "a-demo-key" and the developer secret is "a-demo-secret", a signature would be generated: ( please note that this signature is provided only for demonstration purposes, you should recompute it to get the correct value) 

The HTTP request should then contain the Authorization with the computed signature as follows:

Complete POST request

The presence / absence of "Content-Md5", "Content-Type" and "Content-Length" do not affect the authorization process, it relies solely on the actual request, payload and the authorization header.

Testing Tools

All examples given in the previous section can be verified and reproduced manually with the help of online tools.

When using an online tool, be careful to not include extra white space or line returns as this will affect the final outcome.

Content-MD5

The following online tools can be used to generate MD5:

http://www.md5hashgenerator.com/index.php

http://www.miraclesalad.com/webtools/md5.php

Example 

SHA-256 HMAC

The following online tool can be used to generate SHA-256 HMAC signatures:

http://jetcityorange.com/hmac/

Example 

Demo Code

The following is an example of code to sign requests as described above 

 

RequestSigningInterceptor.java

 

Finally, if you have any questions/issues, please visit our developers forum at forum.m800.com or contact manlaw@maaii.com

M800 Confidential. All rights reserved. 2014 © 

 


  • No labels