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.

• admin.conversations:read
• admin.users:read
• admin.teams:read
• admin.chat:read
• admin.chat:write

Methods

Enterprise and users

Use these methods to gather basic information about the Enterprise Grid organization and its members.

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

Individual messages

Use this method to collect a complete history for a single message.

Tombstone and Deleting Messages

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.

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "limit": 1,
  "cursor": "cGFnZToz"
}

Example Response

{
  "ok": true,
  "enterprise": {
    "id": "E0123ABC456",
    "name": "top-level",
    "domain": "top-level",
    "email_domain": "top-level.com",
    "icon": {
      "image_34": "...",
      "image_44": "...",
      "image_68": "...",
      "image_88": "...",
      "image_102": "...",
      "image_132": "...",
      "image_230": "...",
      "image_default": true
    },
    "teams": [
      {
        "id": "T123ABC456",
        "name": "first-workspace",
        "domain": "first-workspace",
        "email_domain": "first-workspace.com",
        "icon": {
          "image_34": "...",
          "image_44": "...",
          "image_68": "...",
          "image_88": "...",
          "image_102": "...",
          "image_132": "...",
          "image_230": "...",
          "image_default": true
        }
      },
      {
        "id": "T222ABC456",
        "name": "second-workspace",
        "domain": "second-workspace",
        "email_domain": "second-workspace.com",
        "icon": {
          "image_34": "...",
          "image_44": "...",
          "image_68": "...",
          "image_88": "...",
          "image_102": "...",
          "image_132": "...",
          "image_230": "...",
          "image_default": true
        }
      }
    ]
  },
  "response_metadata": {
    "next_cursor": "cGFnZToy"
  }
}

Errors

Return to method list

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

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "include_deleted": true,
  "offset": "W0123ABC456"
}

Example Response

{
  "ok": true,
  "users": [
    {
      "id": "W0123ABC4456",
      "name": "somebody",
      "deleted": false,
      "color": "",
      "real_name": "",
      "tz": "America/Los_Angeles",
      "tz_label": "Pacific Daylight Time",
      "tz_offset": -25200,
      "profile": {
        "avatar_hash": "g54b238ed12b",
        "real_name": "",
        "real_name_normalized": "",
        "full_name_normalized": "",
        "preferred_name_normalized": "",
        "email": "nobody@gmail.com",
        "image_24": "...",
        "image_32": "...",
        "image_48": "...",
        "image_72": "...",
        "image_192": "...",
        "image_512": "..."
      },
      "is_admin": true,
      "is_owner": true,
      "is_primary_owner": true,
      "is_restricted": false,
      "is_ultra_restricted": false,
      "is_bot": false,
      "teams": [
        "T123ABC456",
        "T0680URAL"
      ]
    },
    {
        "id": "W222ABC456",
        "name": "username",
        "deleted": false,
        "color": "",
        "real_name": "Firstname Lastname",
        "tz": "America/Los_Angeles",
        "tz_label": "Pacific Daylight Time",
        "tz_offset": -25200,
        "profile": {
            "title": "Multi-lateral user-facing approach",
            "phone": "",
            "skype": "",
            "real_name": "Firstname Lastname",
            "real_name_normalized": "Firstname Lastname",
            "display_name": "firstnamelastname",
            "display_name_normalized": "firstnamelastname",
            "fields": {
                "XfBF8BDQ8N": {
                    "value": "Custom profile field",
                    "alt": ""
                }
            },
            "status_text": "",
            "status_emoji": "",
            "status_expiration": 0,
            "avatar_hash": "g667f1ee796d",
            "email": "firstnamelastname@gmail.com",
            "first_name": "Firstname",
            "last_name": "Lastname",
            "image_24": "...",
            "image_32": "...",
            "image_48": "...",
            "image_72": "...",
            "image_192": "...",
            "image_512": "...",
            "status_text_canonical": "",
            "team": "EA604CA10"
        },
        "is_admin": false,
        "is_owner": false,
        "is_primary_owner": false,
        "is_restricted": false,
        "is_ultra_restricted": false,
        "is_bot": false,
        "is_app_user": false,
        "updated": 1548973372,
        "teams": [
          "T123ABC456",
          "TXXXXXX123"
        ]
    },
  ],
  "response_metadata": {
    "next_cursor": {"ASB1035D"}
  }
}

Errors

Return to method list

oversight.user.info

This method returns information on a single user on Enterprise Grid.

Facts

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

{
  "ok": true,
  "user": {
    "id": "W0123ABC456",
    "name": "somebody",
    "deleted": false,
    "real_name": "",
    "profile": {
      "avatar_hash": "g54b238ed12b",
      "real_name": "",
      "real_name_normalized": "",
      "full_name_normalized": "",
      "preferred_name_normalized": "",
      "email": "name@domain.com",
      "image_24": "...",
      "image_32": "...",
      "image_48": "...",
      "image_72": "...",
      "image_192": "...",
      "image_512": "..."
    },
    "is_admin": true,
    "is_owner": true,
    "is_primary_owner": true,
    "is_restricted": false,
    "is_ultra_restricted": false,
    "is_bot": false,
    "teams": [
      "T123ABC456",
      "TXXXXXX123"
    ]
  }
}

Errors

Return to method list

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.

Facts

Example Default Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "user": "W0123ABC456"
}

Example Default Response

{
  "ok": true,
  "offset": "C123ABC098",
  "channels": [
    {
      "id": "G0123ABC456",
      "team_id": "T0123ABC456",
      "date_joined": 1538411458,
      "date_left": 0,
      "is_private": true,
      "is_im": false,
      "is_mpim": false,
      "is_ext_shared": false
    },
    {
      "id": "D0123ABC456",
      "team_id": "E0123ABC456",
      "date_joined": 1538411250,
      "date_left": 0,
      "is_private": true,
      "is_im": true,
      "is_mpim": false,
      "is_ext_shared": false
    }
  ],
  "response_metadata": {
    "next_cursor": "cGFnZToy"
  }
}

Errors

Return to method list

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.

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "team": "T0123ABC456",
  "offset": "G0QPJB83S"
}

Example Response

{
  "ok": true,
  "channels": [
    {
      "id": "C123ABC456",
      "name": "project-x",
      "created": 1532393077,
      "is_ext_shared": true,
      "is_private": false,
      "is_mpim": false,
      "is_im": false,
      "is_deleted": false,
      "is_archived": false,
      "is_general": false,
      "topic": {
          "text": "This is the topic",
          "set_by": "W0123ABC456",
          "date_set": 1532394000
      },
      "purpose": {
          "text": "This is the purpose",
          "set_by": "W0123ABC456",
          "date_set": 1532399999
      }
    },
    {
      "id": "C222ABC456",
      "name": "project-y",
      "created": 1533204077,
      "is_ext_shared": false,
      "is_private": true,
      "is_mpim": false,
      "is_im": false,
      "is_deleted": false,
      "is_archived": false,
      "is_general": false,
      "topic": {
          "text": "",
          "set_by": "",
          "date_set": 0
      },
      "purpose": {
          "text": "",
          "set_by": "",
          "date_set": 0
      }
    },
    {
      "id": "G0DEF456",
      "name": "mpdm-primary-owner--first.person--second.person",
      "created": 1574793332,
      "is_ext_shared": false,
      "is_private": true,
      "is_im": false,
      "is_mpim": true,
      "is_deleted": false,
      "is_archived": false
      "is_general": false,
      "topic": {
          "text": "",
          "set_by": "",
          "date_set": 0
      },
      "purpose": {
          "text": "",
          "set_by": "",
          "date_set": 0
      }
   },
   {
      "id": "D0GHI789",
      "name": "D0GHI789",
      "created": 1572908387,
      "is_ext_shared": false,
      "is_private": true,
      "is_im": true,
      "is_mpim": false,
      "is_deleted": false,
      "is_archived": false
      "is_general": false,
      "topic": {
          "text": "",
          "set_by": "",
          "date_set": 0
      },
      "purpose": {
          "text": "",
          "set_by": "",
          "date_set": 0
      }
   }
  ],
  "response_metadata": {
    "next_cursor": "cGFnZToy"
  }
}

Errors

Return to method list

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.

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "channel": "G0123ABC456",
  "team": "T0123ABC456"
}

Example Response

{
  "ok" : true,
  "info" : [
    {
      "id": "C123ABC456",
      "name": "project-x",
      "created": 1532393077,
      "is_archived": false,
      "is_general": false,
      "unlinked": 0,
      "creator": "W0123ABC456",
      "name_normalized": "project-x",
      "is_moved": 0,
      "is_shared": true,
      "is_global_shared": false,
      "is_org_default": false,
      "is_org_mandatory": false,
      "is_org_shared": true,
      "is_private": false,
      "is_mpim": false,
      "is_im": false,
      "previous_names": ["project-y"],
      "is_deleted": false,
      "member_count": 52,
      "purpose" : {
          "text": "Collaboration about Project X",
          "set_by": "W0123ABC456",
          "date_set": 1532393077
      },
      "topic" : {
          "text": "Launch date scheduled for 07/01",
          "set_by": "W0MLS082D",
          "date_set": 1533493077
      },
      "retention" : {
          "type": "custom",
          "duration": "360"
      },
      "shared": {
          "shared_team_ids": [
              "T02NFGBSH"
          ],
          "connected_team_ids": [
              "T1BCMSY04"
          ],
          "internal_team_ids": []
      }
    }
  ]
}

Errors

Return to method list

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.

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "channel": "G0123ABC456",
  "team": "T0123ABC456",
  "limit": 4,
  "offset": "W123ABC456",
  "include_member_left": true
}

Example Response

{
    "ok": true,
    "members": [
        {
            "id": "W123ABC456",
            "is_external": true,
            "date_joined": 1559172886,
            "date_left": 0,
            "team": "T123ABC456"
        },
        {
            "id": "W222222",
            "is_external": true,
            "date_joined": 1559172611,
            "date_left": 0,
            "team": "T123ABC456"
        },
        {
            "id": "W333333",
            "is_external": false,
            "date_joined": 1559172328,
            "date_left": 1561739765,
            "team": "T123ABC456"
        },
        {
            "id": "W444444",
            "is_external": false,
            "date_joined": 1561739686,
            "date_left": 0,
            "team": "T123ABC456"
        }
    ],
  "response_metadata": {
    "next_cursor": "cGFnZToy"
  }
}

Errors

Return to method list

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.

Facts

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

Errors

Return to method list

oversight.chat.delete

This method deletes a single message.

Facts

Example Request

{
  "token": "xxxx-xxxxxxxxx-xxxx",
  "ts": "1569520591.000500",
  "channel": "C0123ABC456",
  "team": "T123ABC456"
}

Example Response

{
    "ok": true,
    "ts": "1569520591.000500"
}

Errors

Return to method list

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.

Facts

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

{
    "ok": true,
    "message": {
        "type": "message",
        "subtype": "dlp_tombstone",
        "ts": "1587006080.000700",
        "text": "\"This message is currently being reviewed by XYZ Company\"",
        "user": "U123ABC456"
    }
}

Errors

Return to method list

oversight.chat.restore

This method restores a tombstone message.

Facts

Example Request

{
  "ts": "1569520591.000500",
  "channel": "C0123ABC456",
  "team": "T123ABC456",
}

Example Response

{
    "ok": true,
    "message": {
        "type": "message",
        "ts": "1587006080.000700",
        "text": "Original message that might contain a policy violation.",
        "user": "WXXXXXXXXX"
    }
}

Errors

Return to method list

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.

Facts

Example Request

{
  "ts": "1569520591.000500",
  "channel": "C0123ABC456",
  "team": "T123ABC456",
  "Text": "This message has been quarantined per DLP Policy 2.1.1"
}

Example Response

{
    "ok": true,
    "message": {
        "type": "message",
        "ts": "1587006080.000700",
        "text": "Original message that might contain a policy violation.",
        "user": "WXXXXXXXXX"
    }
}

Errors

Return to method list