Documentação Técnica — Status de Conexões

1. Visão Geral

O sistema utiliza um conjunto padronizado de status para representar o ciclo de vida das mensagens, independentemente do tipo de conexão utilizada.

Embora os status sejam os mesmos para todas as integrações, a forma como cada status é alcançado pode variar de acordo com a existência ou não de um webhook de confirmação de entrega.

Atualmente, existem dois grupos de conexões:

• Conexões com webhook de confirmação

• Conexões sem webhook de confirmação

Essa diferença é especialmente importante para determinar quando uma mensagem pode ser considerada efetivamente como sent.

2. Status Disponíveis

Status

Descrição

3. Conexões com Webhook de Confirmação

São conexões que possuem um webhook responsável por informar o resultado da entrega da mensagem.

Atualmente:

• Crazy API

• WhatsApp Cloud

• Z-API

Regra

Nessas conexões, o retorno da requisição inicial de envio não é suficiente para considerar a mensagem como efetivamente entregue.

O status sent é confirmado através do webhook de confirmação.

Fluxo conceitual:

pending
   ↓
envio da mensagem
   ↓
confirmação via webhook
   ↓
sent
   ↓
received
   ↓
visualizado

3.1 Conexões sem Webhook de Confirmação

São conexões que não possuem um webhook externo utilizado para confirmar a entrega da mensagem.

Atualmente:

• UAZAPI

• Evolution API

• Conexão Universal
  

Regra

Nessas conexões, o sistema utiliza o retorno HTTP da requisição de envio.

Quando o POST responsável pelo envio retorna HTTP 200, a mensagem é considerada enviada e o status é atualizado diretamente para:

sent

Portanto, não é necessário aguardar uma confirmação externa para essa transição.

4. Regras de Transição de Status

Imutabilidade do sent

Uma vez que uma mensagem tenha atingido o status:

sent

ela não pode retornar para:

pending

Essa regra é válida para todas as conexões.

Exemplo

pending → sent

É permitido.

sent → pending

Não é permitido.

Essa regra impede que uma mensagem já considerada enviada seja posteriormente tratada como se ainda estivesse aguardando envio.

4.1 O status error é final

O status:

error

representa um estado terminal.

Depois que uma mensagem entra em error, nenhuma outra transição de status deve ocorrer.

Permitido

sent → error

ou:

scheduled → error

Não permitido

error → pending
error → sent
error → received
error → visualizado

Portanto:

error → [FIM]

5. Regras para o Status error

O status error pode ser atingido em dois cenários.

Erro após sent

No fluxo normal, após a mensagem atingir sent, o sistema pode aguardar uma confirmação posterior.

Caso ocorra uma falha nessa etapa, o status será alterado para:

error

A mensagem não continua para received ou visualizado.

Fluxo:

pending
   ↓
sent
   ↓
error

A partir de error, o processo é encerrado.

5.1 Erro em mensagem agendada

Mensagens com status scheduled possuem uma regra adicional.

Quando chega o horário programado, o sistema tenta realizar o envio.

Existem dois resultados possíveis:

Sucesso

scheduled → pending

A mensagem entra no fluxo normal de envio.

Falha

scheduled → error

Nesse caso, a mensagem não passa por pending.

Portanto:

                 ┌──→ pending → sent → received → visualizado
scheduled ────────┤
                 └──→ error

6. Status received e visualizado

Os status received e visualizado representam confirmações posteriores ao envio.

Eles são alcançados através de eventos de confirmação, normalmente provenientes do webhook da integração.

Regra importante

Uma mensagem que já esteja em:

received

ou:

visualizado

não deve ser alterada para error.

Isso ocorre porque esses status representam uma confirmação passiva recebida pelo sistema.

O erro deve ser tratado nas etapas anteriores do processo, e não após uma confirmação de recebimento ou visualização.

Fluxo válido

sent → received → visualizado

Fluxos inválidos

received → error

visualizado → error

7. Hierarquia de Status — Mensagens Normais

Para mensagens que não foram agendadas, o fluxo padrão é:

pending → sent → received → visualizado

Cada etapa representa uma evolução do estado da mensagem.

Fluxo com erro

pending → sent → error

O status error encerra o ciclo.

8. Hierarquia de Status — Mensagens Agendadas

Mensagens agendadas possuem o status inicial:

scheduled

Quando chega o horário definido para o envio, o sistema tenta iniciar o processo.

Fluxo de sucesso

scheduled
    ↓
pending
    ↓
sent
    ↓
received
    ↓
visualizado

Fluxo de erro

scheduled
    ↓
error

Portanto, existem duas ramificações possíveis a partir de scheduled.

9. Matriz de Transições

Status Atual

Próximo Status

Condição

Observação: a confirmação de sent varia conforme a conexão utilizada.

10. Comportamento por Integração

Integração

Possui webhook de confirmação?

Como sent é confirmado?

11. Fluxos Completos

Mensagem normal — sucesso

pending
   ↓
sent
   ↓
received
   ↓
visualizado
   ↓
FIM

Mensagem normal — erro

pending
   ↓
sent
   ↓
error
   ↓
FIM

Mensagem agendada — sucesso

scheduled
   ↓
pending
   ↓
sent
   ↓
received
   ↓
visualizado
   ↓
FIM

Mensagem agendada — erro

scheduled
   ↓
error
   ↓
FIM

12. Regra Principal do Ciclo de Vida

De forma simplificada, o ciclo de vida das mensagens pode ser representado da seguinte maneira:

                         ┌───────────────┐
                         │scheduled/envio│
                         └───────┬───────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
                 sucesso                    falha
                    │                         │
                    ▼                         ▼
               ┌─────────┐              ┌─────────┐
               │ pending │              │  error  │
               └────┬────┘              └────┬────┘
                    │                        │
                    ▼                        ▼
               ┌─────────┐                   FIM
               │  sent   │
               └────┬────┘
                    │
             ┌──────┴──────┐
             │             │
          sucesso         erro
             │             │
             ▼             ▼
        ┌──────────┐   ┌─────────┐
        │ received │   │  error  │
        └────┬─────┘   └────┬────┘
             │              │
             ▼              ▼
       ┌────────────┐       FIM
       │ visualizado│
       └─────┬──────┘
             │
             ▼
            FIM

Regra fundamental: os status representam uma evolução do ciclo de vida da mensagem. O sistema não deve permitir regressões ou alterações incompatíveis com as transições definidas nesta documentação.