Post a reply (response URL)

POST

api

responses

{token}

curl -X POST "$RESPONSE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{ "label": "Download", "url": "https://example.com/r.pdf" }]
  }'

await fetch(responseUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mid: 'reply-evt_7f3a',
    text: 'Your report is ready 📊',
    buttons: [{ label: 'Download', url: 'https://example.com/r.pdf' }]
  })
})

import requests

requests.post(response_url, json={
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{"label": "Download", "url": "https://example.com/r.pdf"}],
})

{
  "ok": true,
  "messages": [
    { "message_id": "0f8c…", "mid": "reply-evt_7f3a", "updated": false }
  ]
}

{
  "ok": false,
  "error": {
    "code": "RESPONSE_URL_EXPIRED",
    "message": "This response_url has expired — use the bot-level API."
  }
}

Send Block Kit to the response_url from any event, and the message lands in the conversation that created the event. No Authorization header: having the URL is your permission.

Path parameters

string

required

The token baked into the event’s response_url. Use the URL exactly as we sent it. Never build one yourself.

Body

application/json. Any Block Kit shape we accept, up to 256 KB and 10 messages.

array

One to ten messages. Each has blocks (1 to 25) and optional mid and metadata. Shortcuts such as { "text": "…" } are expanded for you.

string

Your own id for the message, matching ^[a-zA-Z0-9_.:-]{1,64}$. Send it again and the message is replaced instead of duplicated. See Updating messages.

A page block in the body publishes a hosted Page in the same call, as long as the conversation is an internal one. To publish without a conversation at all, use the Pages API.

Response

boolean

true on success.

array

One handle per message in your body, in order.

Show properties

string

The stored message.

string | null

The mid you sent, if any.

boolean

true when the mid matched an existing message and replaced it.

curl -X POST "$RESPONSE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{ "label": "Download", "url": "https://example.com/r.pdf" }]
  }'

await fetch(responseUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mid: 'reply-evt_7f3a',
    text: 'Your report is ready 📊',
    buttons: [{ label: 'Download', url: 'https://example.com/r.pdf' }]
  })
})

import requests

requests.post(response_url, json={
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{"label": "Download", "url": "https://example.com/r.pdf"}],
})

{
  "ok": true,
  "messages": [
    { "message_id": "0f8c…", "mid": "reply-evt_7f3a", "updated": false }
  ]
}

{
  "ok": false,
  "error": {
    "code": "RESPONSE_URL_EXPIRED",
    "message": "This response_url has expired — use the bot-level API."
  }
}

Token rules

Rule	Detail
Lifetime	45 minutes from when the event was created.
Reuse	Multi-use until it expires. Post several messages, or update one many times.
Retries	Every retry of one event carries the exact same `response_url`.
Scope	Only the conversation that created the event.
Rate limit	30 requests per minute per token.

Errors

Status	Code	Meaning
`401`	`token_invalid`	The token is broken or has a bad signature.
`402`	`MESSAGE_CAP_REACHED`	The workspace’s monthly message limit is used up.
`404`	`conversation_not_found`	The conversation no longer exists.
`409`	`conversation_taken_over`	A person has taken over. The bot is locked out.
`410`	`RESPONSE_URL_EXPIRED`	Past 45 minutes. Use an API key instead.
`413`	`PAYLOAD_TOO_LARGE`	Body over 256 KB.
`422`	`EMPTY_BODY`	Nothing to post. An empty body is an error here, unlike a webhook reply.
`422`	`FRAMEWORK_DEFAULT_BODY`	You posted `Accepted`, `OK`, or similar.
`422`	`BLOCK_VALIDATION_FAILED`	Bad Block Kit. The `issues` list shows each problem.
`429`	`rate_limited`	Over 30 per minute. Wait for `retry_after` seconds.
`429`	`UPDATE_LIMIT_REACHED`	One `mid` was updated more than 60 times.
`500`	`PERSIST_FAILED`	We could not store the message. Retry with the same `mid`.

curl -X POST "$RESPONSE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{ "label": "Download", "url": "https://example.com/r.pdf" }]
  }'

await fetch(responseUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mid: 'reply-evt_7f3a',
    text: 'Your report is ready 📊',
    buttons: [{ label: 'Download', url: 'https://example.com/r.pdf' }]
  })
})

import requests

requests.post(response_url, json={
    "mid": "reply-evt_7f3a",
    "text": "Your report is ready 📊",
    "buttons": [{"label": "Download", "url": "https://example.com/r.pdf"}],
})

{
  "ok": true,
  "messages": [
    { "message_id": "0f8c…", "mid": "reply-evt_7f3a", "updated": false }
  ]
}

{
  "ok": false,
  "error": {
    "code": "RESPONSE_URL_EXPIRED",
    "message": "This response_url has expired — use the bot-level API."
  }
}

Overview

Messages

Files

Pages

Post a reply (response URL)

Path parameters

Body

Response

Token rules

Errors

​Path parameters

​Body

​Response

​Token rules

​Errors

Path parameters

Body

Response

Token rules

Errors