HookChat API

HookChat turns Instagram and Messenger direct messages into signed webhook events, and lets you reply with one API call inside Meta's messaging windows. This is the reference for the public /v1 API and the webhook delivery contract.

Base URL https://hookchat.dev (staging: https://stg.hookchat.dev). The API surface is small on purpose: a conversation feed, two send routes, and webhook administration. There is no generic send, and there are no message tags.

The response envelope

Every /v1 response uses one envelope, snake_case throughout. ok is always present and is the only field you branch on.

// success
{ "ok": true, "data": { /* resource */ } }

// failure
{ "ok": false, "error": { "code": "window_closed", "message": "…", "detail": "…" } }

On failure, error.code is a stable machine token from a closed vocabulary; error.message is human-readable and may change; error.detail appears only where a handler has extra non-sensitive context (for example Meta's rejection text on a failed send). Message content never appears in an error.

Authentication

Authenticate with an API key as an HTTP bearer token. Keys are hookchat_live_… or hookchat_test_… and are created in the console (the secret is shown exactly once).

curl https://hookchat.dev/v1/conversations \
  -H "Authorization: Bearer hookchat_live_…"

• A single-tenant (bound) key derives its tenant from the key itself; the ?tenant query parameter is optional, and naming a different tenant is a 403 forbidden.
• An operator key must name ?tenant from its allowlist; omitting it is a 400 tenant_required.
• A missing or invalid key is a 401 unauthorized. The only unauthenticated route is GET /v1/ping.

Where to go next

• Quickstart: install @hookchat/node, receive your first event, send your first reply.
• Sending messages: the two send routes, the window model, conversation targeting, and the full error vocabulary.
• Webhooks and events: the event vocabulary, the signing scheme, and the retry / dead-letter contract.