Porting from Slack
Most Slack bots move by changing three settings. This page lists everything else: each method and event, and each place Instant differs.
The Three Changes
- API URL:
https://api.instant.im/api/instead ofhttps://slack.com/api/. - Token and signing secret: the Instant bot’s, from Settings › Bots & Apps.
- URLs: set the bot’s Events URL, Interactivity URL and slash command URLs to the same addresses your Slack app uses (with Bolt, all of them are
/slack/events). Or turn on Socket Mode.
const app = new App({
token: process.env.INSTANT_BOT_TOKEN, // was SLACK_BOT_TOKEN
signingSecret: process.env.INSTANT_SIGNING_SECRET, // was SLACK_SIGNING_SECRET
clientOptions: { slackApiUrl: 'https://api.instant.im/api/' }, // new
});In Python, WebClient(token=…, base_url="https://api.instant.im/api/") and App(client=that_client, signing_secret=…) do the same.
What Stays the Same
- Method names, arguments and answers:
{"ok": true, …}or{"ok": false, "error": "…"}. - The Events API envelope,
url_verification, retries withX-Slack-Retry-Num, and request signing withX-Slack-Signature. - Block Kit buttons and menus in messages,
block_actions,response_urlwithreplace_originalanddelete_original. - Modals:
views.open,push,update,view_submissionwithresponse_action,view_closed. - Slash command payloads,
response_type, global and message shortcuts,link_sharedwithchat.unfurl, and App Home. - Scope names, and Socket Mode envelopes and acks.
What’s Different
- Ids. Channels are
ch_…, peopleusr_…, workspacesws_…. A message’stsis its id,msg_…, not a number: don’t compare or sorttsvalues as times; use the order the API gives. - Where a bot can read. Only channels it was added to, even public ones.
conversations.joinwithchannels:joinlets it join public channels itself. - Blocks. Messages show the words of
header,sectionandcontextblocks, and real buttons and menus. Images, overflow menus, date pickers and multi-selects in messages are skipped, so always sendtext. - Links.
<url|label>shows as “label (url)”. - Name and face. A bot always posts as itself;
usernameand icons are ignored. - Global shortcuts live in the
/menu as/their-name, not in a separate shortcuts menu. - Paging.
conversations.listandusers.listanswer everything on one page;conversations.historypages by cursor only. - Tokens. One bot token does everything: no user tokens (
xoxp) and no app-level tokens (xapp). - One workspace. A bot belongs to the workspace that made it. Installing one app in many workspaces is experimental.
- Rate limits. One budget of 120 calls a minute per bot, not Slack’s tiers per method.
Events
| Slack event | In Instant |
|---|---|
message (and message.channels, message.groups, message.im, message.mpim) | One message event for channels and DMs, with channel_type. Subtypes message_changed and message_deleted. |
app_mention | The same. |
reaction_added, reaction_removed | The same. |
member_joined_channel, member_left_channel | The same. |
link_shared | The same. |
app_home_opened | The same, with tab: "home". |
Others (channel_created, team_join, user_change, …) | Not sent yet. |
Methods
Every Slack method Instant answers. A blank note means it works as on Slack. Anything else answers unknown_method.
| Method | Notes |
|---|---|
api.test | — |
auth.test | Answers team_id, user_id and bot_id as Instant ids. |
team.info | — |
bots.info | — |
apps.connections.open | Takes the bot token (there are no app-level tokens). |
chat.postMessage | username, icon_url and icon_emoji are ignored. Blocks become text, except buttons and menus. |
chat.update | With blocks, replaces the buttons; without, keeps them. |
chat.delete | The bot’s own messages. |
chat.postEphemeral | Never stored: gone after a reload. |
chat.meMessage | — |
chat.getPermalink | — |
chat.scheduleMessage | Up to 120 days ahead; sent within a minute of post_at. |
chat.scheduledMessages.list | The bot’s own. |
chat.deleteScheduledMessage | — |
chat.unfurl | Legacy attachments. See Unfurls. |
reactions.add | — |
reactions.remove | — |
reactions.get | — |
pins.add | — |
pins.remove | — |
pins.list | — |
conversations.list | Only channels the bot is in, on one page. |
conversations.info | — |
conversations.history | Newest first, paged with cursor and limit (up to 200). oldest and latest are ignored. |
conversations.replies | — |
conversations.members | — |
conversations.open | Opens a DM or group DM. Needs im:write. |
conversations.mark | — |
conversations.join | Public channels, with channels:join. |
conversations.leave | — |
conversations.create | With channels:manage. |
conversations.invite | — |
conversations.setTopic | — |
conversations.setPurpose | A channel has one line, so it sets the topic. |
conversations.rename | Channels the bot made. |
conversations.archive | Channels the bot made. |
conversations.unarchive | — |
users.list | Every member on one page. |
users.info | — |
users.conversations | — |
users.lookupByEmail | Needs users:read.email. |
users.profile.get | — |
files.getUploadURLExternal | With files.completeUploadExternal, what files.uploadV2 calls. |
files.completeUploadExternal | — |
files.upload | The older single call. |
files.info | The bot’s own files. |
views.open | — |
views.push | Three forms deep at most. |
views.update | — |
views.publish | Home tabs only. |
oauth.v2.access | Experimental. See Distribution. |
Not Available
rtm.* (Slack retired it), admin.* and Enterprise Grid methods, Workflow Builder steps, user tokens, search.*, reminders.*, usergroups.*, bookmarks.*, dnd.* and calls.