Developers
Bots are teammates here.
A bot in Instant has a name, a face and a seat. You mention it, DM it and add it to channels like anyone else. Its API speaks Slack’s language, so the bot you already have can move in this afternoon.
Bots Are Members
Every bot shows in the member list with a Bot badge, and only reads the channels someone added it to.
Slack-Compatible
Point your Slack SDK at Instant and use an Instant token. Methods, events, signatures and slash commands keep Slack’s shapes.
Scoped and Audited
Tokens are hashed, scoped and rate limited. Admins choose who can make bots, and every change lands in the audit log.
Make a Bot
In Instant, open Settings › Bots & Apps and choose New Bot. Give it a name and a picture, and copy its token: it starts with ib_ and is shown once. Then add the bot to a channel from its page or with /invite @Bot.
A bot is a seat on your plan, the same as a person, because it reads and posts like one.
curl https://api.instant.im/api/chat.postMessage \
-H "Authorization: Bearer $INSTANT_BOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"channel": "ch_…", "text": "Hello from my bot"}'Port a Slack Bot
Set the API URL to https://api.instant.im/api/, swap in the Instant bot token and signing secret, and point your events and slash command URLs at the same app. With Bolt for JavaScript:
import { App } from '@slack/bolt';
const app = new App({
token: process.env.INSTANT_BOT_TOKEN,
signingSecret: process.env.INSTANT_SIGNING_SECRET,
clientOptions: { slackApiUrl: 'https://api.instant.im/api/' },
});
app.event('app_mention', async ({ event, say }) => {
await say({ text: 'On it!', thread_ts: event.ts });
});
app.command('/weather', async ({ command, ack, respond }) => {
await ack();
await respond({ text: `Sunny in ${command.text || 'your city'}` });
});Channel, user and message ids are Instant’s own, and a message’s ts is its id. Bots treat them as opaque strings anyway, so code that passes them back works unchanged. blocks are shown as text for now; buttons and modals come later.
Methods
Send form fields or JSON to https://api.instant.im/api/<method>. Answers are Slack’s: {"ok": true, …}, or {"ok": false, "error": "channel_not_found"}.
auth.test chat.postMessage chat.update chat.delete chat.postEphemeral chat.getPermalink reactions.add reactions.remove reactions.get pins.add pins.remove conversations.list conversations.info conversations.history conversations.replies conversations.members conversations.open conversations.mark users.conversations users.list users.info
The same token also works on Instant’s own REST API at https://api.instant.im/v1, limited to the routes each scope allows.
Scopes
New bots start with the everyday scopes on. A call outside its scopes answers missing_scope.
| Scope | Allows |
|---|---|
chat:write | Post, edit and delete its own messages in channels and DMs it is in |
channels:read | List channels, read their info and who is in them |
channels:history | Read messages and threads in channels it is in |
im:history | Read DMs it is in |
im:write | Open a DM with someone |
reactions:write | Add and remove its reactions |
reactions:read | Get reaction events |
users:read | List members and read profiles |
users:read.email | See members’ emails |
files:write | Upload files and attach them to messages |
files:read | Download files posted where it is |
pins:write | Pin and unpin messages |
commands | Answer slash commands |
app_mentions:read | Get app_mention events |
Events
Give the bot an events URL and Instant sends Slack’s event_callback envelopes there. When you save the URL it gets a url_verification challenge to echo back.
| Event | When |
|---|---|
message | A message in a channel or DM the bot is in, plus message_changed and message_deleted subtypes |
app_mention | Someone @mentions the bot |
reaction_added, reaction_removed | Someone reacts to a message where the bot is |
member_joined_channel, member_left_channel | People come and go, including the bot itself |
Verify Requests
Every event and slash command is signed with the bot’s signing secret, the way Slack signs them: v0= and the hex HMAC-SHA256 of v0:<timestamp>:<body>. Instant sends it as X-Instant-Signature and X-Instant-Request-Timestamp, and under Slack’s header names too, so Bolt’s check works as it is.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verified(req, rawBody, secret) {
const ts = req.headers['x-instant-request-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const mine = 'v0=' + createHmac('sha256', secret).update(`v0:${ts}:${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(mine), Buffer.from(req.headers['x-instant-signature']));
}Slash Commands
Add commands on the bot’s page: a name, a short description, a usage hint and the URL to call. They show in everyone’s / menu with the bot’s face. Instant posts Slack’s form payload with a response_url. Answer within 3 seconds with {"text": "…"} to reply only to the person, or add "response_type": "in_channel" to post for everyone. Use the response_url for up to 30 minutes to say more.
Limits
Each bot can make 120 calls a minute; past that the API answers 429 with Retry-After. Events are tried three times, and after 50 failed deliveries in a row they pause until you save the URL again. A bot can have two live tokens at once, so you can rotate without downtime.
Questions
Email support@instant.im. We read everything.
Build your first bot.
Make a bot in Settings › Bots & Apps and post your first message in a minute.