# Conversations {% hint style="warning" %} **Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)). {% endhint %} ## Conversations API API for creating, accessing and updating user conversations. **A Conversation object looks like:** ```js { // the unique identifier for the conversation. "id": 2, // the subject of the conversation. "subject": "2", // The current state of the conversation (read, unread or archived). "workflow_state": "unread", // A <=100 character preview from the most recent message. "last_message": "sure thing, here's the file", // the date and time at which the last message was sent. "start_at": "2011-09-02T12:00:00Z", // the number of messages in the conversation. "message_count": 2, // whether the current user is subscribed to the conversation. "subscribed": true, // whether the conversation is private. "private": true, // whether the conversation is starred. "starred": true, // Additional conversation flags (last_author, attachments, media_objects). Each // listed property means the flag is set to true (i.e. the current user is the // most recent author, there are attachments, or there are media objects) "properties": null, // Array of user ids who are involved in the conversation, ordered by // participation level, then alphabetical. Excludes current user, unless this is // a monologue. "audience": null, // Most relevant shared contexts (courses and groups) between current user and // other participants. If there is only one participant, it will also include // that user's enrollment(s)/ membership type(s) in each course/group. "audience_contexts": null, // URL to appropriate icon for this conversation (custom, individual or group // avatar, depending on audience). "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png", // Array of users participating in the conversation. Includes current user. "participants": null, // indicates whether the conversation is visible under the current scope and // filter. This attribute is always true in the index API response, and is // primarily useful in create/update responses so that you can know if the // record should be displayed in the UI. The default scope is assumed, unless a // scope or filter is passed to the create/update API call. "visible": true, // Name of the course or group in which the conversation is occurring. "context_name": "Canvas 101" } ``` **A ConversationParticipant object looks like:** ```js { // The user ID for the participant. "id": 2, // A short name the user has selected, for use in conversations or other less // formal places through the site. "name": "Shelly", // The full name of the user. "full_name": "Sheldon Cooper", // If requested, this field will be included and contain a url to retrieve the // user's avatar. "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png", // The Canvas UUID for the participant. "uuid": "W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCB" } ``` ### [List conversations](#method.conversations.index) [ConversationsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/conversations_controller.rb) **`GET /api/v1/conversations`** **Scope:** `url:GET|/api/v1/conversations` Returns the paginated list of conversations for the current user, most recent ones first. ``` "uuid:W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCB", or "course_456". For users, you can use either their numeric ID or UUID prefixed with "uuid:". Can be an array (by setting "filter[]") or single value (by setting "filter") ``` **Request Parameters:** | Parameter | Type | Description | | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `scope` | `string` |

When set, only return conversations of the specified type. For example, set to “unread” to return only conversations that haven’t been read. The default behavior is to return all non-archived conversations (i.e. read and unread).

Allowed values: unread, starred, archived, sent

When filter\[] contains multiple filters, combine them with this mode, filtering conversations that at have at least all of the contexts (“and”) or at least one of the contexts (“or”)

Allowed values: and, or, default or

| | `interleave_submissions` | `boolean` | (Obsolete) Submissions are no longer linked to conversations. This parameter is ignored. | | `include_all_conversation_ids` | `boolean` | Default is false. If true, the top-level element of the response will be an object rather than an array, and will have the keys “conversations” which will contain the paged conversation data, and “conversation\_ids” which will contain the ids of all conversations under this scope/filter in the same order. | | `include[]` | `string` |

“participant\_avatars”
Optionally include an “avatar\_url” key for each user participating in the conversation
“uuid”
Optionally include an “uuid” key for each user participating in the conversation

Allowed values: participant\_avatars, uuid

| **API response field:** * id The unique identifier for the conversation. * subject The subject of the conversation. * workflow\_state The current state of the conversation (read, unread or archived) * last\_message A <=100 character preview from the most recent message * last\_message\_at The timestamp of the latest message * message\_count The number of messages in this conversation * subscribed Indicates whether the user is actively subscribed to the conversation * private Indicates whether this is a private conversation (i.e. audience of one) * starred Whether the conversation is starred * properties Additional conversation flags (last\_author, attachments, media\_objects). Each listed property means the flag is set to true (i.e. the current user is the most recent author, there are attachments, or there are media objects) * audience Array of user ids who are involved in the conversation, ordered by participation level, then alphabetical. Excludes current user, unless this is a monologue. * audience\_contexts Most relevant shared contexts (courses and groups) between current user and other participants. If there is only one participant, it will also include that user’s enrollment(s)/ membership type(s) in each course/group * avatar\_url URL to appropriate icon for this conversation (custom, individual or group avatar, depending on audience) * participants Array of users (id, name, full\_name) participating in the conversation. Includes current user. If ‘include\[]=participant\_avatars\` was passed as an argument, each user in the array will also have an “avatar\_url” field. If \`include\[]=uuid\` was passed as an argument, each user in the array will also have an “uuid” field * visible Boolean, indicates whether the conversation is visible under the current scope and filter. This attribute is always true in the index API response, and is primarily useful in create/update responses so that you can know if the record should be displayed in the UI. The default scope is assumed, unless a scope or filter is passed to the create/update API call. **Example Response:** ```js [ { "id": 2, "subject": "conversations api example", "workflow_state": "unread", "last_message": "sure thing, here's the file", "last_message_at": "2011-09-02T12:00:00Z", "message_count": 2, "subscribed": true, "private": true, "starred": false, "properties": ["attachments"], "audience": [2], "audience_contexts": {"courses": {"1": ["StudentEnrollment"]}, "groups": {}}, "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png", "participants": [ {"id": 1, "name": "Joe", "full_name": "Joe TA"}, {"id": 2, "name": "Jane", "full_name": "Jane Teacher"} ], "visible": true, "context_name": "Canvas 101" } ] ``` Returns a list of [Conversation](#conversation) objects. ### [Create a conversation](#method.conversations.create) [ConversationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/conversations_controller.rb) **`POST /api/v1/conversations`** **Scope:** `url:POST|/api/v1/conversations` Create a new conversation with one or more recipients. If there is already an existing private conversation with the given recipients, it will be reused. ``` (either numeric IDs or UUIDs prefixed with "uuid:"), or course/group ids prefixed with "course_" or "group_" respectively, e.g. recipients[]=1&recipients[]=uuid:W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCBx&recipients[]=course_3. If the course/group has over 100 enrollments, 'bulk_message' and 'group_conversation' must be set to true. ``` **Request Parameters:** | Parameter | Type | Description | | -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recipients[]` | Required `string` | An array of recipient ids. These may be user ids | | `subject` | `string` | The subject of the conversation. This is ignored when reusing a conversation. Maximum length is 255 characters. | | `body` | Required `string` | The message to be sent | | `force_new` | `boolean` | Forces a new message to be created, even if there is an existing private conversation. | | `group_conversation` | `boolean` | Defaults to false. When false, individual private conversations will be created with each recipient. If true, this will be a group conversation (i.e. all recipients may see all messages and replies). Must be set true if the number of recipients is over the set maximum (default is 100). | | `attachment_ids[]` | `string` | An array of attachments ids. These must be files that have been previously uploaded to the sender’s “conversation attachments” folder. | | `media_comment_id` | `string` | Media comment id of an audio or video file to be associated with this message. | | `media_comment_type` | `string` |

Type of the associated media file

Allowed values: audio, video

| | `mode` | `string` |

Determines whether the messages will be created/sent synchronously or asynchronously. Defaults to sync, and this option is ignored if this is a group conversation or there is just one recipient (i.e. it must be a bulk private message). When sent async, the response will be an empty array (batch status can be queried via the batches API)

Allowed values: sync, async

| | `scope` | `string` |