Catálogo de eventos

Todos os tipos de eventos de webhook emitidos pelo ThunderPhone.

Todo corpo de webhook tem um campo type cujo valor é um dos tipos de evento nesta página. Quando você assina um endpoint, o array events deve conter os tipos de evento desejados (ou ficar vazio para assinar tudo — exceto os eventos por turno telephony.turn / web.turn, que são entregues apenas aos 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 inclui um event_id para deduplicação.
• As trocas bloqueantes ocorrem apenas no webhook legado de URL única: a solicitação de configuração telephony.incoming / web.incoming (números no modo webhook: 13 s, incluindo uma tentativa; chaves de widget no modo webhook: 10 s) e o despacho de ferramentas no modo webhook. Sua resposta molda a chamada em tempo real.

Os exemplos de payload abaixo mostram o envelope de endpoint na ordem de transmissão (chaves ordenadas alfabeticamente: data, event_id, type); as entregas legadas incluem o mesmo 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 sem confirmação enviadas para todas as chamadas recebidas, quer o número esteja configurado com um agente ou com um 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 de telefonia recebida ou realizada 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 esquema da carga útil.

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; ela abrange suas próprias ferramentas de função e a ferramenta integrada send_sms (não outras ferramentas integradas, de base de conhecimento, de conexão de aplicativo ou MCP). Para send_sms, tanto arguments.to quanto arguments.body são [REDACTED]. As transcrições de conclusão também os ocultam; recupere o conteúdo e o destinatário do recurso SMS com escopo da organização usando o message_id da resposta.

{
  "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 conforme ele 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 consultar repetidamente 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 no canal web de telephony.incoming, enviado quando uma sessão do widget web ou uma chamada de teste de microfone do builder começa. As entregas ao endpoint são sem confirmação 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 um formato 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 do 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 o mesmo formato de carga útil que telephony.complete, além de origin_domain, com from_number definido como "web".

web.tool#

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

web.turn#

O equivalente no canal web de telephony.turn, abrangendo chamadas do widget web e chamadas de teste de microfone do builder. Tem o mesmo formato de carga útil, com origin_domain em vez de from_number / to_number. Assim como telephony.turn, exige uma assinatura explícita — nunca é entregue por meio de uma matriz events vazia.

call.transfer_completed#

Enviado uma vez por chamada com o resultado final de uma transferência de chamada: uma transferência fria ou a ponte entre pessoas que uma transferência assistida deixa após o agente sair. Não bloqueia e é entregue apenas a endpoints (nunca ao webhook legado de URL única). Chega após o telephony.complete da chamada: quando a operadora assume a chamada ou a transferência falha ou, quando o ThunderPhone faz a ponte da chamada, quando a ponte termina.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

Os mesmos valores estão no objeto de chamada como transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds e transfer_bridge_total_cents. event_id é o mesmo em cada entrega de uma chamada, portanto um relatório repetido nunca produz um segundo evento.

Eventos de SMS#

Os eventos de SMS descrevem mensagens enviadas pela conta Twilio ou Telnyx conectada da organização. O corpo da mensagem é omitido e to é ocultado. Recupere a mensagem no escopo da organização em GET /v1/sms/{message_id} quando seu conteúdo ou destinatário for necessário.

sms.sent#

Enviado quando a operadora do cliente aceita uma solicitação de SMS de saída. Isto não é uma confirmação de entrega no aparelho.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Enviado após uma rejeição permanente da operadora, após esgotar as tentativas transitórias ou quando o resultado é permanentemente desconhecido. error_code é um código estável do ThunderPhone, e error_message informa a ação necessária do cliente quando disponível. status: "unknown" significa que a operadora pode ter aceitado o SMS; reconcilie-o no log da operadora, pois o ThunderPhone não o reenviará automaticamente.

sms.received#

Reservado para suporte a SMS de entrada. Nenhum evento sms.received é emitido na versão atual. A configuração de webhook de entrada da operadora e a verificação de assinatura serão disponibilizadas separadamente.

Eventos de voz#

A criação de voz personalizada é assíncrona. Esses eventos não bloqueantes permitem reagir a um resultado final em vez de consultar repetidamente o endpoint de detalhes do clone.

voice.ready e voice.failed são entregues apenas a um endpoint de toda a organização com events: []. Eles não podem ser selecionados como filtros explícitos de eventos.

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 apresenta uma falha permanente.

{
  "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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Enviado sempre que a extração de dados estruturados é concluída com êxito, incluindo uma nova tentativa tardia após telephony.complete / web.complete ou uma nova execução manual por meio de POST /v1/calls/{call_id}/extract. Não bloqueante.

Em um modo de extração bloqueante, o evento de conclusão normalmente não espera mais do que o orçamento de extração de 75 segundos. Se o processo de trabalho da extração for perdido, o processo de finalização de produção (a cada cinco minutos) libera uma conclusão cujo blocking_deadline_at expirou antes de iniciar outra tentativa de extração. Um sucesso posterior é entregue separadamente por meio deste evento.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Enviado uma vez quando uma campanha passa de running para completed, seja porque a programação terminou ou porque todos os contatos chegaram a estados terminais. Novas tentativas do executor não emitem outro evento. Este evento de ciclo de vida no nível da organização é entregue apenas a endpoints com escopo de organização, não a endpoints com escopo de agente. Não bloqueante.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

As quatro contagens de resultado são mutuamente exclusivas e somam contacts_total: completed contém contatos bem-sucedidos; no_answer contém contatos com falha/esgotados em estado terminal cujo resultado final foi sem resposta; failed contém todos os demais contatos com falha/esgotados em estado terminal; e remaining contém contatos pendentes, agendados ou em chamada no momento. Um contato aguardando uma nova tentativa é remaining, mesmo quando sua tentativa mais recente não teve resposta. Chamadas em andamento são reconciliadas antes do snapshot de conclusão emitido uma única vez. started_at é o início configurado da campanha ou o horário de criação da campanha quando nenhum início foi configurado.

issue.reported#

Enviado quando um relatório de problema é criado — seja enviado por um usuário no 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"
}

issue.escalated#

Enviado quando um padrão de problema é enviado ao ThunderPhone para análise da equipe: após Reportar ao ThunderPhone, ou quando Corrigir com IA não consegue confirmar uma correção no lado do cliente e encaminha o problema automaticamente. Somente endpoints de toda a organização recebem este evento.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

Esta é uma notificação, não o pacote de evidências. Use cluster_id para correlacioná-la ao padrão de problema. Consulte Reportar ao ThunderPhone.

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

Eventos de alerta#

alert.triggered#

Enviado quando uma regra de alerta com o canal Entregar aos webhooks de desenvolvedor ativado ultrapassa seu limite. Não bloqueante. Uma regra é acionada uma vez e então respeita seu período de espera, de modo que 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.

Eventos de migração#

migration.call.complete#

Enviado quando uma chamada realizada por meio de POST /v1/migrations/{id}/calls termina, independentemente de qual plataforma a tenha realizado. Não bloqueante. Chega em até cerca de 5 minutos após o término da chamada. data contém todos os campos de telephony.complete, além de um bloco migration. Uma chamada realizada pelo ThunderPhone também envia telephony.complete normalmente, com o mesmo call_id. Uma chamada na outra plataforma que não tenha terminado após 2 horas, ou cuja migração tenha terminado ou perdido sua chave antes disso, é enviada com status: "unknown" e sem transcrição.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

Para uma chamada vendor, o ThunderPhone não tem dados de cobrança ou extração: billable_minutes, billing_total_cents e extracted_data são null, product e voice estão vazios, recording_mode é vendor, e recording_url é o link da outra plataforma, quando ela forneceu um.

migration.rollback#

Enviado quando a mudança gradual de uma migração move todas as chamadas de volta para a outra plataforma automaticamente: 3 chamadas não conseguiram se conectar ao ThunderPhone em 15 minutos, 2 chamadas enviadas ao ThunderPhone terminaram antes de o agente atender, ou a taxa de resultado de tarefa do ThunderPhone ficou abaixo da outra plataforma por mais do que a diferença configurada. Sem bloqueio, uma vez por reversão. Depois disso, a participação do ThunderPhone é de 0% e a migração fica pausada até que alguém a retome na aba Migração do agente. A carga não contém números de telefone, transcrições nem IDs de chamadas.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

Relacionados#