Chamadas e Campanhas
Criar Campanha
Criar uma nova campanha com agendamento, lógica de retry e regras de do-not-call
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 statusdraft — chame Atualizar Status da Campanha com "status": "active" para começar a despachar chamadas.
Endpoint
Cabeçalhos da requisição
Token Bearer para autenticação. Formato:
Bearer talq_your_environment_token_hereDeve ser definido como
application/jsonCorpo da requisição
Identificação
Nome da campanha. Máximo de 255 caracteres.
Descrição livre da campanha.
Categoria da campanha. Opções:
sales, follow_up, reminder, custom.UUID do agente atribuído à campanha. O agente deve existir em seu ambiente.
Agendamento
Data em que a campanha se torna elegível para despachar chamadas. Formato:
YYYY-MM-DD.Data de término opcional. Deve ser após
start_date. Formato: YYYY-MM-DD.Array de números de dias da semana quando chamadas podem ser realizadas.
1 = Segunda-feira, 7 = Domingo. Pelo menos um valor 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"}]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
Atraso inicial (em segundos) antes da primeira tentativa de chamada. Padrão:
0.Tentativas máximas de retry por contato. Faixa:
0–10. Padrão: 3.Horas a aguardar entre tentativas de retry. Faixa:
1–168. Padrão: 24.Quando
true, a campanha automaticamente transita para completed assim que todos os contatos forem processados.Quando
true, chamadas que foram completadas mas não converteram são retentadas após o cooldown.Quando
true, aplica um cooldown a todos os contatos após a conclusão da campanha (impede re-engajamento imediato por outra campanha).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 sobrescrevemretry_cooldown_hours para resultados de chamada específicos. Todos na faixa 1–168 horas.
Cooldown após uma chamada bem-sucedida.
Cooldown após cair no correio de voz.
Cooldown após sem resposta.
Cooldown após sinal de ocupado.
Cooldown após uma chamada com falha.
Do-Not-Call (DNC)
Quando
true, os contatos são verificados em uma lista DNC antes do despacho. Padrão: false.Origem da lista DNC. Opções:
environment— lista DNC compartilhada entre todas as campanhas neste ambienteglobal— lista DNC global da plataformacustom— lista específica da campanha fornecida emdo_not_call_custom_list
Array de números de telefone (E.164) bloqueados para esta campanha. Usado apenas quando
do_not_call_list_source é custom.Quando
true, contatos que correspondem a auto_dnc_trigger_statuses ou auto_dnc_trigger_errors são automaticamente adicionados à lista DNC.Status de chamada que acionam a adição automática ao DNC. Exemplo:
["completed", "voicemail"].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
Indica se a campanha foi criada com sucesso.
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_rangessubstitui os campos antigosearliest_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_hourstêm padrão de24se não fornecidos. Use-os para ajustar o comportamento de retry por resultado de chamada. - As janelas de horário são avaliadas no
timezoneda campanha, não no horário local do chamador.