examples/functions/slack-notify/README.md
Content teams need to stay informed when new content is created, but manually notifying team members about new posts is time-consuming and often forgotten. Teams want automatic notifications that include relevant details and quick access links to both the published content and the studio for further editing.
This function automatically sends Slack notifications when content is published using Sanity's document functions and the Slack Web API. When triggered, it sends a formatted message to a designated Slack channel with the post title, publication date, and convenient links to both the published webpage and the studio editor.
This function is built to be compatible with any of the official "clean" templates that include post documents with title and slug fields. We recommend testing the function out in one of those after you have installed them locally.
This function expects your post schema to include:
title field (string)slug field (slug type with current property)Most official templates already include these fields.
Set up Slack Integration
First, create a Slack app and get an OAuth token:
Create a new Slack app:
Configure permissions:
chat:write permission (this allows your bot to send messages).Install the app:
xoxb- (you'll need this for the next step)Invite the app to your channel:
#test-channel)/invite @your-app-name or click the channel name → Settings → Integrations → Add appsInitialize the example
Run this if you haven't initialized blueprints:
npx sanity blueprints init
You'll be prompted to select your organization and Sanity studio.
Then run:
npx sanity blueprints add function --example slack-notify
Add configuration to your blueprint
// sanity.blueprint.ts
import 'dotenv/config'
import process from 'node:process'
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: 'slack-notify',
src: './functions/slack-notify',
memory: 1,
timeout: 10,
event: {
on: ['create'],
filter: "_type == 'post'",
projection: '{_id, title, slug, _createdAt}',
},
env: {
SLACK_OAUTH_TOKEN: process.env.SLACK_OAUTH_TOKEN,
SLACK_CHANNEL: process.env.SLACK_CHANNEL,
BASE_URL: process.env.BASE_URL,
STUDIO_URL: process.env.STUDIO_URL,
},
}),
],
})
Install dependencies
Install dependencies in the project root:
npm install
Configure environment variables
Create a .env file in your project root with the following variables:
# Required
SLACK_OAUTH_TOKEN=xoxb-your-slack-bot-token-here
# Optional (defaults shown)
SLACK_CHANNEL=general
BASE_URL=http://localhost:3000
STUDIO_URL=http://localhost:3333
Required:
SLACK_OAUTH_TOKEN: Your Slack bot OAuth token (starts with xoxb-)Optional:
SLACK_CHANNEL: Slack channel name (default: 'general')BASE_URL: Your website URL (default: 'http://localhost:3000')STUDIO_URL: Your Sanity Studio URL (default: 'http://localhost:3333')You can test the slack-notify function locally using the Sanity CLI before deploying it to production.
Important: This function requires a valid Slack OAuth token and will send real messages to your Slack channel during testing. Make sure you have configured your environment variables (see step 5 above).
Test the function with the created document (from project root):
# If using .env file (recommended)
npx sanity functions test slack-notify \
--file functions/slack-notify/document.json \
--dataset production \
--with-user-token
# Or set environment variables inline
SLACK_OAUTH_TOKEN=xoxb-your-token SLACK_CHANNEL=test-channel \
npx sanity functions test slack-notify \
--file functions/slack-notify/document.json \
--dataset production \
--with-user-token
Alternative: Test with a real document from your dataset:
# From the studio/ folder, find and export an existing post document
cd studio
npx sanity documents query "*[_type == 'post'][0]" > ../real-post.json
# Back to project root for function testing
cd ..
# If using .env file (recommended)
npx sanity functions test slack-notify \
--file real-post.json \
--dataset production \
--with-user-token
# Or set environment variables inline
SLACK_OAUTH_TOKEN=xoxb-your-token SLACK_CHANNEL=test-channel \
npx sanity functions test slack-notify \
--file real-post.json \
--dataset production \
--with-user-token
To test the function logic without actually sending Slack messages, you can temporarily comment out the slack.chat.postMessage call in the function and just log the message that would be sent.
Start the development server for interactive testing:
SLACK_OAUTH_TOKEN=slack-OAuth-token npx sanity functions dev
This opens an interactive playground where you can test functions with custom data.
Once you've tested your function locally and are satisfied with its behavior, you can deploy it to production.
Important: Make sure you have the Deploy Studio permission for your Sanity project before attempting to deploy.
chat:write permissions.Make sure your sanity.blueprint.ts file is properly configured with your function:
// sanity.blueprint.ts
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: 'slack-notify',
src: './functions/slack-notify',
memory: 1,
timeout: 10,
event: {
on: ['create'],
filter: "_type == 'post'",
projection: '{_id, title, slug, _createdAt}',
},
}),
],
})
From your project root, run:
npx sanity blueprints deploy
This command will:
After deployment, you need to add the Slack OAuth token as an environment variable:
npx sanity functions env add slack-notify SLACK_OAUTH_TOKEN "your-slack-oauth-token-here"
Replace "your-slack-oauth-token-here" with your actual Slack OAuth token (the one that starts with xoxb-).
You can verify the environment variable was added successfully:
npx sanity functions env list slack-notify
Learn more about working with environment variables in Functions here: https://www.sanity.io/docs/compute-and-ai/function-env-vars
After deployment, you can verify your function is active by:
npx sanity functions logs slack-notify
Error: "Deploy Studio permission required"
Error: "Blueprint validation failed"
sanity.blueprint.ts configurationError: "Function not sending Slack notifications after deployment"
Error: "Missing environment variable SLACK_OAUTH_TOKEN"
SLACK_OAUTH_TOKEN environment variable in your Sanity project settingsFor more details, see the official function deployment documentation.
chat:write permissionstitle and slug fieldsWhen you create a new post document, the function automatically:
Example Slack message:
*New Document Created!*
Title: Getting Started with Sanity
Webpage: <http://localhost:3000/posts/getting-started-with-sanity|Click Here>
Studio: <http://localhost:3333/structure/post;post-id|Click Here>
DateTime Created: 1/15/2024, 10:30:00 AM
You can customize the notification by modifying the configuration constants at the top of the function:
// Configuration constants
const baseUrl = 'https://your-domain.com' // Update to your production URL
const studioUrl = 'https://your-studio.sanity.studio' // Update to your studio URL
const slackChannel = 'your-channel-name' // Update to your target channel
text: `Your custom message format with ${event.data.title}`,
Include additional fields in the message by accessing event.data.fieldName.
Modify the filter in the blueprint configuration to target different document types or conditions.
Error: "An API error occurred: invalid_auth"
Error: "An API error occurred: channel_not_found"
Error: "Missing environment variable SLACK_OAUTH_TOKEN"
SLACK_OAUTH_TOKEN environment variable with your bot token.Error: "Messages not appearing in Slack"
chat:write permissions