Skip to content
Instant

Developers

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

  1. API URL: https://api.instant.im/api/ instead of https://slack.com/api/.
  2. Token and signing secret: the Instant bot’s, from Settings › Bots & Apps.
  3. 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 with X-Slack-Retry-Num, and request signing with X-Slack-Signature.
  • Block Kit buttons and menus in messages, block_actions, response_url with replace_original and delete_original.
  • Modals: views.open, push, update, view_submission with response_action, view_closed.
  • Slash command payloads, response_type, global and message shortcuts, link_shared with chat.unfurl, and App Home.
  • Scope names, and Socket Mode envelopes and acks.

What’s Different

  • Ids. Channels are ch_…, people usr_…, workspaces ws_…. A message’s ts is its id, msg_…, not a number: don’t compare or sort ts values as times; use the order the API gives.
  • Where a bot can read. Only channels it was added to, even public ones. conversations.join with channels:join lets it join public channels itself.
  • Blocks. Messages show the words of header, section and context blocks, and real buttons and menus. Images, overflow menus, date pickers and multi-selects in messages are skipped, so always send text.
  • Links. <url|label> shows as “label (url)”.
  • Name and face. A bot always posts as itself; username and icons are ignored.
  • Global shortcuts live in the / menu as /their-name, not in a separate shortcuts menu.
  • Paging. conversations.list and users.list answer everything on one page; conversations.history pages 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 eventIn 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_mentionThe same.
reaction_added, reaction_removedThe same.
member_joined_channel, member_left_channelThe same.
link_sharedThe same.
app_home_openedThe 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.

MethodNotes
api.test—
auth.testAnswers team_id, user_id and bot_id as Instant ids.
team.info—
bots.info—
apps.connections.openTakes the bot token (there are no app-level tokens).
chat.postMessageusername, icon_url and icon_emoji are ignored. Blocks become text, except buttons and menus.
chat.updateWith blocks, replaces the buttons; without, keeps them.
chat.deleteThe bot’s own messages.
chat.postEphemeralNever stored: gone after a reload.
chat.meMessage—
chat.getPermalink—
chat.scheduleMessageUp to 120 days ahead; sent within a minute of post_at.
chat.scheduledMessages.listThe bot’s own.
chat.deleteScheduledMessage—
chat.unfurlLegacy attachments. See Unfurls.
reactions.add—
reactions.remove—
reactions.get—
pins.add—
pins.remove—
pins.list—
conversations.listOnly channels the bot is in, on one page.
conversations.info—
conversations.historyNewest first, paged with cursor and limit (up to 200). oldest and latest are ignored.
conversations.replies—
conversations.members—
conversations.openOpens a DM or group DM. Needs im:write.
conversations.mark—
conversations.joinPublic channels, with channels:join.
conversations.leave—
conversations.createWith channels:manage.
conversations.invite—
conversations.setTopic—
conversations.setPurposeA channel has one line, so it sets the topic.
conversations.renameChannels the bot made.
conversations.archiveChannels the bot made.
conversations.unarchive—
users.listEvery member on one page.
users.info—
users.conversations—
users.lookupByEmailNeeds users:read.email.
users.profile.get—
files.getUploadURLExternalWith files.completeUploadExternal, what files.uploadV2 calls.
files.completeUploadExternal—
files.uploadThe older single call.
files.infoThe bot’s own files.
views.open—
views.pushThree forms deep at most.
views.update—
views.publishHome tabs only.
oauth.v2.accessExperimental. 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.

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing