Quickstart

By the end of this page, your bot will answer a real message with formatted text and a button.

Before you start

You need:

A chatbot in your dashboard with its brain set to Webhook.
An HTTPS endpoint we can reach. We never call http://, and we never follow redirects.
Your bot’s signing secret (whsec_…), from the bot’s webhook settings.

Local tunnels are fine for development — anything with a public HTTPS URL works. Private and local network addresses are blocked for security.

Get started

Answer the verification challenge

A webhook bot cannot go active until its URL passes a check. When you press Verify, we send a webhook.verify event with a one-time challenge string. Send it back, and your bot goes live.Two forms work. Return the raw challenge as the body, or return any JSON object with a matching top-level challenge key:

{ "challenge": "3f9a…" }

app.post('/webhook', express.json(), (req, res) => {
  if (req.body.event === 'webhook.verify') {
    return res.json({ challenge: req.body.challenge })
  }
  res.status(200).end()
})

@app.post("/webhook")
def webhook():
    body = request.get_json()
    if body.get("event") == "webhook.verify":
        return {"challenge": body["challenge"]}
    return "", 200

$body = json_decode(file_get_contents('php://input'), true);
if (($body['event'] ?? null) === 'webhook.verify') {
    header('Content-Type: application/json');
    echo json_encode(['challenge' => $body['challenge']]);
    exit;
}
http_response_code(200);

func webhook(w http.ResponseWriter, r *http.Request) {
    var body struct {
        Event     string `json:"event"`
        Challenge string `json:"challenge"`
    }
    json.NewDecoder(r.Body).Decode(&body)
    if body.Event == "webhook.verify" {
        json.NewEncoder(w).Encode(map[string]string{"challenge": body.Challenge})
        return
    }
    w.WriteHeader(http.StatusOK)
}

The key name is case-sensitive. Content-Type does not matter. You have 10 seconds. A check is never retried — just press Verify again.

Using Zapier? Catch Hooks cannot return a custom body, so we skip the echo for zapier.com addresses. See the Zapier guide.

Reply to a message

Once verified, every visitor message arrives as a message.created event. Return Block Kit JSON from the same request, and it shows up right away:

{ "text": "Hi! I got: **hello**" }

That shortcut turns into a full text block on our side. Read the visitor’s words from message.text:

app.post('/webhook', express.json(), (req, res) => {
  const e = req.body
  if (e.event === 'webhook.verify') return res.json({ challenge: e.challenge })
  if (e.event === 'message.created') {
    return res.json({ text: `Hi! I got: **${e.message.text}**` })
  }
  res.status(200).end()
})

@app.post("/webhook")
def webhook():
    e = request.get_json()
    if e.get("event") == "webhook.verify":
        return {"challenge": e["challenge"]}
    if e.get("event") == "message.created":
        return {"text": f"Hi! I got: **{e['message']['text']}**"}
    return "", 200

$e = json_decode(file_get_contents('php://input'), true);
header('Content-Type: application/json');
if ($e['event'] === 'webhook.verify') {
    echo json_encode(['challenge' => $e['challenge']]);
} elseif ($e['event'] === 'message.created') {
    echo json_encode(['text' => "Hi! I got: **{$e['message']['text']}**"]);
}

if body.Event == "message.created" {
    json.NewEncoder(w).Encode(map[string]string{
        "text": "Hi! I got: **" + body.Message.Text + "**",
    })
    return
}

Do not return your framework’s default body. We know the common ones — Accepted, OK, Workflow was started — and we block them instead of posting them. But anything else that is not JSON becomes a real chat bubble. Return JSON, or return an empty body.

Add a button

Buttons make the reply interactive. When someone clicks one, you get an interaction.button_clicked event:

{
  "text": "Your order **#4821** has shipped!",
  "buttons": [
    { "label": "Track package", "value": "4821" },
    { "label": "Contact support" }
  ]
}

A plain label is enough. We build the action_id from it (Track package becomes track_package).

Check the signature

Before you go live, check that each request really came from us. Every POST includes X-MyAIChatbot-Signature:

import { createHmac, timingSafeEqual } from 'node:crypto'

const ts = req.header('X-MyAIChatbot-Timestamp')
const expected = 'v1=' + createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`, 'utf8')
  .digest('hex')

You must sign the raw body bytes, not a re-built object. Full guide in five languages: Verifying signatures.

Next steps

Work that takes longer

You get 10 seconds to reply. Slower work must use the response_url.

Every block type

Images, files, forms, cards, and progress bars.

Get started

Sending messages

Block Kit

Receiving events

No-code platforms

Before you start

Get started

Next steps

Work that takes longer

Every block type

​Before you start

​Get started

​Next steps

Work that takes longer

Every block type

Before you start

Get started

Next steps