# 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/Sao_Paulo"
}'
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'POST',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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/Sao_Paulo'
})
});
const result = await response.json();
import requests
url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
"Authorization": "Bearer talq_your_environment_token_here",
"Content-Type": "application/json"
}
data = {
"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/Sao_Paulo"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
{
"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/Sao_Paulo",
"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"
}
}
Chamadas e Campanhas
Criar Campanha
Criar uma nova campanha com agendamento, lógica de retry e regras de do-not-call
POST
/
api
/
v1
/
campaigns
# 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/Sao_Paulo"
}'
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'POST',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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/Sao_Paulo'
})
});
const result = await response.json();
import requests
url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
"Authorization": "Bearer talq_your_environment_token_here",
"Content-Type": "application/json"
}
data = {
"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/Sao_Paulo"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
{
"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/Sao_Paulo",
"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"
}
}
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
POST /api/v1/campaigns
Cabeçalhos da requisição
string
obrigatório
Token Bearer para autenticação. Formato:
Bearer talq_your_environment_token_herestring
obrigatório
Deve ser definido como
application/jsonCorpo 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:
0–10. Padrão: 3.integer
Horas a aguardar entre tentativas de retry. Faixa:
1–168. 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:
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.
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 ambienteglobal— lista DNC global da plataformacustom— lista específica da campanha fornecida emdo_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
# 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/Sao_Paulo"
}'
const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
method: 'POST',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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/Sao_Paulo'
})
});
const result = await response.json();
import requests
url = "https://app.talkover.ai/api/v1/campaigns"
headers = {
"Authorization": "Bearer talq_your_environment_token_here",
"Content-Type": "application/json"
}
data = {
"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/Sao_Paulo"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
# 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": ["+5511987654321", "+5511976543210"],
"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/Sao_Paulo",
"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
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
{
"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_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.
Endpoints relacionados
Esta página foi útil?