===== New Messages =====

Calling user newMsgs method is GET action & must be [[:api:main#authentication|Authenticated]].

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>newMsgs</fc>''

^ NAME     ^ DESCRIPTION                    ^ Type     ^
| newMsgs  | Number of New unread Messages  | Integer  |

===== Messages Inbox =====

Calling user Inbox method is GET action & must be [[:api:main#authentication|Authenticated]].

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>inbox</fc>''


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

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>inbox?limit=0&MessagesPerPage=5</fc>''

<WRAP center round tip>
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
</WRAP>


=== 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   |


<WRAP center round info>
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
</WRAP>

===== Messages Outbox =====

Calling user Outbox method is GET action & must be [[:api:main#authentication|Authenticated]].
Outbox is holding exactly the same function behavior as in [[api:messaging#messages_inbox|Inbox]].

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>outbox</fc>''
''%%http://example.com/api/v1/%%<fc #ff0000>outbox?limit=0&MessagesPerPage=5</fc>''

===== Reading Message =====

Calling readMsg method is GET action & must be [[:api:main#authentication|Authenticated]].

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>readMsg?id=MsgID</fc>''

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 [[api:messaging#messages_inbox|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 [[api:messaging#download_attachment|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 [[:api:main#authentication|Authenticated]].

**URL Example**
''%%http://example.com/api/v1/%%<fc #ff0000>attachment?id=AttachmentID</fc>''

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/%%<fc #ff0000>download_attachment?id=AttachmentID&accessCode=YourAccessCode</fc>''

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 [[:api:main#authentication|Authenticated]].

**Single Message Delete Example**
''%%http://example.com/api/v1/%%<fc #ff0000>deleteMsg?id=MsgID</fc>''

===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/%%<fc #ff0000>deleteMsg?id=MsgID1,MsgID2,MsgID3,MsgID4</fc>''
===== Compose New Message =====

Calling compose_message method is POST action & must be [[:api:main#authentication|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/%%<fc #ff0000>compose_message</fc>''

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 [[api:messaging&#users_search|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====

<code javascript>
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);
});
</code>
===== Users Search =====

Calling users_search method is GET action & must be [[:api:main#authentication|Authenticated]].

**Example**
''%%http://example.com/api/v1/%%<fc #ff0000>users_search</fc>''

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/%%<fc #ff0000>users_search?q=Keyword</fc>''

**Default Response**

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

<WRAP center round help>
If You use another implementation like select2 jquery plugin you may need to use parameter showInText to true
</WRAP>

**Example:**
''%%http://example.com/api/v1/%%<fc #ff0000>users_search?showInText=1</fc>''

**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 [[https://select2.github.io/|select2.js]]

<code javascript>
<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>
</code>
<code html>
<input type="text" name="to_userid" id="Sendto" />
</code>