Find recipients SearchController#recipients

GET /api/v1/conversations/find_recipients

GET /api/v1/search/recipients

Find valid recipients (users, courses and groups) that the current user can send messages to. The /api/v1/search/recipients path is the preferred endpoint, /api/v1/conversations/find_recipients is deprecated.

Pagination is supported.

Request Parameters:

• search

  Search terms used for matching users/courses/groups (e.g. "bob smith"). If multiple terms are given (separated via whitespace), only results matching all terms will be returned.

• context

  Limit the search to a particular course/group (e.g. "course_3" or "group_4").

• exclude[]

  Array of ids to exclude from the search. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. exclude[]=1&exclude=2&exclude[]=course_3

• type

  "user"|"context"

  Limit the search just to users or contexts (groups/courses).

• user_id

  Integer

  Search for a specific user id. This ignores the other above parameters, and will never return more than one result.

• from_conversation_id

  Integer

  When searching by user_id, only users that could be normally messaged by this user will be returned. This parameter allows you to specify a conversation that will be referenced for a shared context -- if both the current user and the searched user are in the conversation, the user will be returned. This is used to start new side conversations.

• permissions[]

  Array of permission strings to be checked for each matched context (e.g. "send_messages"). This argument determines which permissions may be returned in the response; it won't prevent contexts from being returned if they don't grant the permission(s)

API response field:

• id

  The unique identifier for the user/context. For groups/courses, the id is prefixed by "group_"/"course_" respectively.

• name

  The name of the user/context

• avatar_url

  Avatar image url for the user/context

• type

  "context"|"course"|"section"|"group"|"user"|null

  Type of recipients to return, defaults to null (all). "context" encompasses "course", "section" and "group"

• types[]

  Array of recipient types to return (see type above), e.g. types[]=user&types=course

• user_count

  Only set for contexts, indicates number of messageable users

• common_courses

  Only set for users. Hash of course ids and enrollment types for each course to show what they share with this user

• common_groups

  Only set for users. Hash of group ids and enrollment types for each group to show what they share with this user

• permissions[]

  Only set for contexts. Mapping of requested permissions that the context grants the current user, e.g. { send_messages: true }

[
  {"id": "group_1", "name": "the group", "type": "context", "user_count": 3},
  {"id": 2, "name": "greg", "common_courses": {}, "common_groups": {"1": ["Member"]}}
]