Docs / Integration API contract

Web API methods

Methods are called at https://<server>/api/<method>, as POST, with the token as Authorization: Bearer xoxb-… or as a token field in the body. A body can be JSON or form-encoded; in a form, a structured argument such as blocks or view is a JSON string, which is how Slack's SDK sends every call.

As on Slack, a call that fails is answered with HTTP 200 and {"ok": false, "error": "<code>"}. Slack's SDK treats any other status as a failure to connect and never reads the error code, so this matters more than it looks. The one exception is rate limiting: 429 with a Retry-After header, which the SDK understands.

The supported methods — checked:

MethodArguments honouredNotes
auth.test—Returns url, team, user, team_id, user_id, bot_id. Bolt calls this before it will start.
chat.postMessagechannel, text, blocks, thread_tsReturns ok, channel, ts, and this server's own message object.
views.opentrigger_id, viewReturns ok and view with id, callback_id, external_id, hash and the stack's ids.
views.pushtrigger_id, viewAs views.open.
views.updateview_id or external_id, view, hashAs views.open.

Any other method answers unknown_method. That includes chat.update, chat.delete, chat.postEphemeral, conversations.*, users.*, reactions.*, files.*, views.publish, and apps.connections.open — so Socket Mode is not supported; an app receives events and interactions over HTTP.

chat.postMessage#

  • channel is a channel id or #name. A user id is not accepted: this does not open a direct message, and answers channel_not_found.
  • It needs chat:write. Posting to a public channel the bot has not been added to also needs chat:write.public, as on Slack, and answers not_in_channel with "needed": "chat:write.public" otherwise. A private channel or group conversation needs the bot in it, and answers not_in_channel otherwise.
  • text wins when both text and blocks are given, though the buttons in blocks are still drawn; blocks alone are turned into text (see Block Kit).
  • A thread_ts that is not the first message of a thread in that channel is ignored, and the message is posted to the channel.
  • Not honoured: attachments, username, icon_emoji, icon_url, as_user, reply_broadcast, mrkdwn, parse, link_names, unfurl_links, unfurl_media and metadata.
ErrorWhen
invalid_authThe token is missing, unknown, replaced, or its app is deactivated
missing_scopeThe app does not have chat:write
channel_not_foundNo such channel, or it is archived
not_in_channelA conversation the bot has not been added to, as above
no_textNeither text nor blocks produced anything to post

views.open#

A trigger_id comes with a slash command, a button press or a form submission. It lasts three minutes (Slack's last three seconds, which is unkind to an app on a cold start), opens one view, and belongs to the app it was issued to and the person whose action produced it. The view is shown only to that person.

A person has one stack of forms open at a time, as the client shows one: opening a view closes whatever they had open, from this app or another. What a view can contain is described under Modals. A view may hold only text, with no inputs, such as "Loading" or "Done"; it has no submit button unless it names one.

external_id names a view for views.update, and must be unique among the app's open views. The hash in the answer changes every time the view does.

ErrorWhen
invalid_authAs for chat.postMessage
expired_trigger_idUnknown, used, or older than three minutes — or its room has closed
trigger_not_yoursIssued to a different app
unsupported_elementsEvery input in the view was a kind this server cannot draw
no_inputsThe view has neither inputs nor text
duplicate_external_idAnother of the app's open views has that external_id

views.push#

Puts a view on top of the one the person has open from this app, as on Slack: closing or submitting it goes back to the one under it. At most three views stack. If the person has no view of this app open, it opens as views.open would. The trigger is spent the same way.

Errors are those of views.open, and push_limit_reached when three are open.

views.update#

Changes a view the person still has open, anywhere in the stack, without a trigger: the usual way to answer at once with "Loading" and show the real form when the app has it. Name the view by view_id or by external_id. An input that keeps its block_id and action_id keeps what the person entered in it, as on Slack.

Pass the hash from the last answer to refuse the change if the view has changed since, so two updates cannot overwrite each other. It also refreshes the view's thirty minutes. An app that updates views in a loop is limited as a posting app is, with 429 and Retry-After.

ErrorWhen
invalid_authAs for chat.postMessage
not_foundNo open view of this app by that id or name — or its room has closed
hash_conflictThe view changed after the hash was given
unsupported_elementsAs for views.open
no_inputsAs for views.open
duplicate_external_idAnother of the app's open views has that external_id

This page is made from docs/INTEGRATIONS.md.