Fazer uma ligação agora
Pede ao agente de voz que ligue agora para o número dado. A ligação custa dinheiro, então a Idempotency-Key é obrigatória: uma retentativa depois de um timeout devolve a primeira resposta em vez de discar de novo. Responde 201 com a ligação criada e dispatch: accepted: false não é erro — o serviço de voz recusou, a ligação consta como falha e dispatch.detail diz isso (o motivo técnico fica no log do servidor). Agente com a linha ocupada, ou com uma configuração de voz que não disca (o campo e o valor gravado vêm em error.details), responde 409; cliente bloqueado, 402; agente inativo ou arquivado, 422.
Autorização
bearer calls:executeCredencial da v3: o JWT da sessão (o mesmo da v2) ou um token pessoal dom_pat_…. A lista de escopos de cada operação diz o que ela exige: uma capacidade (agents:read), authenticated ou session-only. Segredo de máquina (X-Agent-Secret, X-API-Token, sdk_…) não é aceito.
Em: header
Escopo: calls:execute
Parâmetros de cabeçalho
Chave de 1 a 255 caracteres ASCII visíveis, estável por intenção do usuário: a mesma chave numa retentativa devolve a primeira resposta em vez de repetir o efeito.
Corpo da requisição
application/json
Definições TypeScript
Use o tipo request body no TypeScript.
Pedido de uma ligação agora.
O agente que liga é obrigatório: a v2 escolhia "o agente mais antigo" do cliente quando ele faltava (R11), e quem ligava descobria depois qual voz tinha atendido.
Corpo da resposta
application/json
application/json
curl -X POST "https://example.com/calls" \ -H "Idempotency-Key: b3f0c1e2-4a5b-4c6d-8e9f-0a1b2c3d4e5f" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "to_number": "string" }'{ "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "answered_at": "string", "contact_name": "string", "contact_phone": "string", "conversation_id": "cc71b11a-25cd-4c2d-9950-df2cc38e3407", "created_at": "string", "direction": "outbound", "duration_ms": 0, "ended_at": "string", "error": null, "from_number": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "job": null, "message_count": 0, "provider": "string", "result_summary": null, "started_at": "string", "status": "pending", "studio": true, "tenant_id": 0, "to_number": "string", "updated_at": "string", "dispatch": { "accepted": true, "detail": "string" }}