Webhooks

Catálogo de eventos

Todos os tipos de evento de webhook emitidos pelo ThunderPhone.

Todo corpo de webhook tem um campo type cujo valor é um dos tipos de evento desta página. Ao assinar um endpoint, o array events deve conter os tipos de evento desejados (ou ficar vazio para assinar todos — exceto os eventos por turno telephony.turn / web.turn, que são enviados apenas para endpoints que os nomeiam explicitamente).

Dois estilos de entrega transportam esses 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.
• Os intercâmbios bloqueantes são executados apenas no webhook legado de URL única: 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 a execução de ferramentas em modo webhook. Sua resposta molda a chamada em tempo real.

Os exemplos de payload abaixo mostram o envelope de endpoint em sua ordem no wire (chaves ordenadas alfabeticamente: data, event_id, type); as entregas legadas carregam os mesmos data sem event_id.

Eventos de chamada#

telephony.incoming#

Enviado quando uma chamada recebida chega a um dos seus números de telefone. As entregas ao endpoint são notificações enviadas sem aguardar resposta para todas as chamadas recebidas, independentemente de o número estar configurado com um 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 schema 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 de telefonia recebida ou efetuada termina. Não bloqueante. Inclui a transcrição, a URL da gravação quando disponível e o resumo de cobrança. Consulte telephony.complete / web.complete para o schema do payload.

telephony.tool#

Enviado após uma chamada de telefonia invocar uma ferramenta de função. Notificação de auditoria não bloqueante — a ferramenta já foi executada quando este evento é entregue; ele abrange suas próprias ferramentas de função (não ferramentas integradas, de base de conhecimento, de conexão de app 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.

telephony.turn#

Enviado enquanto uma chamada de telefonia está em andamento, uma vez para cada turno com fala à medida que ocorre — as conclusões faladas pelo agente e os turnos transcritos de quem liga. Permite acompanhar a conversa ao vivo por webhooks simples em vez de fazer polling de GET /v1/calls/{call_id}/transcript. Não bloqueante.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

O equivalente de canal web a telephony.incoming, enviado quando uma sessão do widget web ou uma chamada de teste de microfone no builder começa. As entregas ao endpoint são enviadas sem aguardar resposta 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 no builder, origin_domain e publishable_key_prefix ficam vazios.

web.complete#

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

web.tool#

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

web.turn#

O equivalente de canal web a telephony.turn, abrangendo chamadas do widget web e chamadas de teste de microfone no builder. Tem a mesma estrutura de payload, com origin_domain em vez de from_number / to_number. Assim como telephony.turn, exige uma assinatura explícita — nunca é entregue por meio de um array events vazio.

Eventos de voz#

A criação de vozes personalizadas é assíncrona. Esses eventos não bloqueantes permitem que você reaja a um resultado final em vez de consultar repetidamente o endpoint de detalhes do clone.

voice.ready#

Enviado quando uma voz personalizada conclui o processamento e pode ser atribuída a um agente.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed#

Enviado quando o processamento de uma voz personalizada falha permanentemente.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

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"
}

issue.reported#

Enviado quando um relatório de problema é criado — seja enviado por uma pessoa usuária pelo dashboard (source: "user") ou automaticamente pela avaliação da chamada (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"
}

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 no início e nunca produziram uma chamada. Não bloqueante. Útil para conectar 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"
}

Eventos de alerta#

alert.triggered#

Enviado quando uma regra de alerta com o canal Entregar para webhooks de desenvolvedor ativado atinge seu limite. Não bloqueante. Uma regra é acionada 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"
}

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

Relacionados#