Conversations API

API for creating, accessing and updating user conversations.

List conversations ConversationsController#index

GET /api/v1/conversations

Returns the list of conversations for the current user, most recent ones first.

Request Parameters:

  • scope
    optional, "unread"|"starred"|"archived"

    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).

  • filter
    optional, course_id|group_id|user_id

    When set, only return conversations for the specified course, group or user. The id should be prefixed with its type, e.g. "user_123" or "course_456"

  • interleave_submissions

    Boolean, default false. If true, the message_count will also include these submission-based messages in the total. See the show action for more information.

  • include_all_conversation_ids

    Boolean, default 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.

API response field:

  • id

    The unique identifier for 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) participating in the conversation. Includes current user.

  • 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:

[
  {
    "id": 2,
    "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 TA"}, {"id": 2, "name": "Jane Teacher"}],
    "visible": true
  }
]

Create a conversation ConversationsController#create

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.

Request Parameters:

  • recipients[]

    An array of recipient ids. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

  • body

    The message to be sent

  • group_conversation
    true|false

    Ignored if there is just one

    recipient, defaults to false. If true, this will be a group conversation (i.e. all recipients will see all messages and replies). If false, individual private conversations will be started with each recipient.

  • attachment_ids[]

    An array of attachments ids. These must be files that have been previously uploaded to the sender's "conversation attachments" folder.

  • media_comment_id

    Media comment id of an audio of video file to be associated with this message.

  • media_comment_type
    "audio"|"video"

    Type of the associated

    media file

  • mode
    "sync"|"async"

    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)

  • scope
    optional, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter
    optional, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

ConversationsController#batches

GET /api/v1/conversations/batches

Returns any currently running conversation batches for the current user. Conversation batches are created when a bulk private message is sent asynchronously (see the mode argument to the create API action).

Example Response:

[
  {
    "id": 1,
    "workflow_state": "created",
    "completion": 0.1234,
    "tags": [],
    "message":
    {
      "id": 1,
      "created_at": "2011-09-02T10:00:00Z",
      "body": "quick reminder, no class tomorrow",
      "author_id": 1,
      "generated": false,
      "media_comment": null,
      "forwarded_messages": [],
      "attachments": []
    }
  }
]

Get a single conversation ConversationsController#show

GET /api/v1/conversations/:id

Returns information for a single conversation. Response includes all fields that are present in the list/index action, as well as messages, submissions, and extended participant information.

Request Parameters:

  • interleave_submissions

    Boolean, default false. If true, submission data will be returned as first class messages interleaved with other messages. The submission details (comments, assignment, etc.) will be stored as the submission property on the message. Note that if set, the message_count will also include these messages in the total.

  • scope
    optional, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter
    optional, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

  • auto_mark_as_read

    Boolean, default true. If true, unread conversations will be automatically marked as read. This will default to false in a future API release, so clients should explicitly send true if that is the desired behavior.

API response field:

  • participants

    Array of relevant users. Includes current user. If there are forwarded messages in this conversation, the authors of those messages will also be included, even if they are not participating in this conversation. Fields include:

  • messages

    Array of messages, newest first. Fields include:

    id

    The unique identifier for the message

    created_at

    The timestamp of the message

    body

    The actual message body

    author_id

    The id of the user who sent the message (see audience, participants)

    generated

    If true, indicates this is a system-generated message (e.g. "Bob added Alice to the conversation")

    media_comment

    Audio/video comment data for this message (if applicable). Fields include: display_name, content-type, media_id, media_type, url

    forwarded_messages

    If this message contains forwarded messages, they will be included here (same format as this list). Note that those messages may have forwarded messages of their own, etc.

    attachments

    Array of attachments for this message. Fields include: display_name, content-type, filename, url

  • submissions

    Array of assignment submissions having comments relevant to this conversation. These should be interleaved with the messages when displaying to the user. See the Submissions API documentation for details on the fields included. This response includes the submission_comments and assignment associations.

Example Response:

{
  "id": 2,
  "workflow_state": "unread",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "name": "Bob Student"}],
  "messages":
    [
      {
        "id": 3,
        "created_at": "2011-09-02T12:00:00Z",
        "body": "sure thing, here's the file",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": [{"id": 1, "display_name": "notes.doc", "uuid": "abcdefabcdefabcdefabcdefabcdef"}]
      },
      {
        "id": 2,
        "created_at": "2011-09-02T11:00:00Z",
        "body": "hey, bob didn't get the notes. do you have a copy i can give him?",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages":
          [
            {
              "id": 1,
              "created_at": "2011-09-02T10:00:00Z",
              "body": "can i get a copy of the notes? i was out",
              "author_id": 3,
              "generated": false,
              "media_comment": null,
              "forwarded_messages": [],
              "attachments": []
            }
          ],
        "attachments": []
      }
    ],
  "submissions": []
}

Edit a conversation ConversationsController#update

PUT /api/v1/conversations/:id

Updates attributes for a single conversation.

Request Parameters:

  • conversation[workflow_state]
    "read"|"unread"|"archived"

    Change the state of this conversation

  • conversation[subscribed]
    true|false

    Toggle the current user's subscription to the conversation (only valid for group conversations). If unsubscribed, the user will still have access to the latest messages, but the conversation won't be automatically flagged as unread, nor will it jump to the top of the inbox.

  • conversation[starred]
    true|false

    Toggle the starred state of the current user's view of the conversation.

  • scope
    optional, "unread"|"starred"|"archived"

    Used when generating "visible" in the API response. See the explanation under the index API action

  • filter
    optional, course_id|group_id|user_id

    Used when generating "visible" in the API response. See the explanation under the index API action

Example Response:

{
  "id": 2,
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": ["attachments"],
  "audience": [2],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}]
}

Mark all as read ConversationsController#mark_all_as_read

POST /api/v1/conversations/mark_all_as_read

Mark all conversations as read.

Delete a conversation ConversationsController#destroy

DELETE /api/v1/conversations/:id

Delete this conversation and its messages. Note that this only deletes this user's view of the conversation.

Response includes same fields as UPDATE action

Example Response:

{
  "id": 2,
  "workflow_state": "read",
  "last_message": null,
  "last_message_at": null,
  "message_count": 0,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": []
}

Add recipients ConversationsController#add_recipients

POST /api/v1/conversations/:id/add_recipients

Add recipients to an existing group conversation. Response is similar to the GET/show action, except that omits submissions and only includes the latest message (e.g. "joe was added to the conversation by bob")

Request Parameters:

  • recipients[]

    An array of recipient ids. These may be user ids or course/group ids prefixed with "course_" or "group_" respectively, e.g. recipients[]=1&recipients=2&recipients[]=course_3

Example Response:

{
  "id": 2,
  "workflow_state": "read",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3, 4],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "name": "Bob Student"}, {"id": 4, "name": "Jim Admin"}],
  "messages":
    [
      {
        "id": 4,
        "created_at": "2011-09-02T12:10:00Z",
        "body": "Jim was added to the conversation by Joe TA",
        "author_id": 1,
        "generated": true,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Add a message ConversationsController#add_message

POST /api/v1/conversations/:id/add_message

Add a message to an existing conversation. Response is similar to the GET/show action, except that omits submissions and only includes the latest message (i.e. what we just sent)

Request Parameters:

  • body

    The message to be sent

  • attachment_ids[]

    An array of attachments ids. These must be files that have been previously uploaded to the sender's "conversation attachments" folder.

  • media_comment_id

    Media comment id of an audio of video file to be associated with this message.

  • media_comment_type
    "audio"|"video"

    Type of the associated

    media file

Example Response:

{
  "id": 2,
  "workflow_state": "unread",
  "last_message": "let's talk this over with jim",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 2,
  "subscribed": true,
  "private": false,
  "starred": null,
  "properties": [],
  "audience": [2, 3],
  "audience_contexts": {"courses": {"1": []}, "groups": {}},
  "avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
  "participants": [{"id": 1, "name": "Joe TA"}, {"id": 2, "name": "Jane Teacher"}, {"id": 3, "name": "Bob Student"}],
  "messages":
    [
      {
        "id": 3,
        "created_at": "2011-09-02T12:00:00Z",
        "body": "let's talk this over with jim",
        "author_id": 2,
        "generated": false,
        "media_comment": null,
        "forwarded_messages": [],
        "attachments": []
      }
    ]
}

Delete a message ConversationsController#remove_messages

POST /api/v1/conversations/:id/remove_messages

Delete messages from this conversation. Note that this only affects this user's view of the conversation. If all messages are deleted, the conversation will be as well (equivalent to DELETE)

Request Parameters:

  • remove

    Array of message ids to be deleted

Example Response:

{
  "id": 2,
  "workflow_state": "read",
  "last_message": "sure thing, here's the file",
  "last_message_at": "2011-09-02T12:00:00-06:00",
  "message_count": 1,
  "subscribed": true,
  "private": true,
  "starred": null,
  "properties": ["attachments"]
}

Batch update conversations ConversationsController#batch_update

PUT /api/v1/conversations

Perform a change on a set of conversations. Operates asynchronously; use the progress endpoint to query the status of an operation.

Request Parameters:

  • conversation_ids[]

    List of conversations to update. Limited to 500 conversations.

  • event

    The action to take on each conversation. Must be one of 'mark_as_read', 'mark_as_unread', 'star', 'unstar', 'archive', 'destroy'

Example Request:

curl https://<canvas>/api/v1/conversations \ 
  -X PUT \ 
  -H 'Authorization: Bearer <token>' \ 
  -d 'event=mark_as_read' \ 
  -d 'conversation_ids[]=1' \ 
  -d 'conversation_ids[]=2'
Returns a Progress

Find recipients ConversationsController#find_recipients

GET /api/v1/conversations/find_recipients

Deprecated, see the Find recipients endpoint in the Search API