Skip to main content

Managing invite requests

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

The features within are only available to Slack workspaces on Enterprise Grid plans.

Don't have a paid plan? Join the Developer Program and provision a fully-featured sandbox for free.

By default, Slack users can invite other users into their Slack workspace and Enterprise Grid org, either as a guest or full member.

You can restrict who can invite users, however. When the Invite Request approval setting is turned on, users need to request invitations for other people. Those invitation requests can be approved or denied by a workspace owner or admin.

That process can be time-consuming. Instead, use the invite request management APIs to build an app that gracefully approves and denies invite requests across all workspaces in your Enterprise Grid org.

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

Scopes​

Two scopes allow an app to manage invite requests across an Enterprise Grid org:

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

When an application subscribed to the invite_requested event is installed to an org, workspace owners and admins will no longer receive invite notifications from Slackbot.

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.

Approve, deny, and manage requests​

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​

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

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

Deny a request​

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

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

Manage requests​

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

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 admin.inviteRequests.approved.list method:

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.