Skip to main content
POST

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

Cabeçalhos da requisição

string
obrigatório
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here
string
obrigatório
Deve ser definido como application/json

Corpo da requisição

Identificação

string
obrigatório
Nome da campanha. Máximo de 255 caracteres.
string
Descrição livre da campanha.
string
obrigatório
Categoria da campanha. Opções: sales, follow_up, reminder, custom.
string
obrigatório
UUID do agente atribuído à campanha. O agente deve existir em seu ambiente.

Agendamento

string
obrigatório
Data em que a campanha se torna elegível para despachar chamadas. Formato: YYYY-MM-DD.
string
Data de término opcional. Deve ser após start_date. Formato: YYYY-MM-DD.
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.
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"}]
string
obrigatório
Fuso horário IANA para call_time_ranges (ex: America/Sao_Paulo, America/Sao_Paulo, Europe/London). Máximo de 50 caracteres.

Retry e Cooldown

integer
Atraso inicial (em segundos) antes da primeira tentativa de chamada. Padrão: 0.
integer
Tentativas máximas de retry por contato. Faixa: 010. Padrão: 3.
integer
Horas a aguardar entre tentativas de retry. Faixa: 1168. Padrão: 24.
boolean
Quando true, a campanha automaticamente transita para completed assim que todos os contatos forem processados.
boolean
Quando true, chamadas que foram completadas mas não converteram são retentadas após o 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).
integer
Horas de cooldown aplicadas aos contatos após a conclusão da campanha. Faixa: 1168. Padrão: 168.

Cooldowns por status

Estes campos opcionais sobrescrevem retry_cooldown_hours para resultados de chamada específicos. Todos na faixa 1168 horas.
integer
Cooldown após uma chamada bem-sucedida.
integer
Cooldown após cair no correio de voz.
integer
Cooldown após sem resposta.
integer
Cooldown após sinal de ocupado.
integer
Cooldown após uma chamada com falha.

Do-Not-Call (DNC)

boolean
Quando true, os contatos são verificados em uma lista DNC antes do despacho. Padrão: false.
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
array
Array de números de telefone (E.164) bloqueados para esta campanha. Usado apenas quando do_not_call_list_source é custom.
boolean
Quando true, contatos que correspondem a auto_dnc_trigger_statuses ou auto_dnc_trigger_errors são automaticamente adicionados à lista DNC.
array
Status de chamada que acionam a adição automática ao DNC. Exemplo: ["completed", "voicemail"].
array
Erros de chamada que acionam a adição automática ao DNC. Exemplo: ["invalid_number", "disconnected"].

Exemplos

Resposta

Resposta de Sucesso (201 Created)

Campos da Resposta

boolean
obrigatório
Indica se a campanha foi criada com sucesso.
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

401 Não Autorizado

403 Proibido — Limite do Plano Atingido

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.

Endpoints relacionados