Skip to main content

​
Orquena Inbox

A Orquena Inbox é a central de atendimento do negócio. Ela pode utilizar uma disposição visual familiar para quem já usa mensageiros na web, mas não é apresentada como WhatsApp Web. O WhatsApp é um canal conectado; a Inbox é um domínio próprio da Orquena.

​
Objetivo

Permitir que uma equipe:
  • Veja conversas e contatos do WhatsApp conectado.
  • Receba novas mensagens em tempo real.
  • Responda por texto dentro da Orquena.
  • Acompanhe mensagens não lidas e estados de entrega.
  • Assuma conversas que estavam com a IA.
  • Utilize sugestões quando o modo Assistente estiver ativo.
  • Continue na mesma conversa quando houver handoff.

​
Fonte da verdade

O frontend não usa o WAHA como banco de mensagens. Mensagens recebidas são persistidas na Orquena antes de qualquer processamento por IA, automação ou notificação.

​
Estrutura da tela

​
Lista de conversas

Cada item pode mostrar:
  • Nome ou telefone do contato.
  • Foto quando disponível e autorizada.
  • Prévia da última mensagem.
  • Horário da última atividade.
  • Quantidade não lida.
  • Atendente responsável.
  • Modo efetivo da IA.
  • Estado operacional: IA, humano necessário, humano ativo ou pausado.
  • Indicador de erro de envio ou canal desconectado.
Filtros iniciais:
  • Todas.
  • Não lidas.
  • Aguardando humano.
  • Em atendimento humano.
  • Com IA automática.
  • Atribuídas a mim.

​
Timeline da conversa

A timeline apresenta:
  • Mensagens recebidas e enviadas.
  • Autor humano ou IA.
  • Horário.
  • Estado de entrega quando disponível.
  • Eventos de sistema relevantes, como takeover e retorno para IA.
  • Resumo de handoff quando existir.
Eventos internos não devem ser enviados ao cliente.

​
Campo de mensagem

O composer permite inicialmente:
  • Digitar texto.
  • Inserir uma sugestão da IA.
  • Editar a sugestão.
  • Enviar manualmente.
O envio humano continua disponível mesmo quando o modo configurado é Automático. Enviar durante uma solicitação de humano faz a conversa passar para atendimento humano ativo.

​
Sincronização inicial

Depois do QR Code, a Orquena busca somente o necessário para criar continuidade operacional:
  • Contatos acessíveis pelo provider.
  • Identificadores de chats.
  • Metadados básicos.
  • Um histórico recente limitado.
A importação completa de anos de mensagens não faz parte da promessa inicial. Toda mensagem nova depois da conexão passa a ser registrada na Orquena.

​
Persistência da conexão

O usuário escaneia o QR Code uma vez e a sessão deve permanecer autenticada enquanto for válida. A tela solicita nova ação quando:
  • A pessoa desconecta pela Orquena.
  • O aparelho vinculado é removido no WhatsApp.
  • A sessão é invalidada.
  • Uma falha não pode ser recuperada automaticamente.

​
Estados do canal

O estado do canal não é o estado da organização. Uma organização já ativada continua acessível mesmo com o WhatsApp desconectado. O histórico persistido continua disponível, e o dashboard mostra a necessidade de reconexão.

​
Contatos

Os contatos são locais ao tenant. O mesmo número pode existir em organizações diferentes sem compartilhar:
  • Conversas.
  • Notas.
  • Agendamentos.
  • Tags.
  • Preferências de IA.
O identificador externo do WhatsApp é apenas uma chave de canal. O domínio Contacts mantém a identidade canônica dentro da organização.

​
Atendimento humano e IA

A Inbox mostra separadamente:
  • Modo configurado: Desligada, Assistente ou Automática.
  • Estado operacional: IA ativa, humano necessário, humano ativo ou pausado.
Exemplo:
Nesse caso, a IA não envia respostas automáticas.

​
Handoff dentro da mesma conversa

Quando a IA não pode continuar, a Inbox recebe:
  • Notificação.
  • Motivo.
  • Resumo do atendimento.
  • Informações já coletadas.
  • Ações tentadas.
  • Sugestão de próximo passo quando segura.
Exemplo:
O botão abre a conversa original. Não é criado um chat paralelo.

​
Mensagem de espera

Uma mensagem aprovada pela organização pode ser enviada uma vez quando o handoff é criado:
Chamei um atendente para continuar seu atendimento por aqui. Assim que possível, ele responderá nesta mesma conversa.
Ela não deve ser repetida após cada nova mensagem do cliente.

​
Controles humanos

Ao enviar a primeira resposta humana depois de um handoff, a conversa muda para HUMAN_ACTIVE.

​
Retorno para IA

O atendente pode devolver a conversa manualmente. Também pode existir retorno automático depois de 24 horas de inatividade, desde que:
  • Não existam mensagens novas do cliente ou atendente durante a janela.
  • O handoff esteja resolvido.
  • A conversa não esteja pausada manualmente.
O comportamento retomado depende do modo efetivo:
  • Desligada: continua sem IA.
  • Assistente: volta a gerar sugestões.
  • Automática: volta a responder automaticamente.

​
Realtime e confiabilidade

  • A tela recebe eventos em tempo real, mas o banco permanece authoritative.
  • Recarregar a página reconstrói o estado persistido.
  • Webhooks duplicados não criam mensagens repetidas.
  • Falhas do provider não apagam o histórico.
  • Mensagens enviadas usam idempotência.
  • Estados de entrega fora de ordem são reconciliados.

​
Permissões iniciais

Exemplos:
Um membro só acessa conversas da organização e das Inboxes para as quais possui permissão.

​
Escopo inicial

Obrigatório no primeiro caminho completo:
  • Texto.
  • Conversas recentes.
  • Mensagens novas.
  • Contatos.
  • Leitura e envio.
  • Não lidas.
  • Estado do canal.
  • Controle humano e IA.
  • Handoff.
Incremental ou futuro:
  • Mídias avançadas.
  • Grupos.
  • Chamadas.
  • Status.
  • Reprodução completa de todos os recursos do aplicativo WhatsApp.

​
Fonte canônica