Events and Socket Mode
Instant tells your bot what happens where it is, in Slack’s Events API format, at a URL you choose or over a WebSocket your bot opens.
The Events URL
On the bot’s page, set the Events URL and tick the events it wants. When you save, Instant sends Slack’s challenge and expects it back within 3 seconds:
{ "type": "url_verification", "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P" }Answer with the challenge as JSON ({"challenge": "…"}) or plain text. Bolt does it for you. After that, events come as Slack’s event_callback:
{
"type": "event_callback",
"team_id": "ws_…",
"api_app_id": "bot_…",
"event_id": "ev_…",
"event_time": 1763600000,
"authorizations": [{ "team_id": "ws_…", "user_id": "usr_…", "is_bot": true }],
"event": {
"type": "message",
"channel": "ch_…",
"channel_type": "channel",
"user": "usr_…",
"text": "Ship it <@usr_…>",
"ts": "msg_…",
"event_ts": "msg_…"
}
}Answer any 2xx within 3 seconds, then do the slow work. A message in a thread has thread_ts; files come as files, each with a url_private the bot downloads with its token and files:read.
Events
A bot never hears about its own messages or reactions. Each event also needs the bot to be where it happened, and the scopes listed.
| Event | When | Needs |
|---|---|---|
message | A message in a channel or DM the bot is in. Edits come as subtype: "message_changed" with the new message; deletions as subtype: "message_deleted" with deleted_ts. | channels:history (channels) or im:history (DMs) |
app_mention | Someone writes <@bot> in a channel or DM the bot is in. | app_mentions:read |
reaction_added, reaction_removed | Someone reacts to a message where the bot is. reaction is the emoji’s Slack name; item points at the message. | |
member_joined_channel, member_left_channel | People come and go, including the bot itself. inviter says who added them. | |
link_shared | Someone shares a link to one of the bot’s unfurl domains. See Unfurls. | links:read |
app_home_opened | Someone opens the bot’s Home tab. See App Home. |
Verify Each Request
Every event, slash command and click is signed with the bot’s signing secret, exactly as Slack signs: v0= and the hex HMAC-SHA256 of v0:<timestamp>:<raw body>. The headers come twice, as X-Instant-Signature and X-Instant-Request-Timestamp, and under Slack’s names, so Bolt checks them unchanged. Without Bolt:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verified(headers, rawBody, secret) {
const ts = headers['x-instant-request-timestamp'];
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes: a replay
const mine = Buffer.from('v0=' + createHmac('sha256', secret).update(`v0:${ts}:${rawBody}`).digest('hex'));
const theirs = Buffer.from(String(headers['x-instant-signature'] ?? ''));
return mine.length === theirs.length && timingSafeEqual(mine, theirs);
}Rotate Signing Secret on the bot’s page makes a new one and stops the old one at once, as on Slack, so deploy the new secret right after.
Retries
- An event that doesn’t get a
2xxwithin 3 seconds is tried again after a second, then 1, 5, 30, 120 and 360 minutes after the first try, then dropped. - Retries carry
X-Slack-Retry-Num(andX-Instant-Retry-Num): 1, 2, 3…. Order isn’t kept across retries, so drop repeats byevent_id. - A
4xxanswer other than429means “don’t send this again” and isn’t retried. - After 50 failed deliveries in a row, events pause and the bot’s page says so. Saving the Events URL again resumes them.
Socket Mode
No public URL, or a bot behind a firewall? Turn on Socket Mode on the bot’s page. Events, slash commands, clicks and form submissions then come over a WebSocket your bot opens, and the URLs on the bot’s page are ignored.
With Bolt, use the bot token as the app token too (Instant has no separate app-level token), and point the socket’s own client at Instant through installerOptions:
app.js
import bolt from '@slack/bolt';
const token = process.env.INSTANT_BOT_TOKEN;
const api = { slackApiUrl: 'https://api.instant.im/api/' };
const app = new bolt.App({
token,
appToken: token,
socketMode: true,
clientOptions: api,
installerOptions: { clientOptions: api }, // where the socket calls apps.connections.open
});
app.event('app_mention', async ({ event, say }) => {
await say({ thread_ts: event.ts, text: 'On it!' });
});
await app.start();Without Bolt: call apps.connections.open with the bot token. It answers {"ok": true, "url": "wss://…"}, good for 30 seconds and one connection. The first frame is Slack’s {"type": "hello"}; after that each frame is an envelope:
{ "envelope_id": "…", "type": "events_api", "accepts_response_payload": false, "payload": { "type": "event_callback", … } }typeisevents_api,slash_commandsorinteractive(clicks, shortcuts and form submissions).- Ack each one within 3 seconds by sending back
{"envelope_id": "…"}, with apayloadto answer a slash command or a form. - An event that isn’t acked is retried like a failed delivery. A command or click while the bot isn’t connected tells the person the bot isn’t connected right now.
- A bot can hold up to 10 connections; the newest gets each envelope. Turning Socket Mode off closes them.