conversations.json

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.2",
  "basePath": "https://canvas.instructure.com/api",
  "resourcePath": "/conversations",
  "produces": [
    "application/json"
  ],
  "apis": [
    {
      "path": "/v1/conversations",
      "description": "Returns the paginated list of conversations for the current user, most\nrecent ones first.",
      "operations": [
        {
          "method": "GET",
          "summary": "List conversations",
          "notes": "Returns the paginated list of conversations for the current user, most\nrecent ones first.",
          "nickname": "list_conversations",
          "parameters": [
            {
              "paramType": "query",
              "name": "scope",
              "description": "When set, only return conversations of the specified type. For example,\nset to \"unread\" to return only conversations that haven't been read.\nThe default behavior is to return all non-archived conversations (i.e.\nread and unread).",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "unread",
                "starred",
                "archived"
              ]
            },
            {
              "paramType": "query",
              "name": "filter",
              "description": "When set, only return conversations for the specified courses, groups\nor users. The id should be prefixed with its type, e.g. \"user_123\" or\n\"course_456\". Can be an array (by setting \"filter[]\") or single value\n(by setting \"filter\")",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "query",
              "name": "filter_mode",
              "description": "When filter[] contains multiple filters, combine them with this mode,\nfiltering conversations that at have at least all of the contexts (\"and\")\nor at least one of the contexts (\"or\")",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "and",
                "or",
                "default or"
              ]
            },
            {
              "paramType": "query",
              "name": "interleave_submissions",
              "description": "(Obsolete) Submissions are no\nlonger linked to conversations. This parameter is ignored.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "query",
              "name": "include_all_conversation_ids",
              "description": "Default is false. If true,\nthe top-level element of the response will be an object rather than\nan array, and will have the keys \"conversations\" which will contain the\npaged conversation data, and \"conversation_ids\" which will contain the\nids of all conversations under this scope/filter in the same order.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "query",
              "name": "include",
              "description": "\"participant_avatars\":: Optionally include an \"avatar_url\" key for each user participanting in the conversation",
              "type": "array",
              "format": null,
              "required": false,
              "enum": [
                "participant_avatars"
              ],
              "items": {
                "type": "string"
              }
            }
          ],
          "type": "array",
          "items": {
            "$ref": "Conversation"
          }
        }
      ]
    },
    {
      "path": "/v1/conversations",
      "description": "Create a new conversation with one or more recipients. If there is already\nan existing private conversation with the given recipients, it will be\nreused.",
      "operations": [
        {
          "method": "POST",
          "summary": "Create a conversation",
          "notes": "Create a new conversation with one or more recipients. If there is already\nan existing private conversation with the given recipients, it will be\nreused.",
          "nickname": "create_conversation",
          "parameters": [
            {
              "paramType": "form",
              "name": "recipients",
              "description": "An array of recipient ids. These may be user ids or course/group ids\nprefixed with \"course_\" or \"group_\" respectively, e.g.\nrecipients[]=1&recipients[]=2&recipients[]=course_3",
              "type": "array",
              "format": null,
              "required": true,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "subject",
              "description": "The subject of the conversation. This is ignored when reusing a\nconversation. Maximum length is 255 characters.",
              "type": "string",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "body",
              "description": "The message to be sent",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "group_conversation",
              "description": "Defaults to false. If true, this will be a group conversation (i.e. all\nrecipients may see all messages and replies). If false, individual private\nconversations will be started with each recipient. Must be set false if the\nnumber of recipients is over the set maximum (default is 100).",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "attachment_ids",
              "description": "An array of attachments ids. These must be files that have been previously\nuploaded to the sender's \"conversation attachments\" folder.",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "media_comment_id",
              "description": "Media comment id of an audio of video file to be associated with this\nmessage.",
              "type": "string",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "media_comment_type",
              "description": "Type of the associated media file",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "audio",
                "video"
              ]
            },
            {
              "paramType": "form",
              "name": "user_note",
              "description": "Will add a faculty journal entry for each recipient as long as the user\nmaking the api call has permission, the recipient is a student and\nfaculty journals are enabled in the account.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "mode",
              "description": "Determines whether the messages will be created/sent synchronously or\nasynchronously. Defaults to sync, and this option is ignored if this is a\ngroup conversation or there is just one recipient (i.e. it must be a bulk\nprivate message). When sent async, the response will be an empty array\n(batch status can be queried via the {api:ConversationsController#batches batches API})",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "sync",
                "async"
              ]
            },
            {
              "paramType": "form",
              "name": "scope",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "unread",
                "starred",
                "archived"
              ]
            },
            {
              "paramType": "form",
              "name": "filter",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "filter_mode",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "and",
                "or",
                "default or"
              ]
            },
            {
              "paramType": "form",
              "name": "context_code",
              "description": "The course or group that is the context for this conversation. Same format\nas courses or groups in the recipients argument.",
              "type": "string",
              "format": null,
              "required": false
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/batches",
      "description": "Returns any currently running conversation batches for the current user.\nConversation batches are created when a bulk private message is sent\nasynchronously (see the mode argument to the {api:ConversationsController#create create API action}).",
      "operations": [
        {
          "method": "GET",
          "summary": "Get running batches",
          "notes": "Returns any currently running conversation batches for the current user.\nConversation batches are created when a bulk private message is sent\nasynchronously (see the mode argument to the {api:ConversationsController#create create API action}).",
          "nickname": "get_running_batches",
          "parameters": [

          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}",
      "description": "Returns information for a single conversation for the current user. Response includes all\nfields that are present in the list/index action as well as messages\nand extended participant information.",
      "operations": [
        {
          "method": "GET",
          "summary": "Get a single conversation",
          "notes": "Returns information for a single conversation for the current user. Response includes all\nfields that are present in the list/index action as well as messages\nand extended participant information.",
          "nickname": "get_single_conversation",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "query",
              "name": "interleave_submissions",
              "description": "(Obsolete) Submissions are no\nlonger linked to conversations. This parameter is ignored.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "query",
              "name": "scope",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "unread",
                "starred",
                "archived"
              ]
            },
            {
              "paramType": "query",
              "name": "filter",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "query",
              "name": "filter_mode",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "and",
                "or",
                "default or"
              ]
            },
            {
              "paramType": "query",
              "name": "auto_mark_as_read",
              "description": "Default true. If true, unread\nconversations will be automatically marked as read. This will default\nto false in a future API release, so clients should explicitly send\ntrue if that is the desired behavior.",
              "type": "boolean",
              "format": null,
              "required": false
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}",
      "description": "Updates attributes for a single conversation.",
      "operations": [
        {
          "method": "PUT",
          "summary": "Edit a conversation",
          "notes": "Updates attributes for a single conversation.",
          "nickname": "edit_conversation",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "conversation[workflow_state]",
              "description": "Change the state of this conversation",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "read",
                "unread",
                "archived"
              ]
            },
            {
              "paramType": "form",
              "name": "conversation[subscribed]",
              "description": "Toggle the current user's subscription to the conversation (only valid for\ngroup conversations). If unsubscribed, the user will still have access to\nthe latest messages, but the conversation won't be automatically flagged\nas unread, nor will it jump to the top of the inbox.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "conversation[starred]",
              "description": "Toggle the starred state of the current user's view of the conversation.",
              "type": "boolean",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "scope",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "unread",
                "starred",
                "archived"
              ]
            },
            {
              "paramType": "form",
              "name": "filter",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "filter_mode",
              "description": "Used when generating \"visible\" in the API response. See the explanation\nunder the {api:ConversationsController#index index API action}",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "and",
                "or",
                "default or"
              ]
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/mark_all_as_read",
      "description": "Mark all conversations as read.",
      "operations": [
        {
          "method": "POST",
          "summary": "Mark all as read",
          "notes": "Mark all conversations as read.",
          "nickname": "mark_all_as_read",
          "parameters": [

          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}",
      "description": "Delete this conversation and its messages. Note that this only deletes\nthis user's view of the conversation.\n\nResponse includes same fields as UPDATE action",
      "operations": [
        {
          "method": "DELETE",
          "summary": "Delete a conversation",
          "notes": "Delete this conversation and its messages. Note that this only deletes\nthis user's view of the conversation.\n\nResponse includes same fields as UPDATE action",
          "nickname": "delete_conversation",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}/add_recipients",
      "description": "Add recipients to an existing group conversation. Response is similar to\nthe GET/show action, except that only includes the\nlatest message (e.g. \"joe was added to the conversation by bob\")",
      "operations": [
        {
          "method": "POST",
          "summary": "Add recipients",
          "notes": "Add recipients to an existing group conversation. Response is similar to\nthe GET/show action, except that only includes the\nlatest message (e.g. \"joe was added to the conversation by bob\")",
          "nickname": "add_recipients",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "recipients",
              "description": "An array of recipient ids. These may be user ids or course/group ids\nprefixed with \"course_\" or \"group_\" respectively, e.g.\nrecipients[]=1&recipients[]=2&recipients[]=course_3",
              "type": "array",
              "format": null,
              "required": true,
              "items": {
                "type": "string"
              }
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}/add_message",
      "description": "Add a message to an existing conversation. Response is similar to the\nGET/show action, except that only includes the\nlatest message (i.e. what we just sent)\n\nAn array of user ids. Defaults to all of the current conversation\nrecipients. To explicitly send a message to no other recipients,\nthis array should consist of the logged-in user id.\n\nAn array of message ids from this conversation to send to recipients\nof the new message. Recipients who already had a copy of included\nmessages will not be affected.",
      "operations": [
        {
          "method": "POST",
          "summary": "Add a message",
          "notes": "Add a message to an existing conversation. Response is similar to the\nGET/show action, except that only includes the\nlatest message (i.e. what we just sent)\n\nAn array of user ids. Defaults to all of the current conversation\nrecipients. To explicitly send a message to no other recipients,\nthis array should consist of the logged-in user id.\n\nAn array of message ids from this conversation to send to recipients\nof the new message. Recipients who already had a copy of included\nmessages will not be affected.",
          "nickname": "add_message",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "body",
              "description": "The message to be sent.",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "attachment_ids",
              "description": "An array of attachments ids. These must be files that have been previously\nuploaded to the sender's \"conversation attachments\" folder.",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "media_comment_id",
              "description": "Media comment id of an audio of video file to be associated with this\nmessage.",
              "type": "string",
              "format": null,
              "required": false
            },
            {
              "paramType": "form",
              "name": "media_comment_type",
              "description": "Type of the associated media file.",
              "type": "string",
              "format": null,
              "required": false,
              "enum": [
                "audio",
                "video"
              ]
            },
            {
              "paramType": "form",
              "name": "recipients",
              "description": "no description",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "included_messages",
              "description": "no description",
              "type": "array",
              "format": null,
              "required": false,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "user_note",
              "description": "Will add a faculty journal entry for each recipient as long as the user\nmaking the api call has permission, the recipient is a student and\nfaculty journals are enabled in the account.",
              "type": "boolean",
              "format": null,
              "required": false
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/{id}/remove_messages",
      "description": "Delete messages from this conversation. Note that this only affects this\nuser's view of the conversation. If all messages are deleted, the\nconversation will be as well (equivalent to DELETE)",
      "operations": [
        {
          "method": "POST",
          "summary": "Delete a message",
          "notes": "Delete messages from this conversation. Note that this only affects this\nuser's view of the conversation. If all messages are deleted, the\nconversation will be as well (equivalent to DELETE)",
          "nickname": "delete_message",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "description": "ID",
              "type": "string",
              "format": null,
              "required": true
            },
            {
              "paramType": "form",
              "name": "remove",
              "description": "Array of message ids to be deleted",
              "type": "array",
              "format": null,
              "required": true,
              "items": {
                "type": "string"
              }
            }
          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations",
      "description": "Perform a change on a set of conversations. Operates asynchronously; use the {api:ProgressController#show progress endpoint}\nto query the status of an operation.",
      "operations": [
        {
          "method": "PUT",
          "summary": "Batch update conversations",
          "notes": "Perform a change on a set of conversations. Operates asynchronously; use the {api:ProgressController#show progress endpoint}\nto query the status of an operation.",
          "nickname": "batch_update_conversations",
          "parameters": [
            {
              "paramType": "form",
              "name": "conversation_ids",
              "description": "List of conversations to update. Limited to 500 conversations.",
              "type": "array",
              "format": null,
              "required": true,
              "items": {
                "type": "string"
              }
            },
            {
              "paramType": "form",
              "name": "event",
              "description": "The action to take on each conversation.",
              "type": "string",
              "format": null,
              "required": true,
              "enum": [
                "mark_as_read",
                "mark_as_unread",
                "star",
                "unstar",
                "archive",
                "destroy"
              ]
            }
          ],
          "type": "Progress"
        }
      ]
    },
    {
      "path": "/v1/conversations/find_recipients",
      "description": "Deprecated, see the {api:SearchController#recipients Find recipients endpoint} in the Search API",
      "operations": [
        {
          "method": "GET",
          "summary": "Find recipients",
          "notes": "Deprecated, see the {api:SearchController#recipients Find recipients endpoint} in the Search API",
          "nickname": "find_recipients",
          "parameters": [

          ],
          "type": "void"
        }
      ]
    },
    {
      "path": "/v1/conversations/unread_count",
      "description": "Get the number of unread conversations for the current user",
      "operations": [
        {
          "method": "GET",
          "summary": "Unread count",
          "notes": "Get the number of unread conversations for the current user",
          "nickname": "unread_count",
          "parameters": [

          ],
          "type": "void"
        }
      ]
    }
  ],
  "models": {
    "Conversation": {
      "id": "Conversation",
      "description": "",
      "required": [

      ],
      "properties": {
        "id": {
          "description": "the unique identifier for the conversation.",
          "example": 2,
          "type": "integer",
          "format": "int64"
        },
        "subject": {
          "description": "the subject of the conversation.",
          "example": 2,
          "type": "string"
        },
        "workflow_state": {
          "description": "The current state of the conversation (read, unread or archived).",
          "example": "unread",
          "type": "string"
        },
        "last_message": {
          "description": "A <=100 character preview from the most recent message.",
          "example": "sure thing, here's the file",
          "type": "string"
        },
        "start_at": {
          "description": "the date and time at which the last message was sent.",
          "example": "2011-09-02T12:00:00Z",
          "type": "datetime"
        },
        "message_count": {
          "description": "the number of messages in the conversation.",
          "example": 2,
          "type": "integer"
        },
        "subscribed": {
          "description": "whether the current user is subscribed to the conversation.",
          "example": true,
          "type": "boolean"
        },
        "private": {
          "description": "whether the conversation is private.",
          "example": true,
          "type": "boolean"
        },
        "starred": {
          "description": "whether the conversation is starred.",
          "example": true,
          "type": "boolean"
        },
        "properties": {
          "description": "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)",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "audience": {
          "description": "Array of user ids who are involved in the conversation, ordered by participation level, then alphabetical. Excludes current user, unless this is a monologue.",
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "audience_contexts": {
          "description": "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.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "avatar_url": {
          "description": "URL to appropriate icon for this conversation (custom, individual or group avatar, depending on audience).",
          "example": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
          "type": "string"
        },
        "participants": {
          "description": "Array of users participating in the conversation. Includes current user.",
          "type": "array",
          "items": {
            "$ref": "ConversationParticipant"
          }
        },
        "visible": {
          "description": "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": true,
          "type": "boolean"
        },
        "context_name": {
          "description": "Name of the course or group in which the conversation is occurring.",
          "example": "Canvas 101",
          "type": "string"
        }
      }
    },
    "ConversationParticipant": {
      "id": "ConversationParticipant",
      "description": "",
      "required": [

      ],
      "properties": {
        "id": {
          "description": "The user ID for the participant.",
          "example": 2,
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "description": "A short name the user has selected, for use in conversations or other less formal places through the site.",
          "example": "Shelly",
          "type": "string"
        },
        "full_name": {
          "description": "The full name of the user.",
          "example": "Sheldon Cooper",
          "type": "string"
        },
        "avatar_url": {
          "description": "If requested, this field will be included and contain a url to retrieve the user's avatar.",
          "example": "https://canvas.instructure.com/images/messages/avatar-50.png",
          "type": "string"
        }
      }
    }
  }
}