Criar Campanha

Cria uma nova campanha com agendamento, política de retry, cooldowns e regras de do-not-call. Campanhas são criadas com status draft — chame Atualizar Status da Campanha com "status": "active" para começar a despachar chamadas.

Endpoint

POST /api/v1/campaigns

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

Deve ser definido como application/json

Corpo da Requisição

Identificação

name

string

obrigatório

Nome da campanha. Máximo de 255 caracteres.

description

string

Descrição livre da campanha.

campaign_type

string

obrigatório

Categoria da campanha. Opções: sales, follow_up, reminder, custom.

agent_id

string

obrigatório

UUID do agente atribuído à campanha. O agente deve existir em seu ambiente.

Agendamento

start_date

string

obrigatório

Data em que a campanha se torna elegível para despachar chamadas. Formato: YYYY-MM-DD.

end_date

string

Data de término opcional. Deve ser após start_date. Formato: YYYY-MM-DD.

days_of_week

array

obrigatório

Array de números de dias da semana quando chamadas podem ser realizadas. 1 = Segunda-feira, 7 = Domingo. Pelo menos um valor obrigatório.

call_time_ranges

array

obrigatório

Janelas de horário (por dia) durante as quais as chamadas podem ser despachadas. Array de objetos com start e end no formato HH:MM (24h). Pelo menos uma janela obrigatória. O end de cada janela deve ser após seu start.Exemplo: [{"start": "09:00", "end": "12:00"}, {"start": "14:00", "end": "17:00"}]

timezone

string

obrigatório

Fuso horário IANA para call_time_ranges (ex: America/New_York, America/Sao_Paulo, Europe/London). Máximo de 50 caracteres.

Retry e Cooldown

initial_call_delay

integer

Atraso inicial (em segundos) antes da primeira tentativa de chamada. Padrão: 0.

max_retries

integer

Tentativas máximas de retry por contato. Faixa: 0–10. Padrão: 3.

retry_cooldown_hours

integer

Horas a aguardar entre tentativas de retry. Faixa: 1–168. Padrão: 24.

auto_complete

boolean

Quando true, a campanha automaticamente transita para completed assim que todos os contatos forem processados.

retry_on_no_conversion

boolean

Quando true, chamadas que foram completadas mas não converteram são retentadas após o cooldown.

enable_post_completion_cooldown

boolean

Quando true, aplica um cooldown a todos os contatos após a conclusão da campanha (impede re-engajamento imediato por outra campanha).

post_completion_cooldown_hours

integer

Horas de cooldown aplicadas aos contatos após a conclusão da campanha. Faixa: 1–168. Padrão: 168.

Cooldowns por status

Estes campos opcionais sobrescrevem retry_cooldown_hours para resultados de chamada específicos. Todos na faixa 1–168 horas.

success_cooldown_hours

integer

Cooldown após uma chamada bem-sucedida.

voicemail_cooldown_hours

integer

Cooldown após cair no correio de voz.

no_answer_cooldown_hours

integer

Cooldown após sem resposta.

busy_cooldown_hours

integer

Cooldown após sinal de ocupado.

failed_cooldown_hours

integer

Cooldown após uma chamada com falha.

Do-Not-Call (DNC)

do_not_call_enabled

boolean

Quando true, os contatos são verificados em uma lista DNC antes do despacho. Padrão: false.

do_not_call_list_source

string

Origem da lista DNC. Opções:

environment — lista DNC compartilhada entre todas as campanhas neste ambiente
global — lista DNC global da plataforma
custom — lista específica da campanha fornecida em do_not_call_custom_list

do_not_call_custom_list

array

Array de números de telefone (E.164) bloqueados para esta campanha. Usado apenas quando do_not_call_list_source é custom.

auto_add_to_dnc_enabled

boolean

Quando true, contatos que correspondem a auto_dnc_trigger_statuses ou auto_dnc_trigger_errors são automaticamente adicionados à lista DNC.

auto_dnc_trigger_statuses

array

Status de chamada que acionam a adição automática ao DNC. Exemplo: ["completed", "voicemail"].

auto_dnc_trigger_errors

array

Erros de chamada que acionam a adição automática ao DNC. Exemplo: ["invalid_number", "disconnected"].

Exemplos

# Basic sales campaign — weekdays 09:00–17:00 New York
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York"
  }'

# Campaign with split call windows + custom DNC + per-status cooldowns
curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up Campaign",
    "campaign_type": "follow_up",
    "agent_id": "agent-uuid-2",
    "start_date": "2024-01-15",
    "end_date": "2024-03-31",
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "17:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 5,
    "retry_cooldown_hours": 48,
    "success_cooldown_hours": 168,
    "voicemail_cooldown_hours": 24,
    "no_answer_cooldown_hours": 12,
    "busy_cooldown_hours": 6,
    "failed_cooldown_hours": 72,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "custom",
    "do_not_call_custom_list": ["+15551234567", "+15559876543"],
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed"],
    "auto_dnc_trigger_errors": ["invalid_number"]
  }'

Resposta

Resposta de Sucesso (201 Created)

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "description": "Outbound sales campaign for Q1",
    "campaign_type": "sales",
    "status": "draft",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "09:00", "end": "17:00"}
    ],
    "timezone": "America/New_York",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Campos da Resposta

success

boolean

obrigatório

Indica se a campanha foi criada com sucesso.

data

object

obrigatório

O objeto da campanha criada. Novas campanhas começam com status: "draft". Use Atualizar Status da Campanha para ativar.

Respostas de Erro

422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "agent_id": ["The selected agent id is invalid."],
    "call_time_ranges": ["The call time ranges field is required."],
    "call_time_ranges.0.end": ["The call time ranges.0.end must be a date after call time ranges.0.start."],
    "days_of_week.0": ["The days of week.0 must be between 1 and 7."]
  }
}

401 Não Autorizado

{
  "message": "Missing Bearer Token"
}

403 Proibido — Limite do Plano Atingido

{
  "success": false,
  "message": "Your plan does not allow creating more campaigns",
  "code": "CAMPAIGN_LIMIT_REACHED"
}

Observações

O agente da campanha já deve existir. Crie-o via Criar Agente.
call_time_ranges substitui os campos antigos earliest_call_time/latest_call_time. Múltiplas janelas permitem pular o horário de almoço ou dividir entre manhã e tarde.
Todos os campos *_cooldown_hours têm padrão de 24 se não fornecidos. Use-os para ajustar o comportamento de retry por resultado de chamada.
As janelas de horário são avaliadas no timezone da campanha, não no horário local do chamador.

Primeiros Passos

Conceitos

Referência da API

Guias

Criar Campanha

Criar Campanha

Endpoint

Cabeçalhos da Requisição

Corpo da Requisição

Identificação

Agendamento

Retry e Cooldown

Cooldowns por status

Do-Not-Call (DNC)

Exemplos

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

Respostas de Erro

422 Erro de Validação

401 Não Autorizado

403 Proibido — Limite do Plano Atingido

Observações

Endpoints Relacionados

Primeiros Passos

Conceitos

Referência da API

Guias

Documentation Index

​Criar Campanha

​Endpoint

​Cabeçalhos da Requisição

​Corpo da Requisição

​Identificação

​Agendamento

​Retry e Cooldown

​Cooldowns por status

​Do-Not-Call (DNC)

​Exemplos

​Resposta

​Resposta de Sucesso (201 Created)

​Campos da Resposta

​Respostas de Erro

​422 Erro de Validação

​401 Não Autorizado

​403 Proibido — Limite do Plano Atingido

​Observações

​Endpoints Relacionados

Criar Campanha

Endpoint

Cabeçalhos da Requisição

Corpo da Requisição

Identificação

Agendamento

Retry e Cooldown

Cooldowns por status

Do-Not-Call (DNC)

Exemplos

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

Respostas de Erro

422 Erro de Validação

401 Não Autorizado

403 Proibido — Limite do Plano Atingido

Observações

Endpoints Relacionados