Go to Slack

Managing invite requests

The rundown
Read this if:You're working with Enterprise Grid or multiple workspaces.
Read first:Managing app approvals
Read next:Recent Updates

Sometimes, a Slack user in an Enterprise Grid organization needs to talk to someone who isn't a member of their workspace, and may not be a member of the Grid org at all. So what happens when a Slack user wants to invite that friend into their Slack workspace and Grid org, as a guest or full member?

If sending invitations is restricted to Workspace Owners and Admins, Slack users can request invitations for other people.

Then, your Enterprise Grid organization can use an app to gracefully handle workspace invite requests.

Your app can approve requested invites across all workspaces in your Grid org, allowing admins to focus on the more important things.

You can use any logic you'd like to determine whether to approve a Requite (that's Request Invite in shortened form). And, if a Requite is unrequited, your app can also deny the request safely.

Read on for all the details on the invite request management APIs.


Overview

Slack users in an Enterprise Grid organization can invite others into a workspace.

When the Invite Request approval setting is turned on, admins have the ability to approve or deny requests to invite a new person into a workspaces.

The flow for inviting a new user to a workspace is simple:

Flow for inviting a new user to a workspace

However, the process of approving new users across every workspace in a large Enterprise Grid org can be time-consuming. We made the invite request management APIs so that an app can handle that task.

This API may only be used by Enterprise Grid orgs.


Scopes

Two scopes allow an app to manage invite requests across an Enterprise Grid org: admin.invites:read and admin.invites:write.

All admin.* scopes are obtained using the normal OAuth flow, but there are a few extra requirements. The OAuth installation must be initiated by an Enterprise Grid admin or owner. Also, the install must take place on the Enterprise Grid org, not on an individual workspace using the workspace switcher during the install flow.

Installing the app on a workspace

Check out the scope documentation for more detail.


Listen for the invite_requested event

Now that you're setup with the scopes needed to handle invite requests, it's time to listen for requests. The invite_requested event from the Events API notifies your app when a user makes a request to invite someone new to a workspace.

Subscribe to the invite_requested event by navigating to your App page and clicking on Event Subscriptions in the left sidebar. The Add Workspace Event button will lead you to the invite_requested event. You'll need to reinstall your app for your subscription to take effect.

Here's the outline of an invite_requested event:

{
    "type": "invite_requested",
    "invite_request": {
        "id": string,
        "email": string,
        "date_created": int,
        "requester_ids": [string],
        "channel_ids": [string],
        "invite_type": string,
        "real_name": string,
        "date_expire": int,
        "request_reason": string,
        "team": {
            "id": string,
            "name": string,
            "domain": string
        }
    }
}

A few nuances on those fields inside the invite_request object you'll find in the event payload:

  • email is the email of the new, invited user.
  • invite_type indicates whether the user is a multi-channel guest, a single-channel guest, or full member. It accepts either the string restricted, ultra_restricted, or full_member corresponding to those three types of channel members.

Manage with approve and deny methods

Armed with the id of the invite_request object you received in the above event, your app is ready to approve or deny a request.

Approve a request to invite someone into a workspace with the approve method:

curl -F token=xoxp-... -F team_id=T9876 -F invite_request_id=1234 https://slack.com/api/admin.inviteRequests.approve

Alternatively, if that request invite is not requited by your admins, deny it with the deny method:

curl -F token=xoxp-... -F team_id=T9876 -F invite_request_id=1234 https://slack.com/api/admin.inviteRequests.deny

Lost your place? You can list the pending request invites in a specific workspace with the list method for pending request invites:

curl -F token=xoxp-... -F team_id=T9876 https://slack.com/api/admin.inviteRequests.list

You'll receive a response containing a list of invite_requests, each of which is identical to what's found in the invite_requested event payload described above.

And, finally, if you want to know which requests have been approved or denied, you can use the corresponding list method for approved or denied invites:

curl -F token=xoxp-... -F team_id=T9876 https://slack.com/api/admin.inviteRequests.approved.list
curl -F token=xoxp-... -F team_id=T9876 https://slack.com/api/admin.inviteRequests.denied.list

Parting words of wisdom

The more partners who partake in a Slack conversation, the more productive Slack can be. Let your users bring their +1s to the party, while retaining the peace of mind afforded by admin approval of invites.

Use the invite request management APIs to gracefully approve or deny invite requests. Spare your Grid admins time and focus. Plus, users win too: they get an immediate response, rather than waiting until an admin can carve out time for approvals.

If you love streamlining the Slack admin experience, read up on our other APIs for workspace management.