Realizar Chamada de Campanha

Inicia uma chamada como parte de uma campanha específica. Este endpoint permite que você acione manualmente chamadas dentro de um contexto de campanha.

Visão Geral

O endpoint Realizar Chamada de Campanha permite que você inicie chamadas individuais dentro de uma campanha existente. Este endpoint utiliza a configuração e os ajustes da campanha para garantir que as chamadas sigam as regras e parâmetros estabelecidos pela campanha.

Chamadas de Campanha vs Chamadas Individuais de Agente

Chamadas de Campanha - Alcance Estratégico e Automatizado

Chamadas de campanha são projetadas para engajamento sistemático e em larga escala com recursos avançados de automação:

Configurações Específicas da Campanha: Cada chamada herda a configuração da campanha (agente, lógica de retry, períodos de cooldown, horários de chamada)
Agendamento Avançado: Chamadas respeitam automaticamente o horário comercial, configurações de fuso horário e restrições de dia da semana
Lógica de Retry: Mecanismos de retry integrados com períodos de cooldown configuráveis entre tentativas
Gerenciamento de Fluxo de Chamada: Fluxos de chamada e mensagens consistentes em todas as chamadas da campanha
Analytics de Desempenho: Rastreamento e relatórios abrangentes no nível da campanha
Recursos de Compliance: Gerenciamento de listas do-not-call e ferramentas de conformidade regulatória
Processamento em Lote: Lida com milhares de chamadas com enfileiramento inteligente e rate limiting

Melhor para: Campanhas de outreach, nutrição de leads, lembretes de compromissos, pesquisas de mercado, e qualquer cenário que exija chamadas consistentes e automatizadas com regras sofisticadas.

Chamadas Individuais de Agente - Interação Imediata e Personalizada

Chamadas individuais de agente são perfeitas para interações instantâneas e pontuais que requerem atenção imediata:

Execução Instantânea: Chamadas são feitas imediatamente sem esperar o agendamento da campanha
Contexto em Tempo Real: Perfeito para follow-ups imediatos após submissões de formulários ou ações do cliente
Parâmetros Flexíveis: Customize parâmetros de chamada na hora para situações específicas
Controle Direto: Controle imediato sobre o timing e a execução da chamada
Toque Pessoal: Ideal para interações de alto valor que exigem atenção humana imediata

Melhor para: Follow-ups de formulários, atendimento imediato ao cliente, agendamentos urgentes, leads de alta prioridade, e qualquer situação que exija resposta instantânea.

Quando Usar Cada Abordagem

Cenário	Use Chamada de Campanha	Use Chamada Individual de Agente
Cliente preenche formulário de contato	❌	✅ Follow-up imediato
Nutrição de lead ao longo do tempo	✅ Sequência automatizada	❌
Lembretes de compromissos	✅ Outreach agendado	❌
Problema urgente do cliente	❌	✅ Resposta instantânea
Pesquisa de mercado	✅ Chamadas em larga escala	❌
Follow-up de venda após demo	❌	✅ Conversão rápida
Chamadas de satisfação do cliente	✅ Outreach sistemático	❌

Endpoint

POST /api/v1/campaigns/{campaign_id}/call

Parâmetros de Caminho

campaign

string

obrigatório

O identificador único da campanha. Você pode encontrá-lo em seu painel, na seção Campanhas.

Cabeçalhos da Requisição

Authorization

string

obrigatório

Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here

Content-Type

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: “+1234567890”).

payload

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.

context

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.

is_testing

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.

allow_duplicates

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

# Request 1: Make a regular campaign call
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890"
  }'

# Request 2: Make a test campaign call
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "is_testing": true
  }'

# Request 3: Make campaign call with payload and context
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1987654321",
    "payload": {
      "customer_name": "John Doe",
      "order_id": "12345",
      "product_name": "Premium Plan"
    },
    "context": {
      "user_id": "user_123",
      "source": "web_app",
      "campaign_batch": "2024_Q1"
    }
  }'

Resposta

Resposta de Sucesso (201 Created)

{
  "campaign_call": {
    "id": "call-uuid-1",
    "campaign_id": "campaign-uuid-1",
    "to": "+1234567890",
    "status": "queued",
    "scheduled_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "campaign": {
    "id": "campaign-uuid-1",
    "name": "Q1 Outreach",
    "status": "active"
  }
}

Campos da Resposta

campaign_call

object

obrigatório

Detalhes da chamada de campanha enfileirada.

Mostrar Objeto de Chamada de Campanha

string

obrigatório

Identificador único da chamada de campanha. Use isto para acompanhar o status e correlacionar com eventos de webhook.

campaign_id

string

obrigatório

A campanha à qual esta chamada pertence.

string

obrigatório

O número de telefone que será chamado.

status

string

obrigatório

Status inicial da chamada de campanha. Valores possíveis:

queued — chamada aceita e aguardando despacho
scheduled — chamada agendada para ser realizada em horário futuro dentro do horário da campanha

scheduled_at

string

Timestamp ISO 8601 quando a chamada deve ser realizada.

created_at

string

obrigatório

Timestamp ISO 8601 quando a chamada de campanha foi criada.

campaign

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.

{
  "success": false,
  "message": "A call to this number already exists in this campaign",
  "existing_call": {
    "id": "call-uuid-existing",
    "campaign_id": "campaign-uuid-1",
    "to": "+1234567890",
    "status": "queued",
    "created_at": "2024-01-15T09:50:00Z"
  }
}

Para sobrescrever este comportamento intencionalmente (ex: uma chamada de follow-up), passe "allow_duplicates": true no corpo da requisição.

404 Não Encontrado

{
  "success": false,
  "message": "Campaign not found"
}

422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "to": [
      "The to field is required."
    ],
    "to": [
      "The to must be a valid phone number."
    ]
  }
}

400 Requisição Inválida

{
  "success": false,
  "message": "Campaign is not active"
}

401 Não Autorizado

{
  "success": false,
  "message": "Unauthorized"
}

403 Proibido

{
  "success": false,
  "message": "Cannot make calls for this campaign"
}

429 Muitas Requisições

{
  "success": false,
  "message": "Rate limit exceeded"
}

500 Erro do Servidor

{
  "success": false,
  "message": "Internal server error."
}

Códigos de Erro

Código	Descrição	Status HTTP
`CAMPAIGN_NOT_FOUND`	A campanha especificada não existe	404
`VALIDATION_ERROR`	A validação da requisição falhou	422
`CAMPAIGN_NOT_ACTIVE`	A campanha não está com status ativo	400
`DUPLICATE_CALL`	Uma chamada existente para o mesmo número está enfileirada ou ativa	409
`INVALID_TOKEN`	Token de autenticação inválido ou ausente	401
`FORBIDDEN`	Não é possível realizar chamadas para esta campanha	403
`RATE_LIMIT_EXCEEDED`	Limite de taxa excedido	429
`SERVER_ERROR`	Erro interno do servidor ocorreu	500

Requisitos de Status da Campanha

Status da Campanha	Pode Realizar Chamadas	Observações
`draft`	❌ Não	A campanha precisa estar ativa
`active`	✅ Sim	Chamadas podem ser feitas
`paused`	❌ Não	A campanha está pausada
`completed`	❌ Não	A campanha foi finalizada
`cancelled`	❌ Não	A campanha foi cancelada

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

Verifique o status da campanha - Verifique se a campanha está ativa antes de realizar chamadas
Use chamadas de teste - Teste sua integração com is_testing: true primeiro
Lide com limites de taxa - Implemente rate limiting adequado em sua aplicação
Valide números de telefone - Garanta que os números de telefone estejam no formato E.164
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

Primeiros Passos

Conceitos

Referência da API

Guias

Realizar Chamada de Campanha

Realizar Chamada de Campanha

Visão Geral

Chamadas de Campanha vs Chamadas Individuais de Agente

Chamadas de Campanha - Alcance Estratégico e Automatizado

Chamadas Individuais de Agente - Interação Imediata e Personalizada

Quando Usar Cada Abordagem

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

Respostas de Erro

409 Conflict — Chamada Duplicada

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

Melhores Práticas

Endpoints Relacionados

Primeiros Passos

Conceitos

Referência da API

Guias

Documentation Index

​Realizar Chamada de Campanha

​Visão Geral

​Chamadas de Campanha vs Chamadas Individuais de Agente

​Chamadas de Campanha - Alcance Estratégico e Automatizado

​Chamadas Individuais de Agente - Interação Imediata e Personalizada

​Quando Usar Cada Abordagem

​Endpoint

​Parâmetros de Caminho

​Cabeçalhos da Requisição

​Corpo da Requisição

​Exemplos de Requisição

​Resposta

​Resposta de Sucesso (201 Created)

​Campos da Resposta

​Respostas de Erro

​409 Conflict — Chamada Duplicada

​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

​Melhores Práticas

​Endpoints Relacionados

Realizar Chamada de Campanha

Visão Geral

Chamadas de Campanha vs Chamadas Individuais de Agente

Chamadas de Campanha - Alcance Estratégico e Automatizado

Chamadas Individuais de Agente - Interação Imediata e Personalizada

Quando Usar Cada Abordagem

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

Respostas de Erro

409 Conflict — Chamada Duplicada

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

Melhores Práticas

Endpoints Relacionados