# Private Message
This section provides necessary functions related to private messaging such ability to send/reply/delete/forward private messages. This set of API supports traditional inbox/sent items messaging with multiple folders support.
# report_pm
Function:
| Function Name | Description | Level |
|---|---|---|
| report_pm | report a problematic private message to moderator. This function is used in conjunction with "report_pm" flag returned from "get_config" function. |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| msg_id | String | yes | ||
| reason | byte[] | optional. Allow user to add a message to describe the problem. |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | Return "true" if the action is executed successfully. "false" otherwise. | |
| result_text | byte[] | Message to be displayed to user after this action is executed. Optional. |
# create_message
Function:
| Function Name | Description | Level |
|---|---|---|
| create_message | send a private message to one or more users. | 3 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| user_name | Array of byte[] | yes | To support sending message to multiple recipients, the app constructs an array and insert user_name for each recipient as an element inside the array. | 3 |
| subject | byte[] | yes | 3 | |
| text_body | byte[] | yes | 3 | |
| action | Int | 1 = REPLY to a message; 2 = FORWARD to a message. If this field is presented, the pm_id below also need to be provided. | 3 | |
| pm_id | String | It is used in conjunction with "action" parameter to indicate which PM is being replied or forwarded to. | 3 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | true: action success. False: action failed | 3 |
| result_text | byte[] | 3 | ||
| msg_id | String | yes | the new created message id | 4 |
# get_box_info
Function:
| Function Name | Description | Level |
|---|---|---|
| get_box_info | Returns a list of message boxes and their information. It allows the app to support multiple folders beyond Inbox and Sent box. | 3 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | true: action success. False: action failed | 3 |
| result_text | byte[] | 3 | ||
| message_room_count | Int | returns remaining message quota - certain forum systems put a limit on how many messages a user can store. | 3 | |
| list | Array of Hash table | yes | returns a list of folder/box information | 3 |
| box_id | String | yes | 3 | |
| box_name | byte[] | yes | 3 | |
| msg_count | Int | yes | number of messages in this box. | 3 |
| unread_count | Int | yes | number of unread messages in this box. | 3 |
| box_type | String | Optional. returns "INBOX" if it is inbox. Returns "SENT" if it is a sent-box. | 3 |
# get_box
Function:
| Function Name | Description | Level |
|---|---|---|
| get_box | Returns a list of message subject and short content from a specific box. | 3, 4 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| box_id | String | yes | API level 4 feature: return only unread pms if box_id is 'unread' | 3,4 |
| start_num | Int | same requirement as get_thread. Returns the latest 20 messages if both start_num and end_num is not entered. | 3 | |
| end_num | Int | para_description | 3 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | true: action success. False: action failed | 3 |
| result_text | byte[] | 3 | ||
| total_message_count | Int | yes | Returns total number of messages in the box | 3 |
| total_unread_count | Int | yes | Returns total number of unread messages in this box | 3 |
| list | Array of Hash table | yes | return a list of messages from this box | 3 |
| msg_id | String | yes | ||
| msg_state | Int | yes | 1 = "Unread", 2 = "Read", 3 = "Replied", 4 = "Forwarded" | 3 |
| timestamp | String | The time stamp when the message is sent. | ||
| sent_date | Date | The time stamp when the message is sent. | 3 | |
| msg_from_id | String | yes | user id of the message sender | 4 |
| msg_from | byte[] | username of the message sender. this field is not required if the current box is a Sent box | 3 | |
| icon_url | String | returns the sender avatar URL. If the current box is a Sent box, returns the first recipient avatar URL | 3 | |
| msg_subject | byte[] | message subject. Make sure to remove all BBCode | 3 | |
| short_content | byte[] | same rule as get_topic short_content | 3 | |
| is_online | Boolean | This value is to indicate whether the sender of this message is currently online. | 4 | |
| msg_to | Array of Hash table | yes | returns an array of Hash-table of recipient data | 3,4 |
| user_id | String | 4 | ||
| username | byte[] | yes | 3 |
# get_message
Function:
| Function Name | Description | Level |
|---|---|---|
| get_message | Returns content of private message given a box id and message id | 3, 4 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| message_id | String | yes | 3 | |
| box_id | String | yes | 3 | |
| return_html | Boolean | yes | Return post content with some bbcode supported. Currently it can return <i>, <u>, <b> and <font color="xxxx"> where "xxxx" is name of the color. This extra parameter is used in conjunction with "disable_html" flag in get_config. If "disable_html=0" or is missing, this parameter should be set to false. Otherwise if disable_html is "1", this paramter should be set to true, or simply not using this paramter at all.</font></b></u></i> | 4 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | true: action success. False: action failed | 3 |
| result_text | byte[] | 3 | ||
| msg_from_id | String | 4 | ||
| msg_from | byte[] | username of the message sender. this field is not required if the current box is a Sent box | 3 | |
| icon_url | String | returns the sender avatar URL. If the current box is a Sent box, returns the first recipient avatar URL | 3 | |
| sent_date | Date | The time stamp when the message is sent. | 3 | |
| timestamp | String | The time stamp when the message is sent. | ||
| msg_subject | byte[] | message subject. Make sure to remove all BBCode | 3 | |
| text_body | byte[] | same rule as get_thread's post_content field | 3 | |
| is_online | Boolean | This value is to indicate whether the sender of this message is currently online. | 3 | |
| allow_smilies | Boolean | This value (if "false") is to instruct the app do not display smilies and instead display it in text format. This is to address certain forum system allows forum admin to disable smilies across the board. If this flag is missing, assume "true" | 4 | |
| msg_to | Array of Hash table | yes | returns an array of Hash-table of recipient data | 3,4 |
| user_id | String | 4 | ||
| username | byte[] | yes | 3 | |
| attachments | Array of Hash table | Returns a list of attachments user has uploaded within this message, in array of hash format. | ||
| filename | byte[] | yes | ||
| filesize | Int | yes | ||
| content_type | String | yes | return "jpg", "pdf" or other file extension. | |
| url | String | yes | URL of the attachment source. | |
| thumbnail_url | String | if content type is image, use absolute path (optional: if not presented, use "url" to load thumbnail instead) |
# get_quote_pm
Function:
| Function Name | Description | Level |
|---|---|---|
| get_quote_pm | Returns a processed [quote] content just like when user click the Reply or Forward button on the web browser. This is to address different forum systems requires different [quote] format | 3 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| message_id | String | yes | 3 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | true: action success. False: action failed | 3 |
| result_text | byte[] | 3 | ||
| msg_id | String | yes | 3 | |
| msg_subject | byte[] | Returns the processed title for a message reply which can be language and forum system specific. | 3 | |
| text_body | byte[] | returns message body usually with [quote] content. | 3 |
# delete_message
Function:
| Function Name | Description | Level |
|---|---|---|
| delete_message | delete a particular private message | 3 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| message_id | String | yes | 3 | |
| box_id | String | yes | 3 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | 3 | |
| result_text | byte[] | 3 |
# mark_pm_unread
Function:
| Function Name | Description | Level |
|---|---|---|
| mark_pm_unread | mark the particular private message as unread | 4 |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| message_Id | String | yes | 4 |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | 4 | |
| result_text | byte[] | 4 |
# mark_pm_read
Function:
| Function Name | Description | Level |
|---|---|---|
| mark_pm_read | Mark pms as read. Supported when flag 'mark_pm_read' was returned in get_config |
Input Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| message id(s) | String | Id(s) of pm to be marked as read, separated by comma for more tham one id. If this parameter was not provides, all pms will be marked as read |
Output Parameters:
| Name | Type | Required? | Description | Level |
|---|---|---|---|---|
| result | Boolean | yes | ||
| result_text | byte[] |