Status de Campanhas - API Disparador

Esta página descreve todos os status possíveis para campanhas, incluindo transições válidas e comportamentos esperados.

Status de Campanha

As campanhas possuem 6 status principais que representam seu ciclo de vida:

DRAFT

Rascunho - Campanha criada mas ainda não iniciada

SCHEDULED

Agendada - Campanha programada para execução futura

RUNNING

Em Execução - Campanha enviando mensagens ativamente

PAUSED

Pausada - Campanha temporariamente suspensa

COMPLETED

Concluída - Todas as mensagens foram processadas

CANCELLED

Cancelada - Campanha interrompida permanentemente

Fluxo de Status

Diagrama de Transições

Regras de Transição

✅ Transições Permitidas

Status Atual	Status Destino	Ação/Trigger	Condições
DRAFT	RUNNING	Criar sem agendamento	Execução imediata
DRAFT	SCHEDULED	Criar com agendamento	Data futura definida
SCHEDULED	RUNNING	Automático	Horário agendado chegou
SCHEDULED	CANCELLED	Cancelar	Antes da execução
RUNNING	PAUSED	Pausar	A qualquer momento
RUNNING	COMPLETED	Automático	Todas mensagens enviadas
RUNNING	CANCELLED	Cancelar	A qualquer momento
PAUSED	RUNNING	Retomar	Dentro do prazo
PAUSED	CANCELLED	Cancelar	A qualquer momento

❌ Transições Não Permitidas

Status Atual	Status Destino	Motivo
COMPLETED	Qualquer	Campanha já finalizada
CANCELLED	Qualquer	Campanha cancelada permanentemente
DRAFT	PAUSED	Não pode pausar antes de iniciar
SCHEDULED	PAUSED	Não pode pausar campanha agendada
PAUSED	SCHEDULED	Não pode reagendar campanha pausada

Comportamentos por Status

DRAFT (Rascunho)

Características

Status inicial de toda campanha criada com isDraft: true
Nenhuma mensagem enviada
Pode ser iniciada imediatamente ou agendada
Configurações podem ser alteradas livremente
Sem limite de tempo neste status

Campos importantes:

createdAt: Data de criação
sentCount: Sempre 0
status: “DRAFT”
totalContacts: Número de contatos definidos

SCHEDULED (Agendada)

Características

Campanha aguardando horário programado
Worker verifica a cada minuto por campanhas prontas
Inicia automaticamente no horário definido
Pode ser cancelada antes do início
Notificação enviada quando inicia (se configurado)

Campos importantes:

scheduledFor: Data/hora programada
status: “SCHEDULED”
sentCount: Sempre 0
message: Pode estar vazio se for enquete

RUNNING (Em Execução)

Características

Enviando mensagens ativamente
Respeita intervalos configurados
Atualiza contadores em tempo real
Pode ser pausada ou cancelada
Remove automaticamente contatos bloqueados

Campos importantes:

startedAt: Momento do início real
sentCount: Incrementado a cada envio
failedCount: Contador de falhas
status: “RUNNING”
progress: Percentual calculado

PAUSED (Pausada)

Características

Interrupção temporária do envio
Mantém posição na fila de contatos
Pode ser retomada ou cancelada
Tempo máximo de pausa configurável
Estado preservado para continuação

Campos importantes:

pausedAt: Momento da pausa
sentCount: Congelado no valor atual
status: “PAUSED”
remainingContacts: Calculado dinamicamente

Por padrão, campanhas pausadas há mais de 24 horas são canceladas automaticamente.

COMPLETED (Concluída)

Características

Todos os contatos foram processados
Status final bem-sucedido
Não pode ser modificada
Estatísticas finais disponíveis
Notificação de conclusão enviada (se configurado)

Campos importantes:

completedAt: Momento da conclusão
sentCount: Total de enviados com sucesso
failedCount: Total de falhas
duration: Tempo total de execução

CANCELLED (Cancelada)

Características

Interrupção permanente
Não pode ser retomada
Mantém histórico parcial
Libera recursos do sistema
Registra motivo do cancelamento

Campos importantes:

cancelledAt: Momento do cancelamento
cancelledBy: Usuário ou sistema
sentCount: Mensagens enviadas antes do cancelamento
reason: Motivo (manual, timeout, erro)

Campos de Controle

Timestamps

interface CampaignTimestamps {
  createdAt: Date;         // Criação da campanha
  scheduledFor?: Date;     // Agendamento (se aplicável)
  startedAt?: Date;        // Início real da execução
  pausedAt?: Date;         // Última pausa
  resumedAt?: Date;        // Última retomada
  completedAt?: Date;      // Conclusão
  cancelledAt?: Date;      // Cancelamento
  updatedAt: Date;         // Última modificação
}

Contadores

interface CampaignCounters {
  totalContacts: number;         // Total de contatos
  sentCount: number;             // Mensagens enviadas
  failedCount: number;           // Falhas de envio
  blockedContactsRemoved: number; // Removidos por bloqueio
  progress: number;              // Percentual (0-100)
}

API de Transições

Pausar Campanha

PUT /api/campaigns/{id}/pause
Authorization: Bearer {token}

Pré-condições:

Status atual: RUNNING
Campanha pertence à empresa do token

Resposta:

{
  "success": true,
  "data": {
    "id": 123,
    "status": "PAUSED",
    "pausedAt": "2024-01-16T10:30:00Z",
    "sentCount": 500,
    "totalContacts": 1000
  }
}

Retomar Campanha

PUT /api/campaigns/{id}/resume
Authorization: Bearer {token}

Pré-condições:

Status atual: PAUSED
Dentro do prazo permitido
Evolution API conectada

Resposta:

{
  "success": true,
  "data": {
    "id": 123,
    "status": "RUNNING",
    "resumedAt": "2024-01-16T11:00:00Z"
  }
}

Cancelar Campanha

PUT /api/campaigns/{id}/cancel
Authorization: Bearer {token}

Pré-condições:

Status atual: SCHEDULED, RUNNING ou PAUSED
Campanha pertence à empresa do token

Resposta:

{
  "success": true,
  "data": {
    "id": 123,
    "status": "CANCELLED",
    "cancelledAt": "2024-01-16T11:30:00Z",
    "cancelledBy": "[email protected]",
    "sentCount": 750
  }
}

Webhooks de Status

Eventos Disparados

interface StatusChangeEvent {
  event: "campaign.status_changed";
  campaignId: number;
  companyId: number;
  previousStatus: string;
  newStatus: string;
  timestamp: string;
  metadata: {
    sentCount?: number;
    failedCount?: number;
    progress?: number;
  };
}

Configuração

Configure URLs de webhook nas configurações da empresa para receber notificações de mudança de status.

Boas Práticas

Monitoramento

Acompanhe campanhas RUNNING regularmente

Timeouts

Configure timeouts apropriados para PAUSED

Limpeza

Archive campanhas COMPLETED antigas

Logs

Mantenha logs de transições para auditoria

Troubleshooting

Campanha travada em RUNNING

Possíveis causas:

Worker parado ou com erro
Evolution API desconectada
Fila Redis congestionada

Soluções:

Verificar logs do worker
Confirmar conexão Evolution
Pausar e retomar campanha
Reiniciar worker se necessário

Campanha não inicia no horário agendado

Possíveis causas:

Fuso horário incorreto
Worker não está rodando
Campanha foi cancelada

Soluções:

Verificar configuração de timezone
Confirmar worker ativo
Verificar logs de sistema

Status inconsistente

Possíveis causas:

Modificação manual no banco
Erro durante transição
Concorrência de processos

Soluções:

Usar apenas APIs oficiais
Verificar logs de erro
Implementar locks apropriados

Referência Rápida

Status	Cor	Pode Pausar	Pode Cancelar	Pode Retomar	É Final
DRAFT	Cinza	❌	❌	❌	❌
SCHEDULED	Roxo	❌	✅	❌	❌
RUNNING	Verde	✅	✅	❌	❌
PAUSED	Amarelo	❌	✅	✅	❌
COMPLETED	Azul	❌	❌	❌	✅
CANCELLED	Vermelho	❌	❌	❌	✅

Getting started

Development