# Private Conversation

Private Conversation

This section provides necessary information related to newer type of private messaging system in "Conversational" style. Conversational PM allows user to exchange message in "thread style" with flexibility to invite additional users to the discussion. This kind of Private Messaging style is similar to a "private thread" style.

# new_conversation

Function:

Function Name	Description	Level
new_conversation	create a new converation between this user and other users.

Input Parameters:

Name	Type	Required?	Description
user_name	Array of byte[]	yes	To support creating a new conversation with multiple recipients, the app constructs an array and insert user_name for each recipient as an element inside the array.
subject	byte[]	yes
text_body	byte[]	yes
attachment_id_array	Array of String
group_id	String

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	true: action success. False: action failed
result_text	byte[]		message to be displayed to users if there is complication.
conv_id	String	yes	ID of new conversation just created.	4

# reply_conversation

Function:

Function Name	Description	Level
reply_conversation	reply to an existing conversation.

Input Parameters:

Name	Type	Required?	Description
conversation_id	String	yes	This is required to indicate which conversation this message is referred to.
text_body	byte[]	yes
subject	byte[]
attachment_id_array	Array of String
group_id	String

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	true: action success. False: action failed
result_text	byte[]		message to be displayed to users if there is complication.
msg_id	String	yes	new created message id in this conversation	4

# invite_participant

Function:

Function Name	Description	Level
invite_participant	Invite additional participants to an existing conversation.

Input Parameters:

Name	Type	Required?	Description
user_name	Array of byte[]	yes	To support inviting an existing conversation with multiple participants, the app constructs an array and insert user_name for each participant as an element inside the array.
conversation_id	String	yes	This is required to indicate which conversation this message is referred to.
invite_reason_text	byte[]		Reason to display to invitees

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	true: action success. False: action failed
result_text	byte[]		message to be displayed to users if there is complication.

# get_conversations

Function:

Function Name	Description	Level
get_conversations	Returns a list of conversations of this user, ordered by date descending order.

Input Parameters:

Name	Type	Required?	Description	Level
start_num	Int		same requirement as get_thread. Returns the latest 20 conversation if both start_num and end_num is not entered.
last_num	Int

Output Parameters:

Name	Type	Required?	Description
conversation_count	Int	yes	Returns total number of conversation in the box
unread_count	Int		Returns total number of conversations with unread message within.
can_upload	Boolean		Indicate if you can upload attachment when creating new conversation.
list	Array of Hash table		return a list of conversations from this box
conv_id	String	yes
reply_count	Int	yes	Returns total number of replies within this conversation.
participant_count	Int	yes	Returns total number of users participated in this conversation.
start_user_id	String
start_timestamp	String		Timestamp of conversation when it be create
start_conv_time	Date	yes	dateTime.iso8601 format time when the start message in this conversation was sent.
last_user_id	String	yes	The last poster id of this conversation
timestamp	String	yes	Timestamp of last message
last_conv_time	Date	yes	dateTime.iso8601 format time when the last message in this conversation was sent.
conv_subject	byte[]		conversation subject. Make sure to remove all BBCode
new_post	Boolean		Indicate if the conversation has unread message
unread_num	Int		Total unread message number in the conversation.
delete_mode	Int		Indicate which delete mode can be applied on this conversation when call delete_conversation method. 1:only support soft-delete mode; 2:only support hard-delete mode; 3:support both soft-delete mode and hard-delete mode. Default is 3 if this field is missing.
participants	Array of Hash table	yes	Each element in the hash-tabe with key as user_id, value as hash-table with two required keys: "username" and "icon_url". "username" and "icon_url" are to indicate the participant username and his/her avatar.
username	byte[]	yes
icon_url	String	yes
is_online	Boolean		return true if this user is currently online

# get_conversation

Function:

Function Name	Description	Level
get_conversation	Returns content of the conversation given a box id and conversation id

Input Parameters:

Name	Type	Required?	Description
conv_id	String	yes
start_num	Int	yes	For pagination. If start_num = 0 & last_num = 9, it returns first 10 messages from this conversation. If both are not presented, return first 20 messages. if start_num = 0 and last_num = 0, return the first message only, and so on (e.g. 1,1; 2,2). If start_num smaller than last_num returns null. If last_num - start_num > 50, returns only first 50 messages starting from start_num
last_num	Int	yes
return_html	Boolean

Output Parameters:

Name	Type	Required?	Description
conv_id	String	yes	conversation ID.
conv_title	byte[]	yes	Title of this conversation.
participant_count	Int	yes	Returns total number of users participated in this conversation.
total_message_num	Int	yes	total number of messages in this converation
can_invite	Boolean	yes	return true if user can invite new members to this conversation
can_edit	Boolean		return true if user can edit this conversation title. Default is false if this field is missing.
can_close	Boolean		return true if user can close this conversation. Default is "false" if this field is missing.
is_closed	Boolean	yes	Returns true if this conversation has been closed. Default is "false" if this field is missing.
can_upload	Boolean		Indicate if you can add attachment when reply conversation
delete_mode	Int		Indicate which delete mode can be applied on this conversation when call delete_conversation method. 1:only support soft-delete mode; 2:only support hard-delete mode; 3:support both soft-delete mode and hard-delete mode. Default is 3 if this field is missing.
participants	Array of Hash table		The same as in get_conversations
username	byte[]		participated user name
icon_url	String		Return message author avatar URL
list	Array of Hash table		an array contains a list of messages in this conversation.
msg_id	String	yes
msg_content	byte[]	yes	Characters display rules (follow the sequence): 1) Remove all BBCode except [ur], [img], [quote]. 2) Remove all non-displayable characters (e.g. \n, \t, white-space, etc) at the beginning AND the end of the content (Trimming) 3) Replace [url] tags in nested [url][img][/img][/url] image link.
msg_author_id	String	yes	message author id
is_unread	Boolean		return true if this message is not yet read by the user. Useful for app to scroll to first unread when entering a conversation.
is_online	Boolean		return true if this user is currently online
has_left	Boolean		return true if user has left this conversation. Default is "false" if this field is missing
timestamp	String	yes	Timestamp of message creation time
post_time	Date	yes	dateTime.iso8601 format. message creation time.
new_post	Boolean		Indicate if the message is unread
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_conversation

Function:

Function Name	Description	Level
get_quote_conversation	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

Input Parameters:

Name	Type	Required?	Description	Level
conv_id	String	yes	Conversation ID
msg_id	String	yes

Output Parameters:

Name	Type	Required?	Description	Level
text_body	byte[]		returns message body usually with [quote] content.

# delete_conversation

Function:

Function Name	Description	Level
delete_conversation	delete an entire conversation. In some forum systems such as XenForo, it is called "leave conversation".

Input Parameters:

Name	Type	Required?	Description	Level
conv_id	String	yes	returns message body usually with [quote] content.
mode	Int	yes	1: soft-delete (For XenForo plugin only. conversation is hidden but will re-appear when there is new message entered into the conversation.). 2: hard-delete (remove me from this conversation and do not show up in my Inbox even when there is new message.)

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes
result_text	byte[]

# mark_conversation_unread

Function:

Function Name	Description	Level
mark_conversation_unread	Mark conversations as unread. Supported when flag 'mark_pm_unread' was returned in get_config

Input Parameters:

Name	Type	Required?	Description	Level
conv_id	String	yes	Conversation id. To mark more than one conversation to be unread, provide more ids separated by ','

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes
result_text	byte[]

# mark_conversation_read

Function:

Function Name	Description	Level
mark_conversation_read	Mark conversations as read. Supported when flag 'mark_pm_read' was returned in get_config

Input Parameters:

Name	Type	Required?	Description	Level
conversation id(s)	String		Id(s) of conversion to be marked as read, separated by comma for more tham one id. If this parameter was not provide, all conversaions will be marked as read

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes
result_text	byte[]

← Moderation Account →