Response URL

Every event we send includes a response_url. POST Block Kit to it, and the message lands in that conversation. The key is already inside the URL, so there is nothing to set up. That is why this is the main path for n8n, Make, and Zapier.

POST https://app.my-aichatbot.com/api/v1/responses/{token}

The pattern

Confirm the webhook

Return an empty body with 2xx. The typing dots stay on, because we know a reply is coming.

Do the slow work

Call your LLM, query your database, build the PDF. Take up to 45 minutes.

POST the result

Send Block Kit to the response_url. It shows up in the chat and turns off the typing dots.

The typing dots give up after about 3 minutes, but the token keeps working. A reply at minute 10 still lands — it just shows up without the dots first.

Send a reply

No Authorization header. Having the URL is your permission.

curl -X POST "$RESPONSE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "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({
    text: 'Your report is ready 📊',
    buttons: [{ label: 'Download', url: 'https://example.com/r.pdf' }]
  })
})

import requests

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

$ch = curl_init($responseUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'text' => 'Your report is ready 📊',
        'buttons' => [['label' => 'Download', 'url' => 'https://example.com/r.pdf']],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

body, _ := json.Marshal(map[string]any{
    "text": "Your report is ready 📊",
    "buttons": []map[string]string{
        {"label": "Download", "url": "https://example.com/r.pdf"},
    },
})

resp, err := http.Post(responseURL, "application/json", bytes.NewReader(body))

A success returns a handle for every message you created:

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

updated tells you if the call created a new message or replaced one — see Updating messages.

Token rules

Lifetime

45 minutes

Counted from when the event was created, not from your first use.

Reuse

multi-use

Post several messages, or update one many times, until it expires.

Rate limit

30 / minute

Per token.

Retries

same token

Every retry of one event carries the exact same response_url.

Errors

Status	Code	Meaning
`401`	`token_invalid`	The token is broken or has a bad signature.
`410`	`RESPONSE_URL_EXPIRED`	Past 45 minutes. Use an API key instead.
`404`	`conversation_not_found`	The conversation no longer exists.
`409`	`conversation_taken_over`	A human is handling it now. The bot is locked out.
`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.

An empty body is fine as a webhook reply (it means “got it”). Here it is an error (422 EMPTY_BODY). This endpoint only exists to create messages.

A 422 is also written to your delivery log. So even if your scenario ignores HTTP responses, you can still see why nothing showed up.

Attaching files

Upload through the token — no API key needed mid-flow:

POST https://app.my-aichatbot.com/api/v1/responses/{token}/files

See Sending files.

Progress updates

Turn one bubble from “queued” into “done”.

Past 45 minutes?

Switch to a key. It never expires.

Get started

Sending messages

Block Kit

Receiving events

No-code platforms

The pattern

Send a reply

Token rules

Errors

Attaching files

Next

Progress updates

Past 45 minutes?

​The pattern

​Send a reply

​Token rules

​Errors

​Attaching files

​Next

Progress updates

Past 45 minutes?

The pattern

Send a reply

Token rules

Errors

Attaching files

Next