Webhooks

A Antonnia entrega eventos em tempo real para sua integração via webhooks. Esses eventos notificam você quando mensagens são criadas, sessões mudam de status ou agentes são transferidos.

Configurando webhooks

Para receber eventos, você precisa criar um App no painel da Antonnia e configurá-lo com uma URL de webhook.

Crie um App

No painel da Antonnia, vá em Settings > Apps e crie um novo app. O app representa a integração do seu canal.

Inscreva-se nos eventos

Selecione quais eventos seu app precisa receber. Para uma integração de canal, você normalmente se inscreverá em:

message.created — para entregar respostas da IA ao seu canal
session.created — para rastrear novas conversas
session.transferred — para lidar com transferências de agentes
session.finished — para limpar recursos do lado do canal (ex.: fechar tickets)

Inscreva-se apenas nos eventos que você realmente precisa.

Defina a URL do webhook

Configure o endpoint HTTPS onde a Antonnia entregará os eventos. Este é o handler de webhook da sua integração (ex.: https://your-service.com/webhook/antonnia).

Quando um cliente (usuário final) se conecta ao seu app, todos os eventos das sessões desse cliente são entregues à sua URL de webhook. Você receberá eventos de todas as sessões e mensagens associadas aos clientes conectados.

Tipos de evento

Event	Fired when
`message.created`	Uma nova mensagem é adicionada a uma sessão (usuário ou assistente)
`session.created`	Uma nova sessão é criada
`session.transferred`	O agente de uma sessão é alterado
`session.finished`	Uma sessão é fechada

Estrutura do evento

Todos os eventos seguem o mesmo envelope:

{
  "id": "evt_abc123",
  "timestamp": 1710000000,
  "type": "message.created",
  "organization_id": "org_xyz",
  "data": {
    "object": { ... }
  }
}

Field	Description
`id`	Identificador único do evento
`timestamp`	Timestamp Unix do evento
`type`	String do tipo de evento
`organization_id`	Organização proprietária do recurso
`data.object`	O objeto completo do recurso (sessão ou mensagem)

Eventos principais para integrações de canal

message.created

Este é o evento mais importante para integrações de canal. Quando o agente de IA responde, você recebe este evento com role: "assistant":

{
  "type": "message.created",
  "data": {
    "object": {
      "id": "msg_123",
      "session_id": "sess_456",
      "role": "assistant",
      "content": { "type": "text", "text": "Hello!" },
      "delivery_status": "pending",
      "provider_message_id": null
    }
  }
}

Filtre o processamento de saída: trate apenas mensagens onde role é "assistant". Você também receberá eventos para mensagens com role: "user" (que você mesmo criou), então ignore essas para evitar loops.

Ignore tipos de conteúdo internos: descarte mensagens onde content.type é "function_call", "function_result" ou "thought". Estes são internos da IA e não devem ser entregues aos usuários finais.

session.transferred

Disparado quando o agente de uma sessão muda. Útil para atualizar a interface do seu canal (ex.: exibir "Você agora está conversando com um agente humano"):

{
  "type": "session.transferred",
  "data": {
    "object": {
      "id": "sess_456",
      "status": "open",
      "agent": {
        "id": "agent_human_123",
        "name": "João Silva",
        "type": "human"
      }
    }
  }
}

session.finished

Disparado quando uma sessão é fechada. Use para limpar recursos do lado do canal (fechar tickets, encerrar chats):

{
  "type": "session.finished",
  "data": {
    "object": {
      "id": "sess_456",
      "status": "closed",
      "agent": null
    }
  }
}

Entrega de webhooks

Os eventos são entregues via HTTP POST para a URL de webhook configurada no seu app. Seu endpoint deve:

Retornar 200 OK rapidamente (em até 5 segundos)
Processar o evento de forma assíncrona se exigir trabalho pesado
Ser idempotente — você pode receber o mesmo evento mais de uma vez

Você só recebe eventos de clientes que estão conectados ao seu app. Se um cliente desconectar ou se conectar a um app diferente, os eventos dele param de chegar ao seu webhook.

Veja a Referência da API de Webhooks para detalhes do payload.