Skip to main content
POST

Realizar chamada de campanha

Coloca uma chamada na fila de uma campanha. A chamada herda o agente, o agendamento, a política de retry e as regras de DNC da campanha. Para chamadas avulsas (sem agendamento da campanha), use Make a call.

Endpoint

Parâmetros de caminho

string
obrigatório
O identificador único da campanha.

Cabeçalhos da requisição

string
obrigatório
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here
string
obrigatório
Application JSON. Formato: application/json

Corpo da requisição

string
obrigatório
Número de telefone para chamar no formato E.164 (ex: “+5511987654321”).
object
Variáveis de substituição para o prompt do agente da campanha. Use isto para personalizar a conversa com dados dinâmicos. As chaves devem corresponder a placeholders no prompt do seu agente.
object
Dados customizados a serem enviados de volta ao seu cliente via webhooks. Estes dados não são usados na conversa, mas serão incluídos em todos os eventos de webhook relacionados a esta chamada, permitindo que você acompanhe e associe chamadas aos seus registros internos.
boolean
Se esta é uma chamada de teste. Chamadas de teste não consomem créditos de cobrança e são excluídas das agregações de analytics. Padrão: false.
boolean
Se permite realizar esta chamada mesmo que o mesmo número to já tenha uma chamada ativa ou enfileirada na campanha. Quando false (padrão), a requisição retorna 409 Conflict com os detalhes da chamada existente para que você possa evitar outreach duplicado. Padrão: false.

Exemplos de Requisição

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

object
obrigatório
Detalhes da chamada de campanha enfileirada.
object
obrigatório
Resumo da campanha pai no momento em que a chamada foi enfileirada.

Respostas de erro

409 Conflict — Chamada Duplicada

Retornado quando uma chamada para o mesmo número to já está ativa ou enfileirada nesta campanha e allow_duplicates é false.
Para sobrescrever este comportamento intencionalmente (ex: uma chamada de follow-up), passe "allow_duplicates": true no corpo da requisição.

404 Não Encontrado

422 Erro de Validação

400 Requisição Inválida

401 Não Autorizado

403 Proibido

429 Muitas Requisições

500 Erro do Servidor

Códigos de erro

Requisitos de Status da Campanha

Observações importantes

Contexto da campanha. Chamadas feitas através deste endpoint são associadas à campanha específica.
Configurações da campanha. A chamada seguirá a configuração da campanha (agente, lógica de retry, etc.).
Chamadas de teste. Use is_testing: true para chamadas de teste que não contam para a cobrança.
Apenas campanhas ativas. Chamadas só podem ser feitas para campanhas com status “active”.
Limites de taxa. Esteja ciente dos limites de taxa ao realizar múltiplas chamadas.

Melhores Práticas

  1. Verifique o status da campanha - Verifique se a campanha está ativa antes de realizar chamadas
  2. Use chamadas de teste - Teste sua integração com is_testing: true primeiro
  3. Lide com limites de taxa - Implemente rate limiting adequado em sua aplicação
  4. Valide números de telefone - Garanta que os números de telefone estejam no formato E.164
  5. Monitore o status da chamada - Acompanhe o status da chamada usando o call_id retornado

Endpoints relacionados

  • Obter Campanha: GET /api/v1/campaigns/{campaign_id}
  • Atualizar Status da Campanha: PATCH /api/v1/campaigns/{campaign_id}/status
  • Realizar uma Chamada: POST /api/v1/calls
  • Listar Chamadas: GET /api/v1/calls
  • Obter Chamadas do Agente: GET /api/v1/agents/{agent_id}/calls