Admin Oversight API
The Admin Oversight API provides near real-time oversight information for customer administrators on Enterprise Grid. This API introduces a new collection of API methods for accessing channel info, channel membership, and specific messages.
Org owners can install Admin Oversight API applications via the typical OAuth process.
This API is not intended for bulk message collection. While you may collect messages with these API methods, they're rate-limited to 100 messages per hour, returning many fewer messages than the conversations.history and conversations.replies Web API methods (which allow 900 messages per hour with 60 calls at 15 messages per call) and equivalent Discovery API methods.
This API is designed to support the admin management use cases such as:
- Automating channel management
- Guest management
- Reporting messages
Scopes
The Admin Oversight API methods rely on combinations of the following scopes. Read a method's Facts to determine which ones that method specifically requires.
Methods
Enterprise and users
Use these methods to gather basic information about the Enterprise Grid organization and its members.
| Method | Description |
|---|---|
oversight.enterprise.info | Returns basic information about an Enterprise Grid org |
oversight.user.conversations | Returns list IDs for all conversations a user is in |
oversight.user.info | Returns information on a single user |
oversight.users.list | Returns list of all users |
Conversations (channels, groups, and DMs)
Use these methods to gather information about and message data from public channels (channels), private channels (channels?private=true), multiparty DMs (groups), and direct messages (dms).
| Method | Description |
|---|---|
oversight.conversations.info | Returns overview of a single channel |
oversight.conversations.list | Returns a list of all conversations |
oversight.conversations.members | Returns list of everyone in a conversation |
Individual messages
Use this method to collect a complete history for a single message.
| Method | Description |
|---|---|
oversight.chat.info | Returns a single message |
Tombstone and Deleting Messages
| Method | Description |
|---|---|
oversight.chat.delete | Deletes a message |
oversight.chat.tombstone | Tombstones a message |
oversight.chat.restore | Restores a message |
oversight.chat.update | Updates a message |
oversight.enterprise.info
This method returns basic information about the Enterprise Grid organization where the app is installed, including all workspaces (teams).
The teams array is paged at 1000 items by default, but this can also be shortened with the limit parameter.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"limit": 1,
"cursor": "cGFnZToz"
}
Example response
oversight.users.list
This method returns a list of all users.
Very similar to the original users.list API method. Includes an array of workspace IDs that the user belongs to on an Enterprise Grid organization (teams).
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"include_deleted": true,
"offset": "W0123ABC456"
}
Example response
oversight.user.info
This method returns information on a single user on Enterprise Grid.
Users
The response will include an array of workspace IDs that the user belongs to on an Enterprise Grid organization (teams). You may search by either user ID (user) or email address (email), but you must include one of those.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"user": "W0123ABC456",
"email": "name@domain.com"
}
Example response
oversight.user.conversations
This method lists IDs for all conversations (channels and DMs, including public, private, organization-wide, and shared) a user is in, based upon the scopes that your app currently has.
With the optional include_historical argument, it will also return any conversation this user was in at some point and left.
Slack only stores and returns the most recent date and time that the user joined or left a conversation.
This method can also be filtered by conversation type: public, private, DM, MPDM. These filters are exclusive and can only be used one at a time.
Since channels like DMs and MPDMs are org-shared channels and are accessible globally within an Enterprise Grid, the team_id field will return the ID associated with the Enterprise ID instead of an individual team.
Example default request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"user": "W0123ABC456"
}
Example default response
oversight.conversations.list
This method provides a paginated list of all conversations, depending on the token scopes, and the team ID. The endpoint provides a truncated version of the channel metadata.
DMs and MPDMs
Because both direct messages and multi-party direct messages are automatically organization-wide on an Enterprise Grid org, they will only be returned when an Enterprise ID is passed as the team parameter, or is omitted entirely.
Channels
Org-shared and multi-workspace channels will also only be returned when the Enterprise ID is passed as the team parameter, or is omitted entirely. Channels that belong to a single workspace will only be returned when that workspace ID is passed into the team parameter.
Conversation names
Channel names are included in this method to make it easier to build a browsable list of conversations. Depending on the conversation type, you can expect a different name format. The name field will return the channel name for channels, the channel ID for DMs, and a string of participants prefixed by mpdm for MPDMs. Please see the Example response for more information.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"team": "T0123ABC456",
"offset": "G0QPJB83S"
}
Example response
oversight.conversations.info
This method provides a comprehensive overview of a single channel's metadata.
The response includes details about channel retention. The retention object includes the type and duration. Retention type is either custom or default. Retention duration is the period of time content is retained in a channel in days.
Deleted channels take about 24 hours to be expunged from our databases. If a channel is deleted but has not yet been pruned, the is_deleted field will return true. When the channel has been fully removed from the databases, you should expect to see a channel_not_found error.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"channel": "G0123ABC456",
"team": "T0123ABC456"
}
Example response
oversight.conversations.members
This method provides a list of everyone in a given channel, private channel, MDPM, or DM.
Like our other .list API methods, its payload is purposely small so that the list itself can be pulled quickly, which is especially important on very large orgs with multiple default channels.
If you want to include members that have left the channel, set the include_member_left argument to true. Otherwise, only members currently in the conversation are returned in the response (for these users, the date_left property is set to 0). Slack does not store every instance of a user joining or leaving a channel, so those records will only reflect the most recent activity. If someone leaves a channel and then rejoins, we update the date_joined field and set the date_left field back to 0.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"channel": "G0123ABC456",
"team": "T0123ABC456",
"limit": 4,
"offset": "W123ABC456",
"include_member_left": true
}
Example response
oversight.chat.info
This method returns a single message. This endpoint will be limited to 100 requests per hour.
If the message has been edited (or deleted), this method returns the current edited (or deleted) message. If an Enterprise Grid customer has their retention set to keep edits and deletes, it will also return all of those edits or the deletion. See below for examples.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"ts": "1569520591.000500",
"channel": "C0123ABC456",
"team": "T123ABC456"
}
Example responses
Unedited message
If a message has not been edited, the "edits" array will exist, but it will be empty.
{
"ok": true,
"message": {
"client_msg_id": "6b6239f9-9a22-4759-ac01-7e9c48658092",
"type": "message",
"text": "Can we reschedule today's meeting?",
"user": "W123ABC456",
"ts": "1569520591.000500",
"team": "T123ABC456"
},
"edits": []
}
Edited message
For an edited message, the root message object is identical to the one in the relevant .history call: The text field shows the current message content as seen in the client, and the edited object shows who made the most recent edit and when they made it.
The edits array will list each edit as a separate object in ascending order. Each object will contain a text field that shows the message content after the edit was made, as well as a previous object that shows what the message content was immediately prior to this edit.
Original message with a single edit
{
"ok": true,
"message": {
"client_msg_id": "6b6239f9-9a22-4759-ac01-7e9c48658092",
"type": "message",
"text": "Can we reschedule today's meeting? I have a conflict.",
"user": "W123ABC456",
"ts": "1569520591.000500",
"team": "T123ABC456",
"edited": {
"user": "W123ABC456",
"ts": "1569521123.000000"
}
},
"edits": [
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521123.000000",
"text": "Can we reschedule today's meeting? I have a conflict.",
"previous": {
"text": "Can we reschedule today's meeting?"
},
"original_ts": "1569520591.000500",
"subtype": "message_changed",
"editor_id": "W123ABC456"
}
]
}
Same message edited a second time
{
"ok": true,
"message": {
"client_msg_id": "6b6239f9-9a22-4759-ac01-7e9c48658092",
"type": "message",
"text": "Never mind, I was able to move my other meeting. See you soon.",
"user": "W123ABC456",
"ts": "1569520591.000500",
"team": "T123ABC456",
"edited": {
"user": "W123ABC456",
"ts": "1569521616.000000"
}
},
"edits": [
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521123.000000",
"text": "Can we reschedule today's meeting? I have a conflict.",
"previous": {
"text": "Can we reschedule today's meeting?"
},
"original_ts": "1569520591.000500",
"subtype": "message_changed",
"editor_id": "W123ABC456"
},
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521616.000000",
"text": "Never mind, I was able to move my other meeting. See you soon.",
"previous": {
"text": "Can we reschedule today's meeting? I have a conflict."
},
"original_ts": "1569520591.000500",
"subtype": "message_changed",
"editor_id": "W123ABC456"
}
]
}
Deleted message
When a message has been deleted, the root message object will only show "type": "deleted", not any version of the message content. The message content at the time of deletion can be found in the edits array in a message object with a subtype of message_deleted. It will be the last item in the list. If you would like to see the original message content as it was first posted, it can be found in the previous object of the message's earliest edit.
{
"ok": true,
"message": {
"type": "deleted"
},
"edits": [
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521123.000000",
"text": "Can we reschedule today's meeting? I have a conflict.",
"previous": {
"text": "Can we reschedule today's meeting?"
},
"original_ts": "1569520591.000500",
"subtype": "message_changed",
"editor_id": "W123ABC456"
},
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521616.000000",
"text": "Never mind, I was able to move my other meeting. See you soon.",
"previous": {
"text": "Can we reschedule today's meeting? I have a conflict."
},
"original_ts": "1569520591.000500",
"subtype": "message_changed",
"editor_id": "W123ABC456"
},
{
"type": "message",
"user": "W123ABC456",
"upload": false,
"ts": "1569521860.000000",
"text": "",
"previous": {
"text": "Never mind, I was able to move my other meeting. See you soon."
},
"original_ts": "1569520591.000500",
"subtype": "message_deleted",
"editor_id": "W123ABC456"
}
]
}
oversight.chat.delete
This method deletes a single message.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"ts": "1569520591.000500",
"channel": "C0123ABC456",
"team": "T123ABC456"
}
Example response
oversight.chat.tombstone
This method tombstones a single message, removing the message content but preserving the message's existence. The tombstone message can be customized with the content argument.
Example request
{
"token": "xxxx-xxxxxxxxx-xxxx",
"ts": "1569520591.000500",
"channel": "C0123ABC456",
"team": "T123ABC456",
"content": "This message is currently being reviewed by XYZ Company"
}
Example response
oversight.chat.restore
This method restores a tombstone message.
Example request
{
"ts": "1569520591.000500",
"channel": "C0123ABC456",
"team": "T123ABC456",
}
Example response
oversight.chat.restore
This method allows a message to be updated. This method specifies text or attachments that should be included in place of the message. Parse mode: full. Use this method for quarantine and restoration. Present your key/value pairs according to RFC-3986.
Example request
{
"ts": "1569520591.000500",
"channel": "C0123ABC456",
"team": "T123ABC456",
"Text": "This message has been quarantined per DLP Policy 2.1.1"
}