Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 9 May 2022 (12 months).
  • Bug fixes for security issues in 3.11.x will end 14 November 2022 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 310 and 311] [Versions 35 and 311] [Versions 36 and 311] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

    Contains class used to return information to display for the message area.

    Copyright: 2016 Mark Nelson <markn@moodle.com>
    License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
    File Size: 3101 lines (134 kb)
    Included or required:0 times
    Referenced: 0 times
    Includes or requires: 0 files

    Defines 1 class

    api:: (87 methods):
      search_messages()
      search_users_in_course()
      search_users()
      message_search_users()
      get_linked_conversation_extra_fields()
      get_conversations()
      get_conversations_between_users()
      get_conversation()
      set_favourite_conversation()
      unset_favourite_conversation()
      get_contacts()
      get_user_contacts()
      count_contacts()
      get_contacts_with_unread_message_count()
      get_non_contacts_with_unread_message_count()
      get_messages()
      get_conversation_messages()
      get_most_recent_message()
      get_most_recent_conversation_message()
      get_profile()
      can_delete_conversation()
      delete_conversation()
      delete_conversation_by_id()
      count_unread_conversations()
      can_mark_all_messages_as_read()
      get_conversation_counts()
      mark_all_messages_as_read()
      mark_all_notifications_as_read()
      mark_all_read_for_user()
      get_all_message_preferences()
      count_blocked_users()
      can_post_message()
      can_send_message()
      can_send_message_to_conversation()
      send_message_to_conversation()
      get_user_privacy_messaging_preference()
      is_user_non_contact_blocked()
      is_user_blocked()
      get_message_processor()
      is_processor_enabled()
      update_processor_status()
      get_processed_processor_object()
      get_blocked_users()
      mark_message_as_read()
      mark_notification_as_read()
      can_delete_message()
      delete_message()
      get_conversation_between_users()
      get_individual_conversations_between_users()
      get_self_conversation()
      create_conversation_between_users()
      create_conversation()
      can_create_group_conversation()
      can_create_contact()
      create_contact_request()
      confirm_contact_request()
      decline_contact_request()
      get_contact_requests()
      get_received_contact_requests_count()
      add_contact()
      remove_contact()
      block_user()
      unblock_user()
      is_contact()
      get_contact()
      is_blocked()
      get_contact_requests_between_users()
      does_contact_request_exist()
      is_user_in_conversation()
      can_contact_user()
      add_members_to_conversation()
      remove_members_from_conversation()
      count_conversation_members()
      is_conversation_area_enabled()
      get_conversation_by_area()
      enable_conversation()
      disable_conversation()
      update_conversation_name()
      get_conversation_members()
      get_unread_conversation_counts()
      mute_conversation()
      unmute_conversation()
      is_conversation_muted()
      delete_all_conversation_data()
      can_delete_message_for_all_users()
      delete_message_for_all_users()
      lazy_create_self_conversation()


    Class: api  - X-Ref

    Class used to return information to display for the message area.

    search_messages($userid, $search, $limitfrom = 0, $limitnum = 0)   X-Ref
    Handles searching for messages in the message area.

    return: array
    param: int $userid The user id doing the searching
    param: string $search The string the user is searching
    param: int $limitfrom
    param: int $limitnum

    search_users_in_course()   X-Ref


    search_users()   X-Ref


    message_search_users(int $userid, string $search, int $limitfrom = 0, int $limitnum = 20)   X-Ref
    Handles searching for user.

    return: array
    param: int $userid The user id doing the searching
    param: string $search The string the user is searching
    param: int $limitfrom
    param: int $limitnum

    get_linked_conversation_extra_fields(array $conversations)   X-Ref
    Gets extra fields, like image url and subname for any conversations linked to components.

    The subname is like a subtitle for the conversation, to compliment it's name.
    The imageurl is the location of the image for the conversation, as might be seen on a listing of conversations for a user.

    return: array the array of subnames, index by conversation id.
    param: array $conversations a list of conversations records.

    get_conversations($userid, $limitfrom = 0, $limitnum = 20, int $type = null,bool $favourites = null, bool $mergeself = false)   X-Ref
    Returns the contacts and their conversation to display in the contacts area.

    ** WARNING **
    It is HIGHLY recommended to use a sensible limit when calling this function. Trying
    to retrieve too much information in a single call will cause performance problems.
    ** WARNING **

    This function has specifically been altered to break each of the data sets it
    requires into separate database calls. This is to avoid the performance problems
    observed when attempting to join large data sets (e.g. the message tables and
    the user table).

    While it is possible to gather the data in a single query, and it may even be
    more efficient with a correctly tuned database, we have opted to trade off some of
    the benefits of a single query in order to ensure this function will work on
    most databases with default tunings and with large data sets.

    return: array the array of conversations
    param: int $userid The user id
    param: int $limitfrom
    param: int $limitnum
    param: int $type the type of the conversation, if you wish to filter to a certain type (see api constants).
    param: bool $favourites whether to include NO favourites (false) or ONLY favourites (true), or null to ignore this setting.
    param: bool $mergeself whether to include self-conversations (true) or ONLY private conversations (false)

    get_conversations_between_users(int $userid1, int $userid2,int $limitfrom = 0, int $limitnum = 20)   X-Ref
    Returns all conversations between two users

    return: array
    param: int $userid1 One of the user's id
    param: int $userid2 The other user's id
    param: int $limitfrom
    param: int $limitnum

    get_conversation(int $userid,int $conversationid,bool $includecontactrequests = false,bool $includeprivacyinfo = false,int $memberlimit = 0,int $memberoffset = 0,int $messagelimit = 0,int $messageoffset = 0,bool $newestmessagesfirst = true)   X-Ref
    Return a conversation.

    return: \stdClass
    param: int $userid The user id to get the conversation for
    param: int $conversationid The id of the conversation to fetch
    param: bool $includecontactrequests Should contact requests be included between members
    param: bool $includeprivacyinfo Should privacy info be included between members
    param: int $memberlimit Limit number of members to load
    param: int $memberoffset Offset members by this amount
    param: int $messagelimit Limit number of messages to load
    param: int $messageoffset Offset the messages
    param: bool $newestmessagesfirst Order messages by newest first

    set_favourite_conversation(int $conversationid, int $userid)   X-Ref
    Mark a conversation as a favourite for the given user.

    return: favourite the favourite object.
    param: int $conversationid the id of the conversation to mark as a favourite.
    param: int $userid the id of the user to whom the favourite belongs.

    unset_favourite_conversation(int $conversationid, int $userid)   X-Ref
    Unset a conversation as a favourite for the given user.

    param: int $conversationid the id of the conversation to unset as a favourite.
    param: int $userid the id to whom the favourite belongs.

    get_contacts()   X-Ref


    get_user_contacts(int $userid, int $limitfrom = 0, int $limitnum = 0)   X-Ref
    Get the contacts for a given user.

    return: array An array of contacts
    param: int $userid
    param: int $limitfrom
    param: int $limitnum

    count_contacts(int $userid)   X-Ref
    Returns the contacts count.

    return: array
    param: int $userid The user id

    get_contacts_with_unread_message_count($userid, $limitfrom = 0, $limitnum = 0)   X-Ref
    Returns the an array of the users the given user is in a conversation
    with who are a contact and the number of unread messages.

    return: array
    param: int $userid The user id
    param: int $limitfrom
    param: int $limitnum

    get_non_contacts_with_unread_message_count($userid, $limitfrom = 0, $limitnum = 0)   X-Ref
    Returns the an array of the users the given user is in a conversation
    with who are not a contact and the number of unread messages.

    return: array
    param: int $userid The user id
    param: int $limitfrom
    param: int $limitnum

    get_messages()   X-Ref


    get_conversation_messages(int $userid, int $convid, int $limitfrom = 0, int $limitnum = 0,string $sort = 'timecreated ASC', int $timefrom = 0, int $timeto = 0)   X-Ref
    Returns the messages for the defined conversation.

    return: array of messages
    param: int $userid The current user.
    param: int $convid The conversation where the messages belong. Could be an object or just the id.
    param: int $limitfrom Return a subset of records, starting at this point (optional).
    param: int $limitnum Return a subset comprising this many records in total (optional, required if $limitfrom is set).
    param: string $sort The column name to order by including optionally direction.
    param: int $timefrom The time from the message being sent.
    param: int $timeto The time up until the message being sent.

    get_most_recent_message()   X-Ref


    get_most_recent_conversation_message(int $convid, int $currentuserid = 0)   X-Ref
    Returns the most recent message in a conversation.

    return: \stdClass|null The most recent message.
    param: int $convid The conversation identifier.
    param: int $currentuserid The current user identifier.

    get_profile()   X-Ref


    can_delete_conversation(int $userid, int $conversationid = null)   X-Ref
    Checks if a user can delete messages they have either received or sent.

    return: bool Returns true if a user can delete the conversation, false otherwise.
    param: int $userid The user id of who we want to delete the messages for (this may be done by the admin
    param: int $conversationid The id of the conversation

    delete_conversation()   X-Ref


    delete_conversation_by_id(int $userid, int $conversationid)   X-Ref
    Deletes a conversation for a specified user.

    This function does not verify any permissions.

    param: int $userid The user id of who we want to delete the messages for (this may be done by the admin
    param: int $conversationid The id of the other user in the conversation

    count_unread_conversations($user = null)   X-Ref
    Returns the count of unread conversations (collection of messages from a single user) for
    the given user.

    return: int the count of the user's unread conversations
    param: \stdClass $user the user who's conversations should be counted

    can_mark_all_messages_as_read(int $userid, int $conversationid)   X-Ref
    Checks if a user can mark all messages as read.

    return: bool true if user is permitted, false otherwise
    param: int $userid The user id of who we want to mark the messages for
    param: int $conversationid The id of the conversation

    get_conversation_counts(int $userid)   X-Ref
    Returns the count of conversations (collection of messages from a single user) for
    the given user.

    return: array the array of conversations counts, indexed by type.
    param: int $userid The user whose conversations should be counted.

    mark_all_messages_as_read($userid, $conversationid = null)   X-Ref
    Marks all messages being sent to a user in a particular conversation.

    If $conversationdid is null then it marks all messages as read sent to $userid.

    param: int $userid
    param: int|null $conversationid The conversation the messages belong to mark as read, if null mark all

    mark_all_notifications_as_read($touserid, $fromuserid = null, $timecreatedto = null)   X-Ref
    Marks all notifications being sent from one user to another user as read.

    If the from user is null then it marks all notifications as read sent to the to user.

    return: void
    param: int $touserid the id of the message recipient
    param: int|null $fromuserid the id of the message sender, null if all messages
    param: int|null $timecreatedto mark notifications created before this time as read

    mark_all_read_for_user()   X-Ref


    get_all_message_preferences($processors, $providers, $user)   X-Ref
    Returns message preferences.

    return: \stdClass
    param: array $processors
    param: array $providers
    param: \stdClass $user

    count_blocked_users($user = null)   X-Ref
    Count the number of users blocked by a user.

    return: int the number of blocked users
    param: \stdClass $user The user object

    can_post_message($recipient, $sender = null)   X-Ref
    Determines if a user is permitted to send another user a private message.
    If no sender is provided then it defaults to the logged in user.

    return: bool true if user is permitted, false otherwise.
    param: \stdClass $recipient The user object.
    param: \stdClass|null $sender The user object.

    can_send_message(int $recipientid, int $senderid, bool $evenifblocked = false)   X-Ref
    Determines if a user is permitted to send another user a private message.

    return: bool true if user is permitted, false otherwise.
    param: int $recipientid The recipient user id.
    param: int $senderid The sender user id.
    param: bool $evenifblocked This lets the user know, that even if the recipient has blocked the user

    can_send_message_to_conversation(int $userid, int $conversationid)   X-Ref
    Determines if a user is permitted to send a message to a given conversation.
    If no sender is provided then it defaults to the logged in user.

    return: bool true if the user can send a message to the conversation, false otherwise.
    param: int $userid the id of the user on which the checks will be applied.
    param: int $conversationid the id of the conversation we wish to check.

    send_message_to_conversation(int $userid, int $conversationid, string $message,int $format)   X-Ref
    Send a message from a user to a conversation.

    This method will create the basic eventdata and delegate to message creation to message_send.
    The message_send() method is responsible for event data that is specific to each recipient.

    return: \stdClass the message created.
    param: int $userid the sender id.
    param: int $conversationid the conversation id.
    param: string $message the message to send.
    param: int $format the format of the message to send.

    get_user_privacy_messaging_preference(int $userid)   X-Ref
    Get the messaging preference for a user.
    If the user has not any messaging privacy preference:
    - When $CFG->messagingallusers = false the default user preference is MESSAGE_PRIVACY_COURSEMEMBER.
    - When $CFG->messagingallusers = true the default user preference is MESSAGE_PRIVACY_SITE.

    return: int    The default messaging preference.
    param: int    $userid The user identifier.

    is_user_non_contact_blocked()   X-Ref


    is_user_blocked()   X-Ref


    get_message_processor($name, $ready = false)   X-Ref
    Get specified message processor, validate corresponding plugin existence and
    system configuration.

    return: mixed $processor if processor present else empty array.
    param: string $name  Name of the processor.
    param: bool $ready only return ready-to-use processors.

    is_processor_enabled($name)   X-Ref
    Returns weather a given processor is enabled or not.
    Note:- This doesn't check if the processor is configured or not.

    return: bool
    param: string $name Name of the processor

    update_processor_status($processor, $enabled)   X-Ref
    Set status of a processor.

    return: bool
    param: \stdClass $processor processor record.
    param: 0|1 $enabled 0 or 1 to set the processor status.

    get_processed_processor_object(\stdClass $processor)   X-Ref
    Given a processor object, loads information about it's settings and configurations.
    This is not a public api, instead use @see \core_message\api::get_message_processor()
    or @see \get_message_processors()

    return: \stdClass processed processor object
    param: \stdClass $processor processor object

    get_blocked_users($userid)   X-Ref
    Retrieve users blocked by $user1

    return: array the users blocked
    param: int $userid The user id of the user whos blocked users we are returning

    mark_message_as_read($userid, $message, $timeread = null)   X-Ref
    Mark a single message as read.

    param: int $userid The user id who marked the message as read
    param: \stdClass $message The message
    param: int|null $timeread The time the message was marked as read, if null will default to time()

    mark_notification_as_read($notification, $timeread = null)   X-Ref
    Mark a single notification as read.

    param: \stdClass $notification The notification
    param: int|null $timeread The time the message was marked as read, if null will default to time()

    can_delete_message($userid, $messageid)   X-Ref
    Checks if a user can delete a message.

    return: bool Returns true if a user can delete the message, false otherwise.
    param: int $userid the user id of who we want to delete the message for (this may be done by the admin
    param: int $messageid The message id

    delete_message($userid, $messageid)   X-Ref
    Deletes a message.

    This function does not verify any permissions.

    return: bool
    param: int $userid the user id of who we want to delete the message for (this may be done by the admin
    param: int $messageid The message id

    get_conversation_between_users(array $userids)   X-Ref
    Returns the conversation between two users.

    return: int|bool The id of the conversation, false if not found
    param: array $userids

    get_individual_conversations_between_users(array $useridsets)   X-Ref
    Returns the conversations between sets of users.

    The returned array of results will be in the same order as the requested
    arguments, null will be returned if there is no conversation for that user
    pair.

    For example:
    If we have 6 users with ids 1, 2, 3, 4, 5, 6 where only 2 conversations
    exist. One between 1 and 2 and another between 5 and 6.

    Then if we call:
    $conversations = get_individual_conversations_between_users([[1,2], [3,4], [5,6]]);

    The conversations array will look like:
    [<conv_record>, null, <conv_record>];

    Where null is returned for the pairing of [3, 4] since no record exists.

    return: stdClass[] Array of conversation records
    param: array $useridsets An array of arrays where the inner array is the set of user ids

    get_self_conversation(int $userid)   X-Ref
    Returns the self conversation for a user.

    return: \stdClass|false The self-conversation object or false if it doesn't exist
    param: int $userid The user id to get the self-conversations

    create_conversation_between_users()   X-Ref


    create_conversation(int $type, array $userids, string $name = null,int $enabled = self::MESSAGE_CONVERSATION_ENABLED, string $component = null,string $itemtype = null, int $itemid = null, int $contextid = null)   X-Ref
    Creates a conversation with selected users and messages.

    return: \stdClass
    param: int $type The type of conversation
    param: int[] $userids The array of users to add to the conversation
    param: string|null $name The name of the conversation
    param: int $enabled Determines if the conversation is created enabled or disabled
    param: string|null $component Defines the Moodle component which the conversation belongs to, if any
    param: string|null $itemtype Defines the type of the component
    param: int|null $itemid The id of the component
    param: int|null $contextid The id of the context

    can_create_group_conversation(int $userid, \context $context)   X-Ref
    Checks if a user can create a group conversation.

    return: bool
    param: int $userid The id of the user attempting to create the conversation
    param: \context $context The context they are creating the conversation from, most likely course context

    can_create_contact(int $userid, int $requesteduserid)   X-Ref
    Checks if a user can create a contact request.

    return: bool
    param: int $userid The id of the user who is creating the contact request
    param: int $requesteduserid The id of the user being requested

    create_contact_request(int $userid, int $requesteduserid)   X-Ref
    Handles creating a contact request.

    return: \stdClass the request
    param: int $userid The id of the user who is creating the contact request
    param: int $requesteduserid The id of the user being requested

    confirm_contact_request(int $userid, int $requesteduserid)   X-Ref
    Handles confirming a contact request.

    param: int $userid The id of the user who created the contact request
    param: int $requesteduserid The id of the user confirming the request

    decline_contact_request(int $userid, int $requesteduserid)   X-Ref
    Handles declining a contact request.

    param: int $userid The id of the user who created the contact request
    param: int $requesteduserid The id of the user declining the request

    get_contact_requests(int $userid, int $limitfrom = 0, int $limitnum = 0)   X-Ref
    Handles returning the contact requests for a user.

    This also includes the user data necessary to display information
    about the user.

    It will not include blocked users.

    return: array The list of contact requests
    param: int $userid
    param: int $limitfrom
    param: int $limitnum

    get_received_contact_requests_count(int $userid)   X-Ref
    Returns the number of contact requests the user has received.

    return: int The count
    param: int $userid The ID of the user we want to return the number of received contact requests for

    add_contact(int $userid, int $contactid)   X-Ref
    Handles adding a contact.

    param: int $userid The id of the user who requested to be a contact
    param: int $contactid The id of the contact

    remove_contact(int $userid, int $contactid)   X-Ref
    Handles removing a contact.

    param: int $userid The id of the user who is removing a user as a contact
    param: int $contactid The id of the user to be removed as a contact

    block_user(int $userid, int $usertoblockid)   X-Ref
    Handles blocking a user.

    param: int $userid The id of the user who is blocking
    param: int $usertoblockid The id of the user being blocked

    unblock_user(int $userid, int $usertounblockid)   X-Ref
    Handles unblocking a user.

    param: int $userid The id of the user who is unblocking
    param: int $usertounblockid The id of the user being unblocked

    is_contact(int $userid, int $contactid)   X-Ref
    Checks if users are already contacts.

    return: bool Returns true if they are a contact, false otherwise
    param: int $userid The id of one of the users
    param: int $contactid The id of the other user

    get_contact(int $userid, int $contactid)   X-Ref
    Returns the row in the database table message_contacts that represents the contact between two people.

    return: mixed A fieldset object containing the record, false otherwise
    param: int $userid The id of one of the users
    param: int $contactid The id of the other user

    is_blocked(int $userid, int $blockeduserid)   X-Ref
    Checks if a user is already blocked.

    return: bool Returns true if they are a blocked, false otherwise
    param: int $userid
    param: int $blockeduserid

    get_contact_requests_between_users(int $userid, int $requesteduserid)   X-Ref
    Get contact requests between users.

    return: \stdClass[]
    param: int $userid The id of the user who is creating the contact request
    param: int $requesteduserid The id of the user being requested

    does_contact_request_exist(int $userid, int $requesteduserid)   X-Ref
    Checks if a contact request already exists between users.

    return: bool Returns true if a contact request exists, false otherwise
    param: int $userid The id of the user who is creating the contact request
    param: int $requesteduserid The id of the user being requested

    is_user_in_conversation(int $userid, int $conversationid)   X-Ref
    Checks if a user is already in a conversation.

    return: bool Returns true if a contact request exists, false otherwise
    param: int $userid The id of the user we want to check if they are in a group
    param: int $conversationid The id of the conversation

    can_contact_user(int $recipientid, int $senderid, bool $evenifblocked = false)   X-Ref
    Checks if the sender can message the recipient.

    return: bool true if recipient hasn't blocked sender and sender can contact to recipient, false otherwise.
    param: int $recipientid
    param: int $senderid
    param: bool $evenifblocked This lets the user know, that even if the recipient has blocked the user

    add_members_to_conversation(array $userids, int $convid)   X-Ref
    Add some new members to an existing conversation.

    param: array $userids User ids array to add as members.
    param: int $convid The conversation id. Must exists.

    remove_members_from_conversation(array $userids, int $convid)   X-Ref
    Remove some members from an existing conversation.

    param: array $userids The user ids to remove from conversation members.
    param: int $convid The conversation id. Must exists.

    count_conversation_members(int $convid)   X-Ref
    Count conversation members.

    return: int Number of conversation members.
    param: int $convid The conversation id.

    is_conversation_area_enabled(string $component, string $itemtype, int $itemid, int $contextid)   X-Ref
    Checks whether or not a conversation area is enabled.

    return: bool Returns if a conversation area exists and is enabled, false otherwise
    param: string $component Defines the Moodle component which the area was added to.
    param: string $itemtype Defines the type of the component.
    param: int $itemid The id of the component.
    param: int $contextid The id of the context.

    get_conversation_by_area(string $component, string $itemtype, int $itemid, int $contextid)   X-Ref
    Get conversation by area.

    return: \stdClass
    param: string $component Defines the Moodle component which the area was added to.
    param: string $itemtype Defines the type of the component.
    param: int $itemid The id of the component.
    param: int $contextid The id of the context.

    enable_conversation(int $conversationid)   X-Ref
    Enable a conversation.

    return: void
    param: int $conversationid The id of the conversation.

    disable_conversation(int $conversationid)   X-Ref
    Disable a conversation.

    return: void
    param: int $conversationid The id of the conversation.

    update_conversation_name(int $conversationid, string $name)   X-Ref
    Update the name of a conversation.

    return: void
    param: int $conversationid The id of a conversation.
    param: string $name The main name of the area

    get_conversation_members(int $userid, int $conversationid, bool $includecontactrequests = false,bool $includeprivacyinfo = false, int $limitfrom = 0,int $limitnum = 0)   X-Ref
    Returns a list of conversation members.

    return: array
    param: int $userid The user we are returning the conversation members for, used by helper::get_member_info.
    param: int $conversationid The id of the conversation
    param: bool $includecontactrequests Do we want to include contact requests with this data?
    param: bool $includeprivacyinfo Do we want to include privacy requests with this data?
    param: int $limitfrom
    param: int $limitnum

    get_unread_conversation_counts(int $userid)   X-Ref
    Get the unread counts for all conversations for the user, sorted by type, and including favourites.

    return: array the unread counts for each conversation, indexed by type.
    param: int $userid the id of the user whose conversations we'll check.

    mute_conversation(int $userid, int $conversationid)   X-Ref
    Handles muting a conversation.

    param: int $userid The id of the user
    param: int $conversationid The id of the conversation

    unmute_conversation(int $userid, int $conversationid)   X-Ref
    Handles unmuting a conversation.

    param: int $userid The id of the user
    param: int $conversationid The id of the conversation

    is_conversation_muted(int $userid, int $conversationid)   X-Ref
    Checks whether a conversation is muted or not.

    return: bool Whether or not the conversation is muted or not
    param: int $userid The id of the user
    param: int $conversationid The id of the conversation

    delete_all_conversation_data(int $conversationid)   X-Ref
    Completely removes all related data in the DB for a given conversation.

    param: int $conversationid The id of the conversation

    can_delete_message_for_all_users(int $userid, int $messageid)   X-Ref
    Checks if a user can delete a message for all users.

    return: bool Returns true if a user can delete the message for all users, false otherwise.
    param: int $userid the user id of who we want to delete the message for all users
    param: int $messageid The message id

    delete_message_for_all_users(int $messageid)   X-Ref
    Delete a message for all users.

    This function does not verify any permissions.

    return: void
    param: int $messageid The message id

    lazy_create_self_conversation(int $userid)   X-Ref
    Create a self conversation for a user, only if one doesn't already exist.

    param: int $userid the user to whom the conversation belongs.