Sending a notification to new users

Use cases:
  • Welcome message for new users
  • Terms of Service for guest accounts
Works with:
  • Events API
  • Block Kit
Code samples:

When a user joins a team, automatically send them a direct message welcoming them and presenting a terms of service they must accept.

How it works

A welcome message sent to a new user

1. Receive a notification when a user joins a team

To find out when a user joins a team we need a Slack app that's subscribed to the team_join event being sent out through the Events API. The Events API sends a POST request to a specified URL whenever certain events occur on a Slack team. In the case of team_join event, Slack will send an event as soon as a new user creates an account on a team. The event will include information about both the team and user. It is sent for bots, guests and full users but with enough information to distinguish between them.

2. If they haven't accepted the terms already, send it to them

When the app receives a team_join event, it'll check a database to confirm whether the user has previously accepted the terms as part of this team or any other team within an Enterprise Grid organization. The database stores the user ID, team/enterprise ID, a boolean for whether they've accepted the terms, and date fields for when the message was sent and accepted. If the user has previously accepted the terms, the app will hold off on sending them a message. If they haven't accepted the terms, the app will add the user to the database and send them a DM using the chat.postMessage API method (which requires the im:write scope). The message includes the terms and a message button with the text 'Agree'. To include the button, you'll need to enable Interactive Messages in the app settings and supply a URL where Slack can send the button click event.

3. Update the user record when they click "Accept"

When the user clicks the "Agree" button in the message, Slack will send a POST request to the provided Interactive Message request URL. This request will include information about who clicked the button as well as a response_url that can be used to update the message the user clicked on. When your app receives this event, it'll find and update the record in the database to indicate that the user has agreed to the terms. By sending a request to the response_url, the app will update the original message to indicate that the terms have been accepted.

4. Periodically check who hasn't accepted the terms

All that's left is to occasionally check who has been sent a message but not yet accepted the terms. You can set up a periodic job to either nag users to accept the terms or you can automatically disable their account through our SCIM API.


How to plumb new user notifcations

Customization suggestions

  • The content of the message that gets sent initially
  • Whether to include an "Accept" button or not
  • Periodically check if people have accepted the message and otherwise remove their access
  • Track the date the terms were last changed and reset all acceptances before that date
  • Configure the message to be sent per-team or only once per Enterprise Grid organization

Other use cases

  • Terms of Service for guest accounts
  • Welcome message for new users
  • Company-specific Slack onboarding

Related documentation

Was this page helpful?