Messaging

Messaging is the module for ExpressioEngine 2 that brings all power of Private Messages, Bulletins (public messages) and Buddies/Blocked lists to frontent templates - even with AJAX support!

Basic concepts
Bulletins
- Compose Bulletin
- View Bulletins
Private Messages
Member lists
Extension hooks

↑ Basic concepts

Here are some Basic concepts regaring messaging in ExpressionEngine.

Private Messages are similar to being able to send another user an email. In this case, though, they access the Private Message through the EE website and not with an email program.

You are able to send Private Messages (PM) to one or several site members, add attachments, reply, forward. PMs can be organized in folders.

Unlike Private Messages, Bulletins do not get sent to each sender, but rather are viewable by all members of the member group(s) designated as recipients. Additionally, Bulletins can have an expiration date, making them ideal for mass communication of time-sensitive information. You can think of bulletins as Public messages.

You may organize site members that you communicate with into Buddies List and Blocked List. You may think of Buddies List as list of people you follow (or simply use it for easy access to selected profiles). Blocked List is the list of members from which you will not accept Private Messages.

↑Bulletins

↑Compose Bulletin


{exp:messaging:bulletin_compose}

<p>Recipients:

{recipients}

<br /><input type="checkbox" name="recipients[]" value="{recipient_id}" /> {recipient_name}

{/recipients}

</p>

<p>Expire this bulletin on:

<br /><input type="text" name="bulletin_expires" value="{current_time format="%Y-%m-%d %H:%i:%s"}" />

</p>

<p>Message text:

<br /><textarea name="message"></textarea>

</p>

<p><input type="submit" value="send" /></p>

{/exp:messaging:bulletin_compose}

{exp:messaging:bulletin_compose} tag will generate the form used to compose bulletin message.

Form fields:

recipients — IDs or recipient member groups. You can let senders select one or several group (in last case, the field should ba named recipients[]). Mandatory
message — message text. Mandatory.
bulletin_expires — the date and time when the bulletin will be expired (and not shown to recipients anymore). Optional (if omited, message will expire in 30 days).

Form tag parameters:

return — a page to return after sending message. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display form.
skip_success_message="yes" — force redirect to return page without showing success message.
ajax="yes" — turn on AJAX mode. The success or error messages shown upon submission will be shown as simple text, without using message templates. The "return" parameter will not be functional if you supply this parameter.
silent="yes" — turn on "silent" mode. Will not show error page when the user has no permission to send bulletin messages, but will output the code surrounded with {if no_results}{/if} tags.
id — form ID (defaults to 'messaging_form')
class — form class (defaults to 'messaging_form')
name — form name (defaults to 'messaging_form')

↑View Bulletins


{exp:messaging:bulletins}

<div id="bulletin_{message_id}">

Message from <a href="{path=member/profile/{sender_member_id}}">{sender_screen_name}</a> ({message_date format="%Y-%m-%d"}

<hr />

{message}

</div>

{/exp:messaging:bulletins}

{exp:messaging:bulletins} tag will display all or certain bulletin message for logged in user.

Tag parameters (all optional):

message_id — bulletin message ID, if you want to limit view to certain message
show_expired="yes" — display also expired messages (by default expired message are not dispalyed)
only_new="yes" — display only new bulletins, that the user has never seen
limit — number of bulletins per page (if you have many messages and want to use pagination)
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result
ajax="yes" — turn on AJAX mode for delete_link. The success or error messages shown upon clicking delete_link will be shown as simple text, without using message templates.

Conditional variables:

{if no_results}{/if} — displayed if there are no messages available
{if can_delete}{/if} — displayed if user has permissions to delete this bulletin (is sender or admin). Deleting the bulletin will completely remove it from the system.

Single variables:

total_results — total number of bulletin messages available for user
count — message counter on each page
absolute_count — message counter throughout all pages
message_id — bulletin message ID
sender_member_id — member ID of person who sent the message
sender_username — username of person who sent the message
sender_screen_name — screen name of person who sent the message
sender_email — email of sender
sender_avatar_url — URL of sender's avatar
sender_photo_url — URL of sender's profile photo
message — message text
message_date format="%Y-%m-%d" — the date when message has been sent. Standard EE date formatting rules apply.
delete_link — pre-formatted link to delete message (shown only if user has permissions)
{paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page). You can also use {pagination_links} tag pair, like with channel entries pagination.

↑Private Messages

↑Compose PM


{exp:messaging:pm_compose save_sent="yes"}

{if warning}

<div class="warning">{warning}</div>

{/if}

<p>Recipient:

<br /><input type="text" name="recipients" value="{recipient_from_url}" />

</p>

<p>Subject:

<br /><input type="text" name="subject" value="{subject}" />

</p>

<p>Message text:

<br /><textarea name="message">{message}</textarea>

</p>

{if attachments_allowed}

<p>Attachments:

<br /><input type="file" name="attachment[]" />

<br /><input type="file" name="attachment[]" />

<br /><input type="file" name="attachment[]" />

</p>

{/if}

<p><input type="submit" value="send" /></p>

{/exp:messaging:pm_compose}

{exp:messaging:pm_compose} is the tag that generates form used for composing the message (and also for replying and forwarding)

In there has been non-critical error after submiting the form (the user has permissions to send the message, but it cannot be delivered for some reason, e.g. recipient is invalid) the error message will not be shown, but the user will be redirected back to message composing page with warning message displayed. Previously entered data will be available in corresponding variables.

Form fields:

recipients — Screen names (not usernames!) or recipient members. Separate multiple recipients with comma. Mandatory.
cc — Screen names (not usernames!) or members whom you want to send copy of message. Optional.
subject — message subject. Mandatory.
message — message body. Mandatory.
attachment — input for file you want to attach. You can place multiple attachment fields (in this case, the fields should ba named attachment[]) - but make sure not more than number of files allowed to attach set in PM preferences. Optional.
forward_attachments[] — if you are forwaring message, you can use this fiels by marking checkboxes for attachments you want to forward together with the message. Must be used inside {attachments} variable pair. Optional.

Form tag parameters:

replying — If you are replying to message, set the value of this parameter to ID of message you're replying to, e.g. replying="143". It will mark the original message in your list as 'replied'. In order to get screen name of original message author (and use as recipient) use {exp:messaging:author} tag. In order to get recipients of original messages (to use as CC if you 'reply all') use {exp:messaging:recipients}
forwarding — If you are forwarding some message, set the value of this parameter to ID of message you're forwarding, e.g. forwarding="143". It will mark the original message in your list as 'forwarded'.
save_sent="yes" — Save message copy in 'Sent' folder.
hide_cc="yes" — setting this will hide recipients listed in cc field, thus making in fuction as blind copy field (bcc)
return — a page to return after sending message. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display form.
skip_success_message="yes" — force redirect to return page without showing success message.
ajax="yes" — turn on AJAX mode. The success or error messages shown upon submission will be shown as simple text, without using message templates. The "return" parameter will not be functional if you supply this parameter.
silent="yes" — turn on "silent" mode. Will not show error page when the user has no permission to send bulletin messages, but will output the code surrounded with {if no_results}{/if} tags.
id — form ID (defaults to 'messaging_form')
class — form class (defaults to 'messaging_form')
name — form name (defaults to 'messaging_form')

Conditional variables:

{if attachments_allowed}{/if} — displayed if user has permissions to add attachment files to the message.
{if attachments}{/if} — displayed if this is message forwaring and orginal message has attachments.
{if warning}{/if} — displayed if the message has not been sent but user has been redirected back to composing page with warning message
{if recipient_from_url}{/if} — displayed if system is able to find out recipient by ID or username specified in URL

Single variables:

warning — pre-formatted warning message
subject — saved subject, if warning has been returned and message not sent. If the form is for forwarding or replying, contains subject of original message, prefixed with Fwd: or Re:
message — saved message text, if warning has been returned and message not sent. If the form is for forwarding or replying, contains message body of original message, surrounded with [quote]
recipient_from_url — if the last segment of URL is valid username or member ID, this variable will contain screen name of member corresponding to that segment (can be used as recipient)

Variable pairs:

{attachments backspace="X"}{/attachments} — used to display list of attachment for message being forwarded. Can be used to populate forward_attachments[] fields for selecting which attachments should be forwarded too. Inside {attachments} following variables are available:

attachment_id — attachment ID (used as value for input)
attachment_name — file name
attachment_size — file size
attachment_extension — file extension

backspace parameter is optional and lets you remove X last characters from the output.

Example forwaring message:


{exp:messaging:pm_compose forwarding="{segment_3}"}

{if warning}

<div class="warning">{warning}</div>

{/if}

<p>Recipient:

<br /><input type="text" name="recipients" value="" />

</p>

<p>Subject:

<br /><input type="text" name="subject" value="{subject}" />

</p>

<p>Message text:

<br /><textarea name="message">{message}</textarea>

</p>

{if attachments}

<p>Attachments:

{attachments}

<br /><input type="checkbox" value="{attachment_id}" name="forward_attachments[]" /> {attachment_name}

{/attachments}

</p>

{/if}

<p><input type="submit" value="send" /></p>

{/exp:messaging:pm_compose}

Example replying to message:


{exp:messaging:pm_compose replying="{segment_3}"}

{if warning}

<div class="warning">{warning}</div>

{/if}

<p>Recipient:

<br /><input type="text" name="recipients" value="{exp:messaging:author message_id="{segment_3}"}" />

</p>

<p>Subject:

<br /><input type="text" name="subject" value="{subject}" />

</p>

<p>Message text:

<br /><textarea name="message">{message}</textarea>

</p>

<p><input type="submit" value="send" /></p>

{/exp:messaging:pm_compose}

↑View messages in folder


<p>Messages in {exp:messaging:folders folder_id="{segment_2}"}{folder_name}{/exp:messaging:folders}</p>

<table class="pm">

<tr>

<th></th>

<th>From</th>

<th>Subject</th>

<th>Date</th>

</tr>

{exp:messaging:private_messages folder_id="{segment_2}" paginate="both" limit="20" form="yes"}

{if no_results}

<tr>

<td class="no_results" colspan="4">No messages here</td>

</tr>

{/if}

{paginate}

<tr>

<td class="pager" colspan="4">{pagination_links}</td>

</tr>

{/paginate}

<tr id="pm_{message_id}">

<td>

<input type="checkbox" name="message_id[]" value="{message_id}" />

</td>

<td>

<a href="{path=member/profile/{sender_member_id}}">{sender_screen_name}</a>

</td>

<td>

<a href="{path=messages/view/{message_id}}" class="{if has_attachment}attach {/if}{if replied}reply {/if}{if forwarded}fwd {/if}{if unread}new {/if}">{subject}</a>

</td>

<td>

{message_date format="%Y-%m-%d"}

</td>

</tr>

{if '{count}'=='20' OR '{absolute_count}'=='{total_results}'}

<tr>

<td colspan="4" class="pm-move">

Move selected messages: {folder_select} <input type="submit" name="move" value="move selected" /> <input type="submit" name="delete" value="delete selected" />

</td>

</tr>

{/if}

{/exp:messaging:private_messages}

</table>

{exp:messaging:private_messages} (or {exp:messaging:pm}, which is the same) tag will display private messages for logged in user.

Tag parameters (all optional):

folder — name of folder, from which you want to display messages. Can be 'inbox', 'sent', 'trash' or name of your custom folder. If folder and folder_id are omited, will display message from Inbox.
folder_id — ID of folder, from which you want to display messages. Number from 0 to 10 (0 - trash, 1 - inbox, 2 - sent, all other are custom folders you can create)
message_id — make the tag work in single-message mode
sort="asc" — sorting order. By default, the latest message is diplayed first. Set this parameter if you want oldest messages to be displayed first.
mark_read="no" — force the message(s) no be NOT marked as read. Note: the message is marked as read when {message} variable is displayed.
form="yes" — if set, creates form for moving/deleting messages around all data displayed and parses {folder_select} variable
return — a page to return after moving message. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the original page.
limit — number of messages per page, if you want to use pagination
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result
ajax="yes" — turn on AJAX mode for moving/deleting form and links. The success or error messages shown upon submit will be shown as simple text, without using message templates.

Conditional variables:

{if no_results}{/if} — displayed if there are no messages available
{if read}{/if} — displayed if message has already been read
{if unread}{/if} — displayed if message has not been read yet
{if replied}{/if} — displayed if user has replied to this message
{if forwarded}{/if} — displayed if user has forwarded this message
{if has_attachments}{/if} — displayed if there are any files attached

Single variables:

total_results — total number of private messages in this folder
count — message counter on each page
absolute_count — message counter throughout all pages
message_id — private message ID
sender_member_id — member ID of person who sent the message
sender_username — username of person who sent the message
sender_screen_name — screen name of person who sent the message
sender_email — email of sender
sender_avatar_url — URL of sender's avatar
sender_photo_url — URL of sender's profile photo
subject — message subject
message — message body text
message_date format="%Y-%m-%d" — the date when message has been sent. Standard EE date formatting rules apply.
delete_url — URL for message deleting
delete_link — pre-formatted link to delete message
empty_trash_url — URL to empty Trash folder (visible only in Trash folder view)
empty_trash_link — pre-formatted link to empty Trash folder (visible only in Trash folder view)
folder_select — pre-formatted dropdown select for folders that the message can be moved to. Displayed only if form="yes" parameter is specified.
{paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page). You can also use {pagination_links} tag pair, like with channel entries pagination.

Variable pairs:

{attachments backspace="X"}{/attachments} — used to display list of files attached with the message.

attachment_id — attachment ID (used as value for input)
attachment_name — file name
attachment_size — file size
attachment_extension — file extension
download_url — URL for downloading the file

{recipients backspace="X"}{/recipients} — used to display list of recipients for this message

recipient_member_id — member ID of PM recipient
recipient_username — username of PM recipient
recipient_screen_name — screen name of PM recipient
recipient_email — email of recipient
recipient_avatar_url — URL of recipient's avatar
recipient_photo_url — URL of recipient's profile photo
recipient_count — counter for recipients loop
total_recipients — total number of recipients

{cc backspace="X"}{/cc} — used to display list of copy recipients for this message

recipient_member_id — member ID of PM copy recipient
recipient_username — username of PM copy recipient
recipient_screen_name — screen name of PM copy recipient
recipient_email — email of recipient
recipient_avatar_url — URL of recipient's avatar
recipient_photo_url — URL of recipient's profile photo
recipient_count — counter for recipients loop
total_cc — total number of copies

backspace parameter is optional and lets you remove X last characters from the output.

↑View messages list grouped by conversation

{exp:messaging:conversations} tag lets you display list of messages grouped by conversation (sender/recipient pair and subject). Similar to Facebook- or Gmail- style.


{exp:messaging:conversations combined="yes" limit="25" paginate="both"}



{paginate}

{pagination_links}

<ul>

        {first_page}

                <li><a href="{pagination_url}" class="page-first">First Page</a></li>

        {/first_page}



        {previous_page}

                <li><a href="{pagination_url}" class="page-previous">Previous Page</a></li>

        {/previous_page}



        {page}

                <li><a href="{pagination_url}" class="page-{pagination_page_number} {if current_page}active{/if}">{pagination_page_number}</a></li>

        {/page}



        {next_page}

                <li><a href="{pagination_url}" class="page-next">Next Page</a></li>

        {/next_page}



        {last_page}

                <li><a href="{pagination_url}" class="page-last">Last Page</a></li>

        {/last_page}

</ul>

{/pagination_links}

{/paginate} 



<p>{conversation_count}. <strong>{subject}</strong> - {last_message_date format="%Y-%m-%d"} - from {last_sender_screen_name} ({last_sender_username}) - to {last_recipient_screen_name} ({last_recipient_username}) ({messages_in_conversation} messages in conversation)



{conversation}

<br />

{count}. #{message_id} sent from {sender_screen_name} ({sender_username}) to {recipient_screen_name} ({recipient_username}) on {message_date format="%Y-%m-%d"}

{/conversation}

</p>



{/exp:messaging:conversations}

Tag parameters:

combined="yes" — display messages from all folders (except Trash) combined. 'folder' and 'folder_id' parmeters will be ignored
folder — name of folder, from which you want to display messages. Can be 'inbox', 'sent', 'trash' or name of your custom folder. If folder and folder_id are omited, will display message from Inbox.
folder_id — ID of folder, from which you want to display messages. Number from 0 to 10 (0 - trash, 1 - inbox, 2 - sent, all other are custom folders you can create)
limit — number of messages per page, if you want to use pagination
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result

Single variables:

conversation_total_results — total number of conversations
conversation_count — conversations counter on each page
conversation_absolute_count — conversations counter throughout all pages
messages_in_conversation — number of messages in conversation
last_message_id — ID of last message in conversation
last_sender_member_id — member ID of person who has sent the last message in conversation
last_sender_username — username of person who has sent the last message in conversation
last_sender_screen_name — screen name of person who has sent the last message in conversation
last_sender_email — email of last sender
last_sender_avatar_url — URL of last sender's avatar
last_sender_photo_url — URL of last sender's profile photo
last_recipient_member_id — member ID of person who received the last message in conversation
last_recipient_username — username of person who received the last message in conversation
last_recipient_screen_name — screen name of person who received the last message in conversation
last_recipient_email — email of last recipient
last_recipient_avatar_url — URL of last recipient's avatar
last_recipient_photo_url — URL of last recipient's profile photo
subject — messages subject
last_message_date format="%Y-%m-%d" — the date when last message in conversation has been sent. Standard EE date formatting rules apply.
{paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page). You can also use {pagination_links} tag pair, like with channel entries pagination.

{conversation backspace="X"}{/conversation} variables pair is used to display individual messages inside conversation.

Inside {conversation} variables pair, following are available:
conditionals:

{if read}{/if} — displayed if message has already been read
{if unread}{/if} — displayed if message has not been read yet
{if replied}{/if} — displayed if user has replied to this message
{if forwarded}{/if} — displayed if user has forwarded this message
{if has_attachments}{/if} — displayed if there are any files attached

single variables:

count — message counter in current conversation
message_id — private message ID
sender_member_id — member ID of person who sent the message
sender_username — username of person who sent the message
sender_screen_name — screen name of person who sent the message
sender_email — email of sender
sender_avatar_url — URL of sender's avatar
sender_photo_url — URL of sender's profile photo
recipient_member_id — member ID of message recipient
recipient_username — username of message recipient
recipient_screen_name — screen name of message recipient
recipient_email — email of message recipient
recipient_avatar_url — URL of message recipient's avatar
recipient_photo_url — URL of message recipient's profile photo
message — message body text
message_date format="%Y-%m-%d" — the date when message has been sent. Standard EE date formatting rules apply.

↑View messages in conversation mode

{exp:messaging:pm_thread} tag lets you display messages as thread or conversation. Is displays complete conversation thread between pair of recipient and sender (identified by subject).


{exp:messaging:pm_thread message_id="{segment_3}" backspace="6"}

{if "{count}"=="1"}<p><strong>{subject}</strong></p>{/if}

<p>From: <a href="{path=member/profile/{sender_member_id}}">{sender_screen_name}</a></p>

<p>To: {recipients backspace="1"}<a href="{path=member/profile/{recipient_member_id}}">{recipient_screen_name}</a>, {/recipients}</p>

<p>Sent on: {message_date format="%Y-%m-%d"}</p>

<div class="message" {if current_message} style="font-weight: bold"{/if}>{message}</div>

<hr />

{/exp:messaging:pm_thread}

Tag parameters:

message_id — ID of any message that is part of this conversation thread. Required
sort="asc" — sorting order. By default, the latest message is diplayed first. Set this parameter if you want oldest messages to be displayed first.
limit — number of bulletins per page (if you have many messages and want to use pagination)
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result
form="yes" — if set, creates form for moving/deleting messages around all data displayed and parses {folder_select} variable
ajax="yes" — turn on AJAX mode for moving/deleting form and links. The success or error messages shown upon submit will be shown as simple text, without using message templates.

All variables presented by {exp:messaging:private_messages} are available with this tag as well. Additionally, following conditional can be used:

{if current_message}{/if} — idenifies current (selected) message

↑View PM

To display particular message, you'll need to use same {exp:messaging:private_messages} tag, but with member_id parameter set.


{exp:messaging:private_messages message_id="{segment_3}"}

<p>From: <a href="{path=member/profile/{sender_member_id}}">{sender_screen_name}</a></p>

<p>To: {recipients backspace="1"}<a href="{path=member/profile/{recipient_member_id}}">{recipient_screen_name}</a>, {/recipients}</p>

<p>Sent on: {message_date format="%Y-%m-%d"}</p>

<p><strong>{subject}</strong></p>

<div class="message">{message}</div>

{if has_attachments}

<div class="att">

{attachments}

<a href="{download_url}">{attachment_name}</a> ({attachment_size})<br />

{/attachments}

</div>

{/if}

<p><a href="{path=messages/reply/{message_id}}">Reply</a> - <a href="{path=messages/forward/{message_id}}">Forward</a> - <a href="{delete_url}">Delete</a></p>

{/exp:messaging:private_messages}

↑Moving and deleting messages

To be able to move message to different folder, call {exp:messaging:private_messages} with form="yes" parameter. Then, you'll have {folder_select} variable containing dropdown select of available folders. ID of messages that should be moved should be in inpus (usually checkboxes) named message_id[]. If the submitted form will contain input named 'delete' the message(s) will be deleted instead (moved to Trash, or deleted permanently if they're in Trash already).

You can also delete message by clicking {delete_url} generated by same tag for each message.

↑Message author


{exp:messaging:author message_id="{segment_3}"}

{exp:messaging:author} will return sender's screen name for message defined by message_id parameter.

↑Message recipients


{exp:messaging:recipients message_id="{segment_3}"}

{exp:messaging:recipients} will return comma-separated list of recipient screen names for message defined by message_id parameter.

↑Message folders list


<ul>

{exp:messaging:folders}

<li><a href="{path=messages/folder/{folder_id}}">{folder_name}</a> ({messages_count})</li>

{/exp:messaging:folders}

</ul>

{exp:messaging:folders} tag is used to display list of user's PM folders (and also for folders editing, see below).

Tag parameters:

folder_id — provide folder ID if you want to limit output to certain folder (e.g. display folder name)
folder — provide folder's name instead of ID to limit output
exclude_trash="yes" — do not include 'Trash' folder in list (useful for editing, as it's name cannot be changed)
show_new="one" or show_new="all" — define how many "new" folders you want to show (for folders creation) - one or all available (used for folders editing).

Single variables:

folder_id — ID of folder
folder_name — name of folder
messages_count — number of messages in folder
unread_count — number of unread messages in folder

↑Editing folders


{exp:messaging:edit_folders}

{exp:messaging:folders show_new="one"}

<p><input name="folder{folder_id}" value="{folder_name}" /></p>

{/exp:messaging:folders}

<p><input type="submit" value="save" /></p>

{/exp:messaging:edit_folders}

Folders editing is done by combining {exp:messaging:edit_folders} and {exp:messaging:folders} tags

In ExpressionEngine, the users are able to create 8 custom folders (plus built-in Trash, Inbox and Sent). You can also give your own names to Inbox and Sent. In order to delete folder, submit the form with it's name empty. If folder has been deleted, all messages in it will be moved to Trash.

Tag parameters:

return — a page to return after sending message. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display form.
ajax="yes" — turn on AJAX mode. The success or error messages shown upon submission will be shown as simple text, without using message templates. The "return" parameter will not be functional if you supply this parameter.
id — form ID (defaults to 'messaging_form')
class — form class (defaults to 'messaging_form')
name — form name (defaults to 'messaging_form')

Form fields:

folderX — with X being numbers from 1 to 10, this field is used for saving folder names

↑Member's general PM info


{exp:messaging:info}

You have {messages_total} stored out of {messages_limit} allowed ({messages_percent}%)

{/exp:messaging:info}

Single variables:

messages_total — total messages stored for member
messages_unread — number of unread messages
messages_limit — limit of messages member can store
messages_percent — percent showing how full are member's folders
send_limit — number of PM member is allowed to send daily
max_chars — maximum chracters PM can contain
attach_maxsize — maximum size of attached file, KB
attach_total — maximum size of all attachments, MB
max_attachments — maximum number of files that can be attached to message

↑Member lists

↑Buddies list


<ul>

{exp:messaging:buddies}

<li><a href="{path=member/profile/{member_id}}">{screen_name}</a> ({remove_link})</li>

{/exp:messaging:buddies}

</ul>

{exp:messaging:buddies} will display list of buddies for logged in person.

Tag parameters (all optional):

buddy_id — if you want to check whether certain member has been added as buddy, set this parameter to his member_id
ajax="yes" — turn on AJAX mode for remove_link. The success or error messages shown upon clicking remove_link will be shown as simple text, without using message templates.
return — a page to return after removing user from list. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the original page.
limit — number of records per page, if you want to use pagination
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result

Single variables:

member_id — buddy member ID
username — buddy username
screen_name — buddy screen name
and other variables that have their values stored in exp_members database table for each buddy
remove_link — pre-formatted link to delete member from list
remove_url — link URL to delete member from list
count — rows counter
absolute_count — rows counter throughout all pages
{paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page). You can also use {pagination_links} tag pair, like with channel entries pagination.

All single variables are also available with buddy_ prefix (buddy_member_id, buddy_username, etc.) that can be used if you run into variable naming conflicts.

↑Blocked list


<ul>

{exp:messaging:blocked}

<li><a href="{path=member/profile/{member_id}}">{screen_name}</a> ({remove_link})</li>

{/exp:messaging:blocked}

</ul>

{exp:messaging:blocked} will display list of members blocked/ignored by logged in person.

Tag parameters (all optional):

buddy_id — if you want to check whether certain member has been listed as blocked, set this parameter to his member_id
ajax="yes" — turn on AJAX mode for remove_link. The success or error messages shown upon clicking remove_link will be shown as simple text, without using message templates.
limit — number of records per page, if you want to use pagination
paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
backspace="X" — remove X last characters from tag output result

Single variables:

member_id — blocked member ID
username — blocked username
screen_name — blocked screen name
and other variables that have their values stored in exp_members database table for each blocked user
remove_link — pre-formatted link to delete member from list
remove_url — link URL to delete member from list
count — rows counter
absolute_count — rows counter throughout all pages
{paginate}{pagination_links}{/paginate} — pagination links (if you have limit parameter set and there's more than one page). You can also use {pagination_links} tag pair, like with channel entries pagination.

All single variables are also available with buddy_ prefix (buddy_member_id, buddy_username, etc.) that can be used if you run into variable naming conflicts.

↑Adding to list


<ul>

{exp:query sql="SELECT * FROM exp_members WHERE group_id=5"}

<li><a href="{path=member/profile/{member_id}}">{screen_name}</a> (<a href="{exp:messaging:add_to_buddies_link url_only="yes" member_id="{member_id}"}">Follow</a>)</li>

{/exp:query}

</ul>

Use {exp:messaging:add_to_buddies_link}tag to display link that would allow to add person to buddies list; {exp:messaging:add_to_blocked_link} - for adding to blocked list.

Tag parameters (all optional):

ajax="yes" — turn on AJAX mode for link. The success or error messages shown upon clicking link will be shown as simple text, without using message templates.
return — a page to return after adding user to list. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the original page.
url_only="yes" — display only the actual URL. By default will display pre-formatted link.

↑Removing from list

The links for removing person from buddies/blocked list can be displayed using {remove_link} variable in {exp:messaging:buddies} and {exp:messaging:blocked}

↑Check buddy/blocked state


<ul>

{exp:messaging:check_buddy_state member_id="{member_id}"}

{if blocked}Blocked - {remove_link}{/if}<br />

{if buddy}Followed - {remove_link}{/if}<br />

{/exp:messaging:check_buddy_state}

</ul>

{exp:messaging:check_buddy_state} allows you to check whether certain user has been added to buddies/blocked list by logged in person.

Tag parameters:

member_id — the ID of member to check. Required
ajax="yes" — turn on AJAX mode for remove_link. The success or error messages shown upon clicking remove_link will be shown as simple text, without using message templates.
return — a page to return after removing from list. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display link.
skip_success_message="yes" — force redirect to return page without showing success message.

Single variables:

remove_link — pre-formatted link to delete member from list
remove_url — link URL to delete member from list

Conditional variables:

if blocked — displayed if user is in blocked list
if buddy — displayed if user is in buddies list

↑ Extension hooks

The module contain several extension hooks, that allow triggering of custom extensions upon certain event.

messaging_bulletin_sent

Triggered after bulletin has been sent.

Parameters:
— (string) $bulletin_message - bulletin message text; — (array) $recipients - recipient user groups

messaging_pm_sent

Triggered after PM has been sent, but before email notification goes out.

Parameters:
— (array) $data - message data; — (array) $recipients - recipients; — (array) $cc - carbon copy recipients;

messaging_member_listed

Triggered after user adds someone to buddies/blocked list.

Parameters:
— (int) $member_id - ID of member that performs the action (adds to the list); — (int) $listed_member - ID of member added to the list; — (string) $type - list type (buddy/blocked);

intoEEtive.com

Messaging

↑ Basic concepts

↑Bulletins

↑Compose Bulletin

↑View Bulletins

↑Private Messages

↑Compose PM

↑View messages in folder

↑View messages list grouped by conversation

↑View messages in conversation mode

↑View PM

↑Moving and deleting messages

↑Message author

↑Message recipients

↑Message folders list

↑Editing folders

↑Member's general PM info

↑Member lists

↑Buddies list

↑Blocked list

↑Adding to list

↑Removing from list

↑Check buddy/blocked state

↑ Extension hooks

messaging_bulletin_sent

messaging_pm_sent

messaging_member_listed