Catálogo de eventos

Todo corpo de webhook tem um campo type cujo valor é um dos tipos de evento desta página. Quando você assina um endpoint, o array events deve conter os tipos de evento que você quer (ou estar vazio para assinar todos). Dois estilos de entrega transportam estes eventos:

As entregas de endpoint são sempre notificações não bloqueantes com tentativas: responda com qualquer 2xx; o envelope contém um event_id para deduplicação.
As trocas bloqueantes são executadas apenas no webhook de URL única legado: a solicitação de configuração telephony.incoming / web.incoming (números em modo webhook e chaves de widget, tempo limite de 10 s) e o despacho de ferramentas em modo webhook. Sua resposta molda a chamada ao vivo.

Os payloads de exemplo abaixo mostram o envelope de endpoint em sua ordem de transmissão (chaves ordenadas alfabeticamente: data, event_id, type); as entregas legadas transportam os mesmos data sem event_id.

Eventos de chamada

`telephony.incoming`

Enviado quando uma chamada de entrada chega a um dos seus números de telefone. As entregas ao endpoint são notificações fire-and-forget enviadas para todas as chamadas de entrada, seja o número configurado com agente ou com webhook. Números sem um agente atribuído também recebem a solicitação de configuração bloqueante no webhook legado — consulte telephony.incoming / web.incoming para o esquema completo de solicitação / resposta.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

Enviado quando uma chamada telefônica de entrada ou saída termina. Não bloqueante. Inclui a transcrição completa, a URL da gravação e o resumo de cobrança. Consulte telephony.complete / web.complete para o esquema do payload.

`telephony.tool`

Enviado depois que uma chamada telefônica invoca uma ferramenta de função. Notificação de auditoria não bloqueante — a ferramenta já foi executada quando este evento é entregue; ela abrange suas próprias ferramentas de função (não ferramentas integradas, de base de conhecimento, de conexão de aplicativo ou MCP).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response é o resultado executado: {"status": <http status>, "response": <your endpoint's JSON>} em caso de sucesso, ou {"status": <status>, "error": "<message>"} em caso de falha.

`web.incoming`

O equivalente no canal web de telephony.incoming, enviado quando uma sessão do widget web ou uma chamada de teste de microfone do builder é iniciada. As entregas ao endpoint são fire-and-forget para todas as sessões web. Chaves publicáveis em mode="webhook" também recebem a solicitação de configuração bloqueante no webhook legado — essa solicitação bloqueante tem uma estrutura diferente (origin_domain, publishable_key_prefix; sem números de telefone). Consulte telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number é sempre o literal "web". Para sessões de widget no modo webhook, to_number fica vazio (o número do agente da sessão é atribuído após a configuração); para chamadas de teste de microfone do builder, origin_domain e publishable_key_prefix ficam vazios.

`web.complete`

O equivalente no canal web de telephony.complete, abrangendo chamadas do widget web (direction: "web") e chamadas de teste de microfone do builder (direction: "test"). Não bloqueante. Tem a mesma estrutura de payload de telephony.complete, além de origin_domain, com from_number definido como "web".

No webhook legado de URL única, chamadas de teste de microfone do builder historicamente são relatadas como telephony.complete — apenas chamadas com direction: "web" usam o tipo web.complete nesse caso. O sistema de endpoints mapeia chamadas web e de teste para web.*. Payloads históricos podem conter os valores legados de direction, widget ou mic.

`web.tool`

O equivalente no canal web de telephony.tool. O data contém origin_domain em vez de from_number / to_number.

Eventos de qualidade

`call.graded`

Enviado sempre que uma execução de avaliação por IA é concluída para uma chamada. Não bloqueante.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

Campo	Tipo	Descrição
`grade.id`	integer	ID da avaliação
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` ou `no_conversation`
`grade.summary`	string	Resumo de um parágrafo
`grade.detected_issues`	array	Strings de problemas encontrados pelo avaliador
`grade.status`	string	Sempre `completed` — apenas execuções concluídas são enviadas
`grade.grader_model`	string	Qual avaliador produziu o resultado (por exemplo, `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Uma chamada pode ser avaliada mais de uma vez — uma avaliação heurística rápida geralmente é seguida por uma avaliação completa do modelo quando a gravação está disponível, e reavaliações manuais são possíveis. Cada execução concluída emite seu próprio evento call.graded; considere o graded_at mais recente como autoritativo.

`issue.reported`

Enviado quando um relatório de problema é criado — seja enviado por uma pessoa usuária pelo painel (source: "user") ou automaticamente pela avaliação de chamadas (source: "system"). Não bloqueante.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

Campo	Tipo	Descrição
`issue_report.severity`	string	`critical`, `warning` ou `info`
`issue_report.status`	string	`open` ou `resolved`
`issue_report.source`	string	`user` (enviado pelo painel) ou `system` (criado pela avaliação)

Reavaliar uma chamada recria seus relatórios de problemas gerados pelo sistema, o que reemite issue.reported para os relatórios recriados. Faça a deduplicação por call_id + title se quiser apenas uma notificação por problema subjacente.

Eventos de chamadas de teste

`test-call.completed`

Enviado quando uma execução de chamada de teste atinge um status terminal — completed ou failed, incluindo execuções que falharam na inicialização e nunca produziram uma chamada. Não bloqueante. Útil para integrar execuções de CI em lote aos seus sistemas de chat/notificações.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Campo	Tipo	Descrição
`test_call_run.target_type`	string	`agent` ou `phone_number`
`test_call_run.target_id`	integer	ID do agente ou do número de telefone que a execução direcionou, correspondente a `target_type`
`test_call_run.status`	string	`completed` ou `failed`
`test_call_run.call_id`	integer \| null	`null` quando a execução falhou antes de uma chamada ser realizada
`test_call_run.error_message`	string	Vazio em caso de sucesso

Eventos de alerta

`alert.triggered`

Enviado quando uma regra de alerta com o canal Entregar para webhooks de desenvolvedor ativado ultrapassa seu limite. Não bloqueante. Uma regra é disparada uma vez e então respeita seu período de espera, portanto uma violação contínua produz um evento por janela de período de espera.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Campo	Tipo	Descrição
`event_id` (em `data`)	UUID	O ID de disparo do alerta — diferente do `event_id` de entrega do invólucro
`rule_id`, `rule_name`	UUID, string	A regra que foi disparada
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume` ou `suite_regression`
`comparator`	string	`lt`, `lte`, `gt` ou `gte`
`metric_value`	number	O valor da métrica na janela quando a regra foi disparada
`threshold`	number	O limite configurado
`window_hours`	integer	Janela de avaliação retroativa
`fired_at`	timestamp

Consulte o guia de Alertas para criar regras, métricas, períodos de espera e os canais de e-mail / Slack.

Relacionados

telephony.incoming / web.incoming

O payload bloqueante de chamada recebida ao qual você precisa responder.

telephony.complete / web.complete

Transcrição e métricas após a chamada.

Endpoints de webhook

Inscreva uma URL em um subconjunto destes eventos.

Ferramentas de função

Como os eventos telephony.tool / web.tool são gerados.

Webhooks

Function Tools

Eventos de chamada

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventos de qualidade

`call.graded`

`issue.reported`

Eventos de chamadas de teste

`test-call.completed`

Eventos de alerta

`alert.triggered`

Relacionados

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoints de webhook

Ferramentas de função

​Eventos de chamada

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Eventos de qualidade

​call.graded

​issue.reported

​Eventos de chamadas de teste

​test-call.completed

​Eventos de alerta

​alert.triggered

​Relacionados

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoints de webhook

Ferramentas de função

Eventos de chamada

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventos de qualidade

`call.graded`

`issue.reported`

Eventos de chamadas de teste

`test-call.completed`

Eventos de alerta

`alert.triggered`

Relacionados