Types of recipients

  1. 7-1 privatemsg.api.php types
  2. 7-2 privatemsg.api.php types
  3. 6-2 privatemsg.api.php types

It is possible to define other types of recipients than the usual single user. These types are defined through a hook and a few callbacks and are stored in the {pm_index} table for each recipient entry.

Because of that, only the combination of type and recipient (was uid in older versions) defines a unique recipient.

This feature is usually used to define groups of recipients. Privatemsg comes with the privatemsg_roles sub-module, which allows to send messages to all members of a specific group.

When sending a new message with a recipient type other than user, Privatemsg only inserts a single entry for that recipient type. However, when looking for messages for a user, Privatemsg only looks for recipient types user and hidden. To fill the gap, Privatemsg defines three ways how a non-user type is converted to hidden recipient entries.

  • For small recipient types (by default <100 recipients, configurable), the entries are added directly after saving the original private message.
  • When sending messages through the UI, bigger recipient types are handled with batch API.
  • For messages sent by the API, the hidden recipients are generated during cron runs.

Once all hidden recipients are added, the original recipient type is marked as read so Privatemsg knows that he has been processed.

Privatemsg defines the following types:

  • user: This is the default recipient type which is used for a single user.
  • hidden: Used to add internal recipient entries for other recipient types.
  • role: The sub-module privatemsg_roles defines an additional type called role. This allows to send messages to all members of a role.

To implement a new type, the following hooks need to be implemented. Note that most of these hooks can also be used alone for other functionality than defining recipient types.

Additionally, there is also a hook_privatemsg_recipient_type_info_alter() that allows to alter recipient type definitions.


./privatemsg.api.php, line 425
Privatemsg API Documentation


Namesort ascending Location Description
privatemsg_recipient_key ./privatemsg.module Return key for a recipient object used for arrays.
privatemsg_recipient_get_types ./privatemsg.module Returns an array of defined recipient types.
privatemsg_recipient_get_type ./privatemsg.module Return a single recipient type information.
privatemsg_recipient_access ./privatemsg.module This function is used to test if the current user has write/view access for a specific recipient type.
hook_privatemsg_recipient_type_info_alter ./privatemsg.api.php Allows to alter the defined recipient types.
hook_privatemsg_recipient_type_info ./privatemsg.api.php This hook is used to tell privatemsg about the recipient types defined by a module. Each type consists of an array keyed by the internal recipient type name and the following keys must be defined.
hook_privatemsg_operation_executed ./privatemsg.api.php Allows response to a successful operation.
hook_privatemsg_name_lookup_matches ./privatemsg.api.php Allows to alter found recipient types for a given string.
hook_privatemsg_name_lookup ./privatemsg.api.php Hook which allows to look up a user object.
hook_privatemsg_autocomplete_alter ./privatemsg.api.php Allows to alter the found autocomplete suggestions.