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:
| Method | Arguments honoured | Notes |
|---|---|---|
auth.test | — | Returns url, team, user, team_id, user_id, bot_id. Bolt calls this before it will start. |
chat.postMessage | channel, text, blocks, thread_ts | Returns ok, channel, ts, and this server's own message object. |
views.open | trigger_id, view | Returns ok and view with id, callback_id, external_id, hash and the stack's ids. |
views.push | trigger_id, view | As views.open. |
views.update | view_id or external_id, view, hash | As 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#
channelis a channel id or#name. A user id is not accepted: this does not open a direct message, and answerschannel_not_found.- It needs
chat:write. Posting to a public channel the bot has not been added to also needschat:write.public, as on Slack, and answersnot_in_channelwith"needed": "chat:write.public"otherwise. A private channel or group conversation needs the bot in it, and answersnot_in_channelotherwise. textwins when bothtextandblocksare given, though the buttons inblocksare still drawn;blocksalone are turned into text (see Block Kit).- A
thread_tsthat 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_mediaandmetadata.
| Error | When |
|---|---|
invalid_auth | The token is missing, unknown, replaced, or its app is deactivated |
missing_scope | The app does not have chat:write |
channel_not_found | No such channel, or it is archived |
not_in_channel | A conversation the bot has not been added to, as above |
no_text | Neither 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.
| Error | When |
|---|---|
invalid_auth | As for chat.postMessage |
expired_trigger_id | Unknown, used, or older than three minutes — or its room has closed |
trigger_not_yours | Issued to a different app |
unsupported_elements | Every input in the view was a kind this server cannot draw |
no_inputs | The view has neither inputs nor text |
duplicate_external_id | Another 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.
| Error | When |
|---|---|
invalid_auth | As for chat.postMessage |
not_found | No open view of this app by that id or name — or its room has closed |
hash_conflict | The view changed after the hash was given |
unsupported_elements | As for views.open |
no_inputs | As for views.open |
duplicate_external_id | Another of the app's open views has that external_id |