Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • List conversations
  • Create a conversation
  • Get running batches
  • Get a single conversation
  • Edit a conversation
  • Mark all as read
  • Delete a conversation
  • Add recipients
  • Add a message
  • Delete a message
  • Batch update conversations
  • Find recipients
  • Unread count

Was this helpful?

  1. Services
  2. Canvas LMS
  3. Resources

Conversations

API for creating, accessing and updating user conversations.

A Conversation object looks like:

{
  // 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:

{
  // 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"
}

GET /api/v1/conversations

Scope: url:GET|/api/v1/conversations

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

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

filter[]

string

When set, only return conversations for the specified courses, groups or users. The id should be prefixed with its type, e.g. “user_123” or “course_456”. Can be an array (by setting “filter[]”) or single value (by setting “filter”)

filter_mode

string

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 participanting in the conversation

Allowed values: participant_avatars

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

  • 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,
    "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"
  }
]

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.

Request Parameters:

Parameter
Type
Description

recipients[]

Required string

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

Allowed values: sync, async

scope

string

Allowed values: unread, starred, archived

filter[]

string

filter_mode

string

Allowed values: and, or, default or

context_code

string

The course or group that is the context for this conversation. Same format as courses or groups in the recipients argument.

GET /api/v1/conversations/batches

Scope: url:GET|/api/v1/conversations/batches

Example Response:

[
  {
    "id": 1,
    "subject": "conversations api example",
    "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 /api/v1/conversations/:id

Scope: url:GET|/api/v1/conversations/:id

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

Request Parameters:

Parameter
Type
Description

interleave_submissions

boolean

(Obsolete) Submissions are no longer linked to conversations. This parameter is ignored.

scope

string

Allowed values: unread, starred, archived

filter[]

string

filter_mode

string

Allowed values: and, or, default or

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

(Obsolete) Array of assignment submissions having comments relevant to this conversation. Submissions are no longer linked to conversations. This field will always be nil or empty.

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "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", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_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": []
}

PUT /api/v1/conversations/:id

Scope: url:PUT|/api/v1/conversations/:id

Updates attributes for a single conversation.

Request Parameters:

Parameter
Type
Description

conversation[workflow_state]

string

Change the state of this conversation

Allowed values: read, unread, archived

conversation[subscribed]

boolean

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]

boolean

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

scope

string

Allowed values: unread, starred, archived

filter[]

string

filter_mode

string

Allowed values: and, or, default or

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "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", "full_name": "Joe TA"}]
}

POST /api/v1/conversations/mark_all_as_read

Scope: url:POST|/api/v1/conversations/mark_all_as_read

Mark all conversations as read.

DELETE /api/v1/conversations/:id

Scope: url: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,
  "subject": "conversations api example",
  "workflow_state": "read",
  "last_message": null,
  "last_message_at": null,
  "message_count": 0,
  "subscribed": true,
  "private": true,
  "starred": false,
  "properties": []
}

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

Scope: url:POST|/api/v1/conversations/:id/add_recipients

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

Request Parameters:

Parameter
Type
Description

recipients[]

Required string

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "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", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_name": "Bob Student"},
    {"id": 4, "name": "Jim", "full_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": []
      }
    ]
}

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

Scope: url:POST|/api/v1/conversations/:id/add_message

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

An array of user ids. Defaults to all of the current conversation recipients. To explicitly send a message to no other recipients, this array should consist of the logged-in user id.

An array of message ids from this conversation to send to recipients of the new message. Recipients who already had a copy of included messages will not be affected.

Request Parameters:

Parameter
Type
Description

body

Required string

The message to be sent.

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 of video file to be associated with this message.

media_comment_type

string

Type of the associated media file.

Allowed values: audio, video

recipients[]

string

no description

included_messages[]

string

no description

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "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", "full_name": "Joe TA"},
    {"id": 2, "name": "Jane", "full_name": "Jane Teacher"},
    {"id": 3, "name": "Bob", "full_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": []
      }
    ]
}

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

Scope: url: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:

Parameter
Type
Description

remove[]

Required string

Array of message ids to be deleted

Example Response:

{
  "id": 2,
  "subject": "conversations api example",
  "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"]
}

PUT /api/v1/conversations

Scope: url:PUT|/api/v1/conversations

Request Parameters:

Parameter
Type
Description

conversation_ids[]

Required string

List of conversations to update. Limited to 500 conversations.

event

Required string

The action to take on each conversation.

Allowed values: 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'

GET /api/v1/conversations/find_recipients

Scope: url:GET|/api/v1/conversations/find_recipients

GET /api/v1/conversations/unread_count

Scope: url:GET|/api/v1/conversations/unread_count

Get the number of unread conversations for the current user

Example Response:

{'unread_count': '7'}

PreviousContent SharesNextCourse Audit log

Last updated 2 months ago

Was this helpful?

Returns a list of objects.

An array of recipient ids. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. =2&recipients[]=course_3. If the course/group has over 100 enrollments, ‘bulk_message’ and ‘group_conversation’ must be set to true.

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 )

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

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

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

Used when generating “visible” in the API response. See the explanation under the

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

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

Returns a object.

Deprecated, see the in the Search API

This documentation is generated directly from the Canvas LMS source code, available .

ConversationsController#index
ConversationsController#create
ConversationsController#batches
ConversationsController#show
ConversationsController#update
ConversationsController#mark_all_as_read
ConversationsController#destroy
ConversationsController#add_recipients
ConversationsController#add_message
ConversationsController#remove_messages
ConversationsController#batch_update
ConversationsController#find_recipients
ConversationsController#unread_count
on Github
List conversations
Conversation
Create a conversation
Get running batches
create API action
Get a single conversation
Edit a conversation
Mark all as read
Delete a conversation
Add recipients
Add a message
Delete a message
Batch update conversations
Find recipients
Unread count
recipients[]=1&recipients
recipients[]=1&recipients
batches API
index API action
index API action
index API action
index API action
index API action
index API action
index API action
index API action
index API action
progress endpoint
Progress
Find recipients endpoint