# Moderation

Moderation

This section provides necessary information related to topics and posts moderation. It includes ability to stick/unstick, move and delete topics, ability to close or reopen topics. And ability to return a topics/post moderation queue for moderator/administrator alike to approve topics. It also supports banning a particular user with options to delete all his posts in the forum, handy for quickly removing spammer.

Function:

Function Name Description Level
get_topic get_latest_topic get_unread_topic get_participated_topic get_subscribed_topic search_topic get_user_topic search Add the following key-value pairs to the existing functions:

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
topics Array of Hash table Add the following key-value pairs to the topics hash data
can_ban Boolean return true if the user has authority to ban the first or last post creator, depends on the function return from. E.g. get_unread_topic returns the last post, hence can_ban flag should indicate where the user has the authority to ban the last post creator.
is_ban Boolean return true if the user has already been banned.
can_delete Boolean return true if the user has authority to delete this topic.
is_deleted Boolean return true if this topic has been soft-deleted.
can_approve Boolean return true if the user has authority to approve this topic. This field is only returned with a topic is awaiting for moderation. If the topic does not need moderation or the topic has already been approved. Do not return this field.
is_approved Boolean return false if this topic is not yet approved. If this key is missing, assume the thread is already approved. E.g. user login as admin will have the ability to see unapproved topic.
can_stick Boolean return true if the user has authority to stick or unstick this topic.
is_sticky Boolean return true if this topic is set as sticky mode.
can_close Boolean return true if the user has authority to close this topic.
can_rename Boolean return true if the user has authority to rename this topic.
can_move Boolean return true if the user has authority to move this topic to somewhere else.
can_merge Boolean Indicate if the user can merge topics in current sub-forum. Only for function get_topic

# search_post,get_user_reply_post

Function:

Function Name Description Level
search_post get_user_reply_post Add the following key-value pairs to the existing functions:

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
posts Array of Hash table Add the following key-value pairs to posts hash data
can_ban Boolean return true if the user has authority to ban the post creator, depends on the function return from. E.g. get_unread_topic returns the last post, hence can_ban flag should indicate where the user has the authority to ban the last post creator.
is_ban Boolean return true if the user has already been banned.
can_delete Boolean return true if the user has authority to delete this post.
is_deleted Boolean return true if this post has been soft-deleted.
can_approve Boolean return true if the user has authority to approve this post. This field is only returned with a post is awaiting for moderation. If the topic does not need moderation or the post has already been approved. Do not return this field.
is_approved Boolean return false if this post is not yet approved. If this key is missing, assume the thread is already approved. E.g. user login as admin will have the ability to see unapproved topic.
can_move Boolean return true if the user has authority to move this post to somewhere else.

# get_user_info

Function:

Function Name Description Level
get_user_info Add the following key-value pairs to the existing functions:

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
Array of Hash table Add the following key-value pairs to existing return structure.
can_ban Boolean return true if the user has the authority to ban the user returned in get_user_info
is_ban Boolean return true returned user in get_user_info has already been banned.

# get_thread,get_thread_by_unread,get_thread_by_post

Function:

Function Name Description Level
get_thread get_thread_by_unread get_thread_by_post Add the following key-value pairs to the existing functions:

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
can_merge Boolean Indicate if the user can merge this thread with other thread
can_merge_post Boolean Indicate if the user can merge posts in current thread.
can_rename Boolean return true if the user has authority to rename this topic.
can_delete Boolean return true if the user has authority to delete this topic.
can_close Boolean return true if the user has authority to close this topic.
can_approve Boolean return true if the user has authority to approve this topic. This field is only returned with a topic is awaiting for moderation. If the topic does not need moderation or the topic has already been approved. Do not return this field.
can_stick Boolean return true if the user has authority to stick or unstick this topic.
can_move Boolean return true if the user has authority to move this topic to somewhere else.
can_ban Boolean return true if the user has authority to ban this post creator.
is_ban Boolean return true if the user has already been banned
is_approved Boolean return false if this topic is not yet approved. If this key is missing, assume the thread is already approved. E.g. user login as admin will have the ability to see unapproved topic.
is_deleted Boolean return true if this topic has been soft-deleted. E.g. user login as admin will have the ability to see soft-deleted topic and will have the ability to undelete it
posts Array of Hash table add the following key-value pair in the "posts" hash
is_deleted Boolean return true if this topic has been soft-deleted. E.g. user login as admin will have the ability to see soft-deleted topic and will have the ability to undelete it.
can_delete Boolean return true if the user has authority to delete this post.
is_ban Boolean return true if the user has already been banned.
can_approve Boolean return true if the user has authority to approve this topic. This field is only returned with a topic is awaiting for moderation. If the topic does not need moderation or the topic has already been approved. Do not return this field.
is_approved Boolean return false if this topic is not yet approved. If this key is missing, assume the thread is already approved. E.g. user login as admin will have the ability to see unapproved topic.
can_ban Boolean return true if the user has authority to ban this post author.
can_move Boolean return true if the user has authority to move this topic to somewhere else.

# login_mod

Function:

Function Name Description Level
login_mod This is used in conjuntion with the "is_login_mod" flag returned from the below functions. If this flag is set to true, the app need to re-authenticate with server to receive a special cookies to proceed.

Input Parameters:

Name Type Required? Description Level
username byte[] yes
password byte[] yes The app should send the encrypted password to the server if there is instruction received from get_config. Otherwise send the plain-text password. For example most of the vBulletin systems requires md5 encryption by default, while SMF systems support SHA-1 encryption.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] message to be displayed to users if there is complication.

# m_stick_topic

Function:

Function Name Description Level
m_stick_topic

Input Parameters:

Name Type Required? Description Level
topic_id String yes
mode Int yes "1" = stick a topic. "2" = unstick a topic.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_close_topic

Function:

Function Name Description Level
m_close_topic

Input Parameters:

Name Type Required? Description Level
topic_id String yes
mode Int "1" = reopen a topic. "2" = close a topic.

Output Parameters:

Name Type Required? Description Level
result Boolean return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean yes return true if user need to re-authenticate with login_mod function again before proceeding.

# m_delete_topic

Function:

Function Name Description Level
m_delete_topic

Input Parameters:

Name Type Required? Description Level
topic_id String yes
mode Int yes "1" = soft-delete a topic. "2" = hard-delete a topic. If a particular forum system does not support soft-delete, always perform a hard delete.
reason_text byte[] This option allows user to insert the reason of deletion.

Output Parameters:

Name Type Required? Description Level
result Boolean return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean yes return true if user need to re-authenticate with login_mod function again before proceeding.

# m_delete_post

Function:

Function Name Description Level
m_delete_post Ability to delete a particular post. Please refer to "delete_post" for deleting own post.

Input Parameters:

Name Type Required? Description Level
post_id String yes
mode Int "1" = soft-delete a post. "2" = hard-delete a post. If a particular forum system does not support soft-delete, always perform a hard delete.
reason_text byte[] This option allows user to insert the reason of deletion.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_undelete_topic

Function:

Function Name Description Level
m_undelete_topic Ability to undo a previously soft-deleted topics

Input Parameters:

Name Type Required? Description Level
topic_id String yes
reason_text byte[] This option allows user to insert the reason of this action.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_undelete_post

Function:

Function Name Description Level
m_undelete_post Ability to undelete a previously soft-deleted post.

Input Parameters:

Name Type Required? Description Level
post_id String yes
reason_text byte[] This option allows user to insert the reason of this action.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_move_topic

Function:

Function Name Description Level
m_move_topic Ability to move a topic from one forum to another forum.

Input Parameters:

Name Type Required? Description Level
topic_id String yes
forum_id String yes
redirect Boolean Indicate if a redirect link need to be created for moved topic. Default action will be done if it's not set. Flag 'advanced_move' in get_config will indicate the support of this parameter.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_rename_topic

Function:

Function Name Description Level
m_rename_topic Ability to move a topic from one forum to another forum.

Input Parameters:

Name Type Required? Description Level
topic_id String yes
title byte[] yes Rename to topic title.
prefix_id String prefix ID that user has selected. List of prefixes are returned from "get_topic" method. Plugin supported this parameter when get_config return 'prefix_edit' as 1

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_move_post

Function:

Function Name Description Level
m_move_post Ability to extract a post from an existing topic and merge with another existing topic, or extract an existing post and create a new topic with this post.

Input Parameters:

Name Type Required? Description Level
post_id String yes Separate more post ids with ','
topic_id String The destination topic of the post to be moved to. If it is to be moved to a new topic, leave this field as NULL.
topic_title byte[] If "topic_id" is NULL, this parameter is required. It creates a new topic with this title and move the post as the first post of this topic.
forum_id String The destination forum of the post to be moved to. If it is not to be moved to a new topic, leave this field as NULL.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod byte[] return true if user need to re-authenticate with login_mod function again before proceeding.
topic_id String If a post(s) was moved as a new topic, return the new topic id

# m_merge_topic

Function:

Function Name Description Level
m_merge_topic Ability to merge two topics into a single topic. From topic A to topic B, and keep topic B subject title.

Input Parameters:

Name Type Required? Description Level
topic_id String yes Topic A
topic_id String yes Topic B
redirect Boolean Indicate if a redirect link need to be created for merged topic. Default action will be done if it's not set. Flag 'advanced_merge' in get_config will indicate the support of this parameter.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
topic_id String For some forum system (like SMF), it does not support merge to a specified topic, and it always keep the older topic id for merged topic. In this case, plugin need return the target topic id
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_get_moderate_topic

Function:

Function Name Description Level
m_get_moderate_topic Returns a list of topics awaiting moderator approval. This function will only invoked if get_config returns "m_approve = 1"

Input Parameters:

Name Type Required? Description Level
start_num Int For pagination. If start_num = 0 & last_num = 9, it returns first 10 items, sorted by date (last-in-first-out). If both are not presented, return first 20 items. if start_num = 0 and last_num = 0, return the first item only. If last_num smaller than start_num returns error code "Out-of-range" (see error code column). If last_num - start_num > 50, returns only first 50 items starting from start_num.
last_num Int See above.

Output Parameters:

Name Type Required? Description Level
total_topic_num Int Total number of topics awaiting to be moderated.
topics Array of Hash table Returns a list of topic in an array, each topic is in Hash Table format. Returns null if total_topic_num = 0
forum_id String yes
forum_name byte[] yes
topic_id String yes
topic_title byte[] yes Remove all BBCode in title
topic_author_id String
topic_author_name byte[] yes
icon_url String Return topic author avatar URL
post_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time.
timestamp String yes Timestamp of topic last post
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters
moderated_by_id String
moderated_by_name byte[] If this topic has already been moderated, return the username of the person who moderated this topic
moderated_reason byte[]

# m_get_moderate_post

Function:

Function Name Description Level
m_get_moderate_post Returns a list of posts awaiting moderator approval. This function will only invoked if get_config returns "m_approve = 1"

Input Parameters:

Name Type Required? Description Level
start_num Int For pagination. If start_num = 0 & last_num = 9, it returns first 10 items, sorted by date (last-in-first-out). If both are not presented, return first 20 items. if start_num = 0 and last_num = 0, return the first item only. If last_num smaller than start_num returns error code "Out-of-range" (see error code column). If last_num - start_num > 50, returns only first 50 items starting from start_num.
last_num Int See above.

Output Parameters:

Name Type Required? Description Level
total_post_num Int yes Total number of posts awaiting to be moderated.
posts Array of Hash table Returns a list of post in an array, each post is in Hash Table format. Returns null if total_post_num = 0
forum_id String yes
forum_name byte[]
topic_id String
topic_title byte[] Remove all BBCode in title
post_id String
post_title byte[] Remove all BBCode in title
post_author_id String
post_author_name byte[]
icon_url String Return topic author avatar URL
timestamp String Timestamp of topic last post
post_time Date dateTime.iso8601 format. If this topic has no reply, use the topic creation time.
short_content byte[] yes Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters
moderated_by_id String
moderated_by_name byte[] If this post has already been moderated, return the username of the person who moderated this post.
moderated_reason byte[]

# m_approve_topic

Function:

Function Name Description Level
m_approve_topic Moderator to approve or unapprove a specific topic.

Input Parameters:

Name Type Required? Description Level
topic_id String yes
mode Int yes "1" = approve the topic. "2" = unapprove the topic.

Output Parameters:

Name Type Required? Description Level
result Boolean return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.

# m_approve_post

Function:

Function Name Description Level
m_approve_post Moderator to approve or unapprove a specific post.

Input Parameters:

Name Type Required? Description Level
post_id String yes
mode Int yes "1" = approve the post. "2" = unapprove the post.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.

# m_ban_user

Function:

Function Name Description Level
m_ban_user Ability to ban a particular user.

Input Parameters:

Name Type Required? Description Level
user_name byte[] yes
mode Int yes "1" = ban the user. "2" = ban the user and delete all his posts (soft-delete if soft-delete is supported by the forum system.
reason_text byte[] This option allows user to insert the reason of deletion.
expires Int Expire timestamps. need flag 'ban_expires' in get_config to support this parameter

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_get_delete_topic

Function:

Function Name Description Level
m_get_delete_topic Returns a list of topics that have been soft-deleted. Only return soft-deleted topics that this user has the authority to perform further action such as undelete or hard-delete. This function will only invoked if get_config returns "m_delete = 1"

Input Parameters:

Name Type Required? Description Level
start_num Int yes For pagination. If start_num = 0 & last_num = 9, it returns first 10 items, sorted by date (last-in-first-out). If both are not presented, return first 20 items. if start_num = 0 and last_num = 0, return the first item only. If last_num smaller than start_num returns error code "Out-of-range" (see error code column). If last_num - start_num > 50, returns only first 50 items starting from start_num.
last_num Int yes See above.

Output Parameters:

Name Type Required? Description Level
total_topic_num Int yes Total number of topics that has been soft-deleted.
topics Array of Hash table Returns a list of topic in an array, each topic is in Hash Table format. Returns null if total_topic_num = 0
forum_id String yes
forum_name byte[] yes
topic_id String yes
topic_title byte[] yes Remove all BBCode in title
topic_author_id String yes 4
topic_author_name byte[] yes
icon_url String Return topic author avatar URL.
post_time Date yes dateTime.iso8601 format. The datetime of this topic is created.
timestamp String yes Timestamp of topic last post
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters
deleted_by_id String 4
deleted_by_name byte[] yes Return the username of the person who has previously soft-deleted this topic
delete_reason byte[] Return reason of deletion, if any.

# m_get_delete_post

Function:

Function Name Description Level
m_get_delete_post Returns a list of previously soft-deleted posts. This function will only invoked if get_config returns "m_delete = 1"

Input Parameters:

Name Type Required? Description Level
start_num Int yes For pagination. If start_num = 0 & last_num = 9, it returns first 10 items, sorted by date (last-in-first-out). If both are not presented, return first 20 items. if start_num = 0 and last_num = 0, return the first item only. If last_num smaller than start_num returns error code "Out-of-range" (see error code column). If last_num - start_num > 50, returns only first 50 items starting from start_num.
last_num Int yes See above.

Output Parameters:

Name Type Required? Description Level
total_post_num Int yes Total number of posts awaiting to be moderated.
posts Array of Hash table yes Returns a list of post in an array, each post is in Hash Table format. Returns null if total_post_num = 0
forum_id String yes
forum_name byte[] yes
topic_id String yes
topic_title byte[] yes
post_id String yes
post_title byte[] yes Remove all BBCode in title
post_author_id String
post_author_name byte[] yes
icon_url String Return post author avatar URL
timestamp String Timestamp of topic last post
post_time Date
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert \"[url http://...]http://…..[/url]\" to \"[url]\". 3) Convert \"[img]http://…..[/img]\" to \"[img]\". 4) Remove \"Last edited by...\" tag at the end. 5) Remove all non-displayable characters (e.g. \\n, \\t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters
deleted_by_id String
deleted_by_name byte[] Return the username of the person who has previously soft-deleted this topic
delete_reason byte[] Return reason of deletion, if any.

# m_get_report_post

Function:

Function Name Description Level
m_get_report_post Returns a list of user reported posts. This function will only invoked if get_config returns "m_report = 1"

Input Parameters:

Name Type Required? Description Level
start_num Int yes For pagination. If start_num = 0 & last_num = 9, it returns first 10 items, sorted by date (last-in-first-out). If both are not presented, return first 20 items. if start_num = 0 and last_num = 0, return the first item only. If last_num smaller than start_num returns error code "Out-of-range" (see error code column). If last_num - start_num > 50, returns only first 50 items starting from start_num.
last_num Int yes See above.

Output Parameters:

Name Type Required? Description Level
total_report_num Int yes Total number of reported posts.
reports Array of Hash table yes Returns a list of reported post in an array, each post is in Hash Table format. Returns null if total_report_num = 0
forum_id String yes
forum_name byte[] yes
topic_id String yes
topic_title byte[] yes
post_id String yes
post_title byte[] yes
post_author_id String yes
post_author_name byte[] yes
icon_url String yes post author avatar url
post_time Date yes
timestamp String yes Timestamp of topic last post
short_content byte[] yes Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters
report_id String ID of the report record if forum system provide.
reported_by_id String
reported_by_name byte[]
report_reason byte[]

# m_mark_as_spam

Function:

Function Name Description Level
m_mark_as_spam Mark the user as spammer. This function call was controlled by flag 'can_mark_spam' in related functions. Flag 'is_spam' is the status indicator. Currently it's supported in IPBoard plugin only.

Input Parameters:

Name Type Required? Description Level
user_id String yes The ID of user which will be marked as spammer.

Output Parameters:

Name Type Required? Description Level
result Boolean yes Return 1 if the user was successully been marked as spammer.
result_text byte[] Reason of the failure, if any.

# m_merge_post

Function:

Function Name Description Level
m_merge_post Ability to merge posts into a single post. From posts A to post B, and keep post B subject title author and time. Flag 'can_merge_post' in get_thread will indicate the support of this function.

Input Parameters:

Name Type Required? Description Level
post_ids String yes Posts A. Can be ',' separated posts id like '1,2,3'
post_id String yes Target post id will be merged to

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully.
result_text byte[] Reason of the failure, if any.
is_login_mod Boolean return true if user need to re-authenticate with login_mod function again before proceeding.

# m_unban_user

Function:

Function Name Description Level
m_unban_user Lift ban for a banned user. Flag to indicate this function in get_config 'unban'

Input Parameters:

Name Type Required? Description Level
user_id String yes

Output Parameters:

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

# m_close_report

Function:

Function Name Description Level
m_close_report Close a report to a post. Flag to indicate this function in get_config 'close_report'

Input Parameters:

Name Type Required? Description Level
report_id String ID of report record if it's returned in m_get_report_post . Otherwise it should be the Post ID

Output Parameters:

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

# m_get_inactive_users

Function:

Function Name Description Level
m_get_inactive_users get all inactive user list 4

Input Parameters:

Name Type Required? Description Level
page Int 4
perpage Int 4

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 4
member_count Int yes number of members 3
list Array of Hash table yes 4
list Array of Hash table yes 4
list Array of Hash table yes 4

# m_approve_user

Function:

Function Name Description Level
m_approve_user approve user, unapprove user 4

Input Parameters:

Name Type Required? Description Level
user_id Int yes User id
user_name String yes User name
mode Int yes "1" = approve the user. "2" = unapprove the user.

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 4