Webhook

O webhook genérico é o canal para todo o resto: um chat interno, um sistema de tickets, um job de CI ou um script. O seu sistema posta uma mensagem JSON no gateway, e o gateway posta as respostas de volta numa URL de callback que você escolhe. Os dois sentidos levam o mesmo segredo compartilhado.

	Webhook
Transporte	Um endpoint HTTP que o gateway serve, mais uma URL de callback para onde ele posta
Quem pode falar com o agente	Quem envia o segredo compartilhado
Voz recebida	Sim, como base64 ou URL na requisição
Respostas em voz	Não (só texto)
Imagens recebidas	Sim, como base64 ou URL na requisição
Imagens enviadas	Sim, como base64 no callback
Sinal de “trabalhando”	Um aviso curto postado no callback se a resposta passar de uns 2 segundos

Configuração

Configure o ChatCLI

export CHATCLI_WEBHOOK_ADDR=":8083"
export CHATCLI_WEBHOOK_SECRET="um-texto-longo-e-aleatorio"
export CHATCLI_WEBHOOK_CALLBACK_URL="https://seu-app.example.com/chatcli/respostas"
# export CHATCLI_WEBHOOK_PATH="/inbound"   # o padrão

Inicie o gateway

/gateway start
/gateway status     # webhook deve aparecer

Mande uma mensagem

curl -X POST http://localhost:8083/inbound \
  -H "Content-Type: application/json" \
  -H "X-ChatCLI-Secret: um-texto-longo-e-aleatorio" \
  -d '{"chat_id": "ticket-42", "user_id": "alice", "text": "resuma o log do último deploy"}'

O gateway responde 202 Accepted na hora; o progresso e a resposta chegam na sua URL de callback.

Variáveis de ambiente

Variável	Obrigatória	Padrão	O que faz
`CHATCLI_WEBHOOK_ADDR`	sim	—	Endereço do endpoint, por exemplo `:8083`. O adaptador liga quando ela está definida.
`CHATCLI_WEBHOOK_SECRET`	sim, na prática	—	Segredo compartilhado conferido em toda requisição no `X-ChatCLI-Secret` e reenviado em todo callback. Sem ele toda requisição é recusada com `401`, e um aviso é registrado no start.
`CHATCLI_WEBHOOK_CALLBACK_URL`	sim, para receber respostas	—	Para onde o gateway posta o progresso e a resposta. Sem ela as requisições continuam aceitas e rodam, mas as respostas não são entregues a lugar nenhum; um aviso é registrado no start.
`CHATCLI_WEBHOOK_PATH`	não	`/inbound`	Caminho do endpoint.
`CHATCLI_WEBHOOK_HOME_CHANNEL`	não	—	`chat_id` usado nas mensagens proativas enviadas com `@send webhook`.

A requisição

POST em CHATCLI_WEBHOOK_PATH com Content-Type: application/json e o header X-ChatCLI-Secret:

Campo	Obrigatório	Significado
`chat_id`	sim	A conversa. Mensagens com o mesmo `chat_id` compartilham contexto.
`user_id`	não	Quem mandou; usado para diferenciar pessoas no Conversation Hub.
`text`	um entre texto, áudio ou imagem	A mensagem.
`audio_b64` ou `audio_url`	não	Uma mensagem de voz, em base64 ou como URL que o gateway baixa. É transcrita antes de o agente rodar.
`audio_mime`	não	O tipo MIME do áudio, por exemplo `audio/ogg`.
`image_b64` ou `image_url`	não	Uma imagem, em base64 ou como URL que o gateway baixa.
`image_mime`	não	O tipo MIME da imagem, por exemplo `image/png`.

Resposta	Quando
`202 Accepted`	A mensagem entrou na fila.
`400 Bad Request`	O corpo não é JSON válido, falta `chat_id`, o base64 não decodifica, ou não há texto, áudio nem imagem.
`401 Unauthorized`	O segredo está ausente ou errado, ou `CHATCLI_WEBHOOK_SECRET` não está definido.
`405 Method Not Allowed`	Qualquer coisa que não seja `POST`.
`503 Service Unavailable`	O gateway está desligando.

O corpo da requisição é limitado ao teto de áudio mais 1 MB, uns 21 MB com o CHATCLI_GATEWAY_MAX_AUDIO_BYTES padrão.

Os callbacks

Para cada mensagem o gateway posta JSON em CHATCLI_WEBHOOK_CALLBACK_URL, com Content-Type: application/json e o mesmo header X-ChatCLI-Secret, para que o seu endpoint confira a origem:

{
  "chat_id": "ticket-42",
  "text": "O último deploy terminou em 4m12s; dois avisos, nenhum erro."
}

Quando a resposta traz uma imagem, o corpo também tem image_b64, e image_mime e image_filename quando são conhecidos. Uma mesma mensagem pode gerar vários callbacks com esse formato: o aviso de “trabalhando”, atualizações de progresso enquanto o agente trabalha e a resposta final. Nenhum campo os diferencia; a resposta final é a última. Qualquer resposta 2xx do seu endpoint conta como entregue.

Segurança

Use um segredo longo e aleatório, e sirva o endpoint por HTTPS quando ele for acessível de outras máquinas.
audio_url e image_url são baixados pelo próprio gateway, então quem tem o segredo consegue fazer o gateway buscar uma URL da rede dele.
Cada mensagem roda o agente com suas tools e o shell, sem confirmações. Endureça com o modo de segurança.

Limites

Uma resposta é cortada em 3500 caracteres e termina com ….
Só texto e imagens voltam no callback; respostas em voz não são enviadas neste canal.

Veja também

Chat gateway

Como as mensagens rodam, voz, imagens, continuidade e os outros canais.

Mensagens proativas

Deixe o agente postar no seu callback por conta própria com @send.

Comece aqui

Documentação

Configuração

Variáveis de ambiente

A requisição

Os callbacks

Segurança

Limites

Veja também

Chat gateway

Mensagens proativas

​Configuração

​Variáveis de ambiente

​A requisição

​Os callbacks

​Segurança

​Limites

​Veja também

Chat gateway

Mensagens proativas

Configuração

Variáveis de ambiente

A requisição

Os callbacks

Segurança

Limites

Veja também