HookChata Jiffi product

Documentation

HookChat turns Instagram and Messenger direct messages into signed webhook events, and lets you reply with one API call inside Meta's reply window. These pages cover the public /v1 API, how deliveries and retries work, the SDKs and the command line.

Start hereInstall an SDK, receive your first signed event and send your first reply.How-to guidesConnect an account, reply inside the window, verify and replay deliveries, rotate a secret, manage keys, and what happens when a person asks Meta to delete their data.ReferenceEvery route, parameter, error code and command, generated from the source of truth.SDKsThe Node, Python and Go clients and the hookchat command line.ReleasesWhat shipped in each version, and the binaries and packages to download.

Base URL https://hookchat.dev. The API surface is small on purpose: a conversation feed, two send routes, and webhook management. 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": { "platform_message_id": "mid.def456" } }
Failure
{
  "ok": false,
  "error": {
    "code": "window_closed",
    "message": "The 24 hour reply window for this conversation has closed.",
    "detail": "Use the human-agent route within 7 days of the last inbound message."
  }
}

On failure, error.code is a fixed code you can match on. error.message is for people and may change. error.detail appears only when there is more to say that is safe to share, such as Meta's reason for refusing a 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).

Shell
curl "$HOOKCHAT_BASE_URL/v1/conversations" \
  -H "Authorization: Bearer $HOOKCHAT_API_KEY"
  • A workspace is what the API calls a tenant: the tenant value in a URL is the workspace name you see in the console.
  • A workspace key already knows its workspace; the ?tenant query parameter is optional, and naming a different one is a 403 forbidden.
  • An operator key works across several workspaces and must name one with ?tenant; leaving it out 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, the retry schedule and when a delivery gives up.
  • API reference: every route, parameter, response and error code, generated from the OpenAPI document.
  • CLI reference: every hookchat command with its flags and examples.