Pular para o conteúdo principal
PUT
/
api
/
v1
/
campaigns
/
{campaign_id}
# Update only the call windows + timezone
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo"
  }'

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "campaign_type": "sales",
    "status": "active",
    "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": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Atualizar Campanha

Atualiza parcialmente uma campanha existente. Todos os campos são opcionais — apenas os campos que você enviar serão atualizados. Use Atualizar Status da Campanha para alterar apenas o status (draft → active → paused → completed).

​
Endpoint

PUT /api/v1/campaigns/{campaign_id}

​
Parâmetros de Caminho

​
campaign_id
string
obrigatório
UUID da campanha a ser atualizada.

​
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

Todos os campos são opcionais. Envie apenas o que você quer alterar. As regras de validação e faixas correspondem a Criar Campanha.

​
Identificação

​
name
string
Nome da campanha. Máximo de 255 caracteres.
​
description
string
Descrição livre.
​
campaign_type
string
Categoria da campanha. Opções: sales, follow_up, reminder, custom.
​
agent_id
string
UUID do agente. Deve existir em seu ambiente.

​
Agendamento

​
start_date
string
Formato: YYYY-MM-DD.
​
end_date
string
Data de término opcional. Deve ser após start_date. Formato: YYYY-MM-DD. Envie null para limpar.
​
days_of_week
array
Array de números de dias da semana (1–7, onde 1 = Segunda-feira). Mínimo de 1 entrada.
​
call_time_ranges
array
Janelas de horário. Array de objetos {start: "HH:MM", end: "HH:MM"} (formato 24h). Mínimo de 1 entrada. O end de cada janela deve ser após seu start.
​
timezone
string
Fuso horário IANA (ex: America/New_York). Máximo de 50 caracteres.

​
Retry e Cooldown

​
initial_call_delay
integer
Atraso inicial em segundos. Faixa: 0+.
​
max_retries
integer
Faixa: 0–10.
​
retry_cooldown_hours
integer
Faixa: 1–168.
​
auto_complete
boolean
Auto-transição para completed quando todos os contatos forem processados.
​
retry_on_no_conversion
boolean
Retenta chamadas que foram completadas sem conversão.
​
enable_post_completion_cooldown
boolean
​
post_completion_cooldown_hours
integer
Faixa: 1–168.
​
success_cooldown_hours
integer
Faixa: 1–168.
​
voicemail_cooldown_hours
integer
Faixa: 1–168.
​
no_answer_cooldown_hours
integer
Faixa: 1–168.
​
busy_cooldown_hours
integer
Faixa: 1–168.
​
failed_cooldown_hours
integer
Faixa: 1–168.

​
Do-Not-Call (DNC)

​
do_not_call_enabled
boolean
​
do_not_call_list_source
string
Opções: environment, global, custom.
​
do_not_call_custom_list
array
Array de números de telefone (E.164). Usado quando do_not_call_list_source é custom.
​
auto_add_to_dnc_enabled
boolean
​
auto_dnc_trigger_statuses
array
​
auto_dnc_trigger_errors
array

​
Exemplos

# Update only the call windows + timezone
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo"
  }'

# Switch to custom DNC list and tighten retry policy
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "max_retries": 2,
    "retry_cooldown_hours": 12,
    "success_cooldown_hours": 168,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "custom",
    "do_not_call_custom_list": ["+15551234567"],
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed"]
  }'

​
Resposta

​
Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "campaign_type": "sales",
    "status": "active",
    "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": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

​
Respostas de Erro

​
422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "call_time_ranges.0.end": [
      "The call time ranges.0.end must be a date after call time ranges.0.start."
    ]
  }
}

​
404 Não Encontrada

{
  "success": false,
  "message": "Campaign not found"
}

​
409 Conflict — Chamadas Ativas

{
  "success": false,
  "message": "Cannot update schedule while there are queued calls. Pause the campaign first.",
  "code": "CAMPAIGN_HAS_ACTIVE_CALLS"
}

​
Observações

  • Use PATCH /v1/campaigns/{id}/status para alterar o status — é um endpoint separado com sua própria validação.
  • Atualizar call_time_ranges ou timezone enquanto a campanha está active pode atrasar chamadas enfileiradas até que elas voltem a se encaixar nas novas janelas.
  • Enviar "end_date": null limpa uma data de término previamente definida.

​
Endpoints Relacionados