# 2026-04-13 - Z-API OpenAI Chatbot Cockpit

## Objetivo

Elevar a integracao Z-API para um nivel operacional mais completo, fechando o fluxo de webhook inbound, inbox local, auto-reply com OpenAI e controle administrativo do bot por contrato.

## Backend

- criado o endpoint operacional de webhook da Z-API para recebimento, normalizacao, idempotencia e persistencia local
- ampliado o parser do webhook para lidar melhor com variacoes de payload, telefone, nome do remetente, status e identificacao de grupos
- criado o fluxo de auto-reply simples via OpenAI, com envio de resposta de volta pela Z-API
- adicionada a regra de pausa de automacao por contrato
- mantido o modulo `src/Modules/ZApiChat/` como camada de inbox e persistencia local

## Integracao e chat

- criado adapter oficial da Z-API para o chat administrativo, usando `instance`, `token` e `client-token` por contrato com fallback global
- ajustado o `chat-zapi` para usar o adapter oficial no envio
- melhorada a persistencia de threads para preencher `subject` quando o contato passa a ser identificado
- refinada a tela do chat com contexto de contrato e acao de atualizar conversas

## Hub e governanca

- expandido o hub Z-API com leitura de eventos recentes do bot
- adicionada leitura dos logs recentes da OpenAI para `zapi_auto_reply`
- adicionados indicadores de replies do bot e contratos pausados
- criado controle administrativo para pausar e retomar o bot por contrato no hub
- centralizada a lista de contratos pausados em `tiix_zapi_config`

## Logs

- `zapi_logs` passa a registrar recepcao do webhook e decisoes do auto-reply
- `openai_logs` registra prompts e respostas do fluxo `zapi_auto_reply`
- o hub agora consolida essas duas trilhas para leitura operacional

## Arquivos impactados

- `src/Integrations/ZApi/Http/ZApiWebhookController.php`
- `src/Integrations/ZApi/Services/ZApiWebhookService.php`
- `src/Integrations/ZApi/Services/ZApiAutoReplyService.php`
- `src/Integrations/ZApi/ZApiConfig.php`
- `src/Integrations/ZApi/ZApiAdminRepository.php`
- `src/Modules/ZApiChat/ZApiOfficialAdapter.php`
- `src/Modules/ZApiChat/ZApiChatService.php`
- `src/Modules/ZApiChat/ZApiChatRepository.php`
- `pages/admin/chat-zapi.php`
- `pages/admin/zapi-hub.php`
- `scripts/chat.js`

## Validacao

- `php -l src/Integrations/ZApi/Services/ZApiWebhookService.php`
- `php -l src/Integrations/ZApi/Services/ZApiAutoReplyService.php`
- `php -l src/Integrations/ZApi/ZApiConfig.php`
- `php -l src/Integrations/ZApi/ZApiAdminRepository.php`
- `php -l src/Modules/ZApiChat/ZApiOfficialAdapter.php`
- `php -l src/Modules/ZApiChat/ZApiChatService.php`
- `php -l src/Modules/ZApiChat/ZApiChatRepository.php`
- `php -l pages/admin/chat-zapi.php`
- `php -l pages/admin/zapi-hub.php`

## Proximo passo sugerido

- validar o fluxo com payload real da Z-API em ambiente controlado
- revisar logs `webhook.auto_reply` e `zapi_auto_reply`
- decidir se o adapter legado antigo sera descontinuado apos estabilizacao