New Messages

Calling user newMsgs method is GET action & must be Authenticated.

URL Example http://example.com/api/v1/newMsgs

NAME DESCRIPTION Type
newMsgs Number of New unread Messages Integer

Messages Inbox

Calling user Inbox method is GET action & must be Authenticated.

URL Example http://example.com/api/v1/inbox

To use pagination you will need to define MessagesPerPage & limit GET parameters

URL Example http://example.com/api/v1/inbox?limit=0&MessagesPerPage=5

limit parameter should be used for current page in pagination and is start with 0 and is mostly should be incremented by allowed/configured MessagesPerPage. if MessagesPerPage is 5, then limit should be start with 0 then next page is current limit+MessagesPerPage

Response

Response is 2 Dimensional Array, first array for Messages info & second one for messages info

Info

NAME DESCRIPTION TYPE Default
limit Current Messages Limit Integer FALSE
numberOfMessages Number of total counted messages Integer Integer
MessagesPerPage Displayed Messages per page Integer 5

Messages

NAME DESCRIPTION TYPE
msg_id Message ID Integer
subject Message Subject String
message Message Body Text
attachment If attachment value is true mean message is containing attachment Boolean
isRead If isRead value is false mean this a new message Boolean
numOfreplies Number of replies this message contain Integer
created_date Messages Created Date Date
fromUserID The UserID who created this message Integer
fromName The full name of who created this message String
fromUserRole The User Group who created this message String
fromUserAvatar The User avatar of who created this message String
toUserID The UserID of message receipting Integer
toName The full name of message receipting String
toUserRole The User group of message receipting String
toUserAvatar The User avatar of message receipting String

Messages is sorted by un-read/new messages are always on top by created_date and messages which been read is sorted descending by created_date

Messages Outbox

Calling user Outbox method is GET action & must be Authenticated. Outbox is holding exactly the same function behavior as in Inbox.

URL Example http://example.com/api/v1/outbox http://example.com/api/v1/outbox?limit=0&MessagesPerPage=5

Reading Message

Calling readMsg method is GET action & must be Authenticated.

URL Example http://example.com/api/v1/readMsg?id=MsgID

The response return in multi array each first dimensional array is message and replies information, the main created message always on top and rest of replies messages are sorted by created_date ascending and is exactly have the same output property as Inbox.

The files array is only appear if attachment value is true and is may contain multi arrays for each files related to this message or reply. the only necessary parameter is attachment id which need to be passed Download Attachment API.

Files Array

NAME DESCRIPTION TYPE
id Attachment ID Integer
file_name Attachment file name String
file_type File content type String
file_size File size is in bytes Integer

Download Attachment

Calling attachment method is GET action & must be Authenticated.

URL Example http://example.com/api/v1/attachment?id=AttachmentID

In first example you will need to pass the return into iframe if you need alternative better way you can use the other method as direct Link.

Alternative Method http://example.com/api/v1/download_attachment?id=AttachmentID&accessCode=YourAccessCode

This method does not required you to be authenticated but you will need to add your accessCode in GET Parameter to verify your credentials.

Delete Message

Calling deleteMsg method is GET action & must be Authenticated.

Single Message Delete Example http://example.com/api/v1/deleteMsg?id=MsgID

Mass Messages Delete

You can separate multi messages id by comma in order to delete multiply message in same action

URL Example http://example.com/api/v1/deleteMsg?id=MsgID1,MsgID2,MsgID3,MsgID4

Compose New Message

Calling compose_message method is POST action & must be Authenticated. Because Composing new message may contain single or multi attachments so the form enctype should be multipart/form-data.

URL Form Action Example http://example.com/api/v1/compose_message

In this method we should use the following input parameters in the post form.

Input Name Input Type Description Value Type
toUserID text advised to use User Search to get Users ID Integer
subject text Message Subject String
message textarea Message Body Text
attachment[] file Multi attachment support Base64
reply_id text Set it to Message ID for replying message only Integer

jQuery Example

var form = new FormData();
form.append("toUserID", "250");
form.append("subject", "Another TEst");
form.append("message", "Message");
form.append("attachment[]", "mamaafrica.jpg");
 
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://example.com/api/v1/compose_message",
  "method": "POST",
  "headers": {
    "access-code": "YOUR_ACCESS_CODE"
  },
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form
}
 
$.ajax(settings).done(function (response) {
  console.log(response);
});

Calling users_search method is GET action & must be Authenticated.

Example http://example.com/api/v1/users_search

If you using autocomplete ajax function you can always use User input to “q” parameter to get more accurate users. The search query parameter will always looking after User full_name

Example http://example.com/api/v1/users_search?q=Keyword

Default Response

NAME DESCRIPTION TYPE
id User ID Integer
full_name User full name String
description User group String

If You use another implementation like select2 jquery plugin you may need to use parameter showInText to true

Example: http://example.com/api/v1/users_search?showInText=1

showInText Response

NAME DESCRIPTION TYPE
id User ID Integer
text is show User full name & User Group in same field as following: Full Name (Group) String

jQuery Example

Include select2.js

<script type="text/javascript">
    $(document).ready(function() {
        $('#Sendto').select2({
            placeholder: "Search for User",
            allowClear: true,
            minimumInputLength: 0,
            multiple: false,
            ajax: {
                params: {headers: {"ACCESS-CODE": "UserAccessCode"}},
                url: "http://example.com/api/v1/users_search?showInText=1", //showIntext make it easy
                dataType: 'json',
                data: function(term, page) {
                    return {
                        q: term
                    };
                },
                results: function(data, page) {
                    return {
                        results: data
                    };
                }
            }
        });
    });
</script>
<input type="text" name="to_userid" id="Sendto" />