> ## Documentation Index > Fetch the complete documentation index at: https://docs.orquena.com/llms.txt > Use this file to discover all available pages before exploring further. # Orquena Inbox > Central de conversas conectada ao WhatsApp, com atendimento humano, realtime, sincronização inicial e controle da IA. # 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 ```text theme={null} WhatsApp ↓ WAHA ↓ webhook autenticado e normalizado Orquena Inbox ↓ PostgreSQL ↓ Realtime para o dashboard ``` 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 ```text theme={null} ┌──────────────────────┬──────────────────────────────────┐ │ Conversas │ João da Silva │ │ │ │ │ 🔍 Pesquisar │ João: Tem horário hoje? │ │ │ │ │ João da Silva │ Barbearia: ... │ │ Maria Oliveira │ │ │ Carlos Santos │ Sugestões da IA, quando ativas │ │ │ │ │ │ [ Digite sua mensagem... ] [➤] │ └──────────────────────┴──────────────────────────────────┘ ``` ## 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 ```text theme={null} PREPARING QR_REQUIRED CONNECTING CONNECTED SYNCING RECONNECTING DISCONNECTED ACTION_REQUIRED ERROR ``` 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: ```text theme={null} Modo configurado: Automática Estado atual: Atendimento humano ativo ``` 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: ```text theme={null} ⚠️ Atendimento humano necessário Cliente: Carlos Silva Motivo: solicitação fora das regras configuradas Resumo: Carlos deseja saber se a empresa atende em domicílio. Esse serviço não está cadastrado e a IA não pode confirmar. [ Assumir conversa ] ``` 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 ```text theme={null} [ Assumir conversa ] [ Devolver para IA ] [ Pausar automação ] [ Resolver handoff ] ``` 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: ```text theme={null} inbox.read inbox.message.send inbox.assign conversation.take-over conversation.return-to-ai conversation.ai-mode.manage handoff.resolve ``` 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 ```text theme={null} docs/prds/onboarding-inbox-ai-v1.md docs/architecture/conversation-ai-control-v1.md plugins/first-party/inbox/README.md ```