# 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": "+5511987654321"
  }'

{
  "campaign_call": {
    "id": "call-uuid-1",
    "campaign_id": "campaign-uuid-1",
    "to": "+5511987654321",
    "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"
  }
}

POST

api

campaigns

{campaign_id}

call

# 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": "+5511987654321"
  }'

{
  "campaign_call": {
    "id": "call-uuid-1",
    "campaign_id": "campaign-uuid-1",
    "to": "+5511987654321",
    "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"
  }
}

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

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

Parâmetros de caminho

campaign

string

obrigatório

O identificador único da campanha.

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

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": "+5511987654321"
  }'

# 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": "+5511987654321",
    "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": "+5511976543210",
    "payload": {
      "customer_name": "Maria Silva",
      "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": "+5511987654321",
    "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": "+5511987654321",
    "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

Realizar uma Chamada Encerrar Chamada

​Realizar chamada de campanha

​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

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