Pular para o conteúdo principal
PATCH
/
api
/
v1
/
campaigns
/
{campaign_id}
/
status
# Requisição 1: Ativar uma campanha
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

{
  "success": true,
  "message": "Status da campanha atualizado com sucesso",
  "data": {
    "id": "campaign-uuid-1",
    "status": "active"
  }
}

​
Atualizar Status da Campanha

Atualizar o status de uma campanha específica. Controla o ciclo de vida da campanha (rascunho, ativa, pausada, concluída, cancelada).

​
Endpoint

PATCH /api/v1/campaigns/{campaign_id}/status

​
Parâmetros de caminho

​
campaign
string
obrigatório
O identificador único da campanha. Você pode encontrá-lo na lista de campanhas.

​
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
Application JSON. Formato: application/json

​
Corpo da requisição

​
status
string
obrigatório
Novo status da campanha. Opções: draft, active, paused, completed, cancelled

​
Valores de Status Válidos

  • draft - Campanha está em modo rascunho
  • active - Campanha está em execução
  • paused - Campanha está pausada
  • completed - Campanha foi finalizada
  • cancelled - Campanha foi cancelada

​
Exemplos de Requisição

# Requisição 1: Ativar uma campanha
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

# Requisição 2: Pausar uma campanha
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

​
Resposta

​
Resposta de Sucesso (200 OK)

{
  "success": true,
  "message": "Status da campanha atualizado com sucesso",
  "data": {
    "id": "campaign-uuid-1",
    "status": "active"
  }
}

​
Campos da Resposta

​
success
boolean
obrigatório
Indica se a operação foi bem-sucedida.
​
message
string
obrigatório
Mensagem de sucesso descrevendo a operação.
​
data
object
obrigatório
Dados da campanha atualizada.

​
Respostas de erro

​
404 Não Encontrado

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

​
422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "status": [
      "The selected status is invalid."
    ],
    "status": [
      "The status field is required."
    ]
  }
}

​
409 Conflito

{
  "success": false,
  "message": "Invalid status transition"
}

​
401 Não Autorizado

{
  "success": false,
  "message": "Unauthorized"
}

​
500 Erro do Servidor

{
  "success": false,
  "message": "Internal server error."
}

​
Códigos de erro

CódigoDescriçãoStatus HTTP
CAMPAIGN_NOT_FOUNDCampanha especificada não existe404
VALIDATION_ERRORValidação da requisição falhou422
INVALID_STATUS_TRANSITIONTransição de status inválida409
INVALID_TOKENToken de autenticação inválido ou ausente401
SERVER_ERRORErro interno do servidor ocorreu500

​
Regras de Transição de Status

draft → active - Permitido quando a campanha está configurada corretamente
active → paused - Permitido a qualquer momento
paused → active - Permitido a qualquer momento
active/paused → completed - Permitido quando todas as chamadas foram processadas
draft/active/paused → cancelled - Permitido a qualquer momento
Transições irreversíveis. Algumas transições de status não podem ser desfeitas.

​
Notas Importantes

Controle de fluxo. Use este endpoint para controlar o ciclo de vida da campanha.
Validação de transição. O sistema valida se a transição de status é permitida.
Impacto nas chamadas. Mudanças de status podem afetar chamadas em andamento.
Status final. Status como completed e cancelled são finais e não podem ser alterados.

​
Melhores Práticas

  1. Planeje transições - Entenda as regras de transição antes de alterar status
  2. Monitore impacto - Acompanhe como mudanças de status afetam as chamadas
  3. Use pausa temporária - Use paused para interromper temporariamente sem cancelar
  4. Confirme finalização - Certifique-se de que deseja finalizar antes de usar completed
  5. Documente mudanças - Mantenha registro das mudanças de status da campanha

​
Endpoints relacionados

  • Listar Campanhas: GET /api/v1/campaigns
  • Criar Campanha: POST /api/v1/campaigns
  • Obter Campanha: GET /api/v1/campaigns/{campaign_id}
  • Atualizar Campanha: PUT /api/v1/campaigns/{campaign_id}
  • Excluir Campanha: DELETE /api/v1/campaigns/{campaign_id}
  • Fazer Chamada de Campanha: POST /api/v1/campaigns/{campaign_id}/call