Webhook

The generic webhook is the channel for everything else: an internal chat, a ticketing system, a CI job or a script. Your system posts a JSON message to the gateway, and the gateway posts the replies back to a callback URL you choose. Both directions carry the same shared secret.

	Webhook
Transport	An HTTP endpoint the gateway serves, plus a callback URL it posts to
Who can talk to the agent	Callers that send the shared secret
Voice in	Yes, as base64 or a URL in the request
Voice replies	No (text only)
Images in	Yes, as base64 or a URL in the request
Images out	Yes, as base64 in the callback
”Working on it” signal	One short notice posted to the callback if the reply takes more than about 2 seconds

Set it up

Configure ChatCLI

export CHATCLI_WEBHOOK_ADDR=":8083"
export CHATCLI_WEBHOOK_SECRET="a-long-random-string"
export CHATCLI_WEBHOOK_CALLBACK_URL="https://your-app.example.com/chatcli/replies"
# export CHATCLI_WEBHOOK_PATH="/inbound"   # the default

Start the gateway

/gateway start
/gateway status     # webhook should be listed

Send a message

curl -X POST http://localhost:8083/inbound \
  -H "Content-Type: application/json" \
  -H "X-ChatCLI-Secret: a-long-random-string" \
  -d '{"chat_id": "ticket-42", "user_id": "alice", "text": "summarize the last deploy log"}'

The gateway answers 202 Accepted at once; the progress and the reply arrive at your callback URL.

Environment variables

Variable	Required	Default	What it does
`CHATCLI_WEBHOOK_ADDR`	yes	—	Address the endpoint binds, for example `:8083`. The adapter starts when it is set.
`CHATCLI_WEBHOOK_SECRET`	yes, in practice	—	Shared secret checked on every request in `X-ChatCLI-Secret` and sent back on every callback. Without it every request is refused with `401`, and a warning is logged at start.
`CHATCLI_WEBHOOK_CALLBACK_URL`	yes, to get replies	—	Where the gateway posts the progress and the reply. Without it requests are still accepted and run, but the replies are not delivered anywhere; a warning is logged at start.
`CHATCLI_WEBHOOK_PATH`	no	`/inbound`	Path of the endpoint.
`CHATCLI_WEBHOOK_HOME_CHANNEL`	no	—	`chat_id` used for proactive messages sent with `@send webhook`.

The request

POST to CHATCLI_WEBHOOK_PATH with Content-Type: application/json and the X-ChatCLI-Secret header:

Field	Required	Meaning
`chat_id`	yes	The conversation. Messages with the same `chat_id` share context.
`user_id`	no	Who sent it; used to tell people apart in the Conversation Hub.
`text`	one of text, audio or image	The message.
`audio_b64` or `audio_url`	no	A voice message, inline as base64 or as a URL the gateway downloads. It is transcribed before the agent runs.
`audio_mime`	no	The audio’s MIME type, for example `audio/ogg`.
`image_b64` or `image_url`	no	An image, inline as base64 or as a URL the gateway downloads.
`image_mime`	no	The image’s MIME type, for example `image/png`.

Response	When
`202 Accepted`	The message was queued.
`400 Bad Request`	The body is not valid JSON, `chat_id` is missing, base64 does not decode, or there is no text, audio or image.
`401 Unauthorized`	The secret is missing or wrong, or `CHATCLI_WEBHOOK_SECRET` is not set.
`405 Method Not Allowed`	Anything other than `POST`.
`503 Service Unavailable`	The gateway is shutting down.

The request body is limited to the audio size cap plus 1 MB, about 21 MB with the default CHATCLI_GATEWAY_MAX_AUDIO_BYTES.

The callbacks

For each message the gateway posts JSON to CHATCLI_WEBHOOK_CALLBACK_URL, with Content-Type: application/json and the same X-ChatCLI-Secret header so your endpoint can check where it came from:

{
  "chat_id": "ticket-42",
  "text": "The last deploy finished in 4m12s; two warnings, no errors."
}

When the reply carries an image, the body also has image_b64, and image_mime and image_filename when they are known. A single message can produce several callbacks with this same shape: the “working on it” notice, progress updates while the agent works, and the final reply. There is no field telling them apart; the final reply is the last one. Any 2xx answer from your endpoint counts as delivered.

Security

Keep the secret long and random, and serve the endpoint over HTTPS when it is reachable from other machines.
audio_url and image_url are downloaded by the gateway itself, so whoever holds the secret can make the gateway fetch a URL from its own network.
Each message runs the agent with its tools and shell, without confirmations. Harden it with security mode.

Limits

A reply is cut at 3500 characters and ends with ….
Only text and images are posted back; voice replies are not sent on this channel.

Chat gateway

How messages run, voice, images, continuity and the other channels.

Proactive messaging

Let the agent post to your callback on its own with @send.

Get started

Documentation

Set it up

Environment variables

The request

The callbacks

Security

Limits

See also

Chat gateway

Proactive messaging

​Set it up

​Environment variables

​The request

​The callbacks

​Security

​Limits

​See also

Chat gateway

Proactive messaging

Set it up

Environment variables

The request

The callbacks

Security

Limits

See also