# AI Conversational Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Implement AI-powered chat replies via Grok with configurable persona (approved by superadmin) and two modes: autonomous (bot replies directly) and suggestion (operator confirms). **Architecture:** New `ChatAiService` handles Grok API calls for conversations. `AiPersona` model stores structured persona per tenant with approval workflow. `ProcessInboundMessageJob` is upgraded from stub to real logic that routes through ChatAiService. Frontend gets chatbot settings page, admin approval page, and activates the AI suggestion placeholder in the Inbox. **Tech Stack:** Laravel 12 (backend), Vue 3 + Tabler UI (frontend), Grok API (xAI) **Spec:** `docs/superpowers/specs/2026-03-22-ai-conversational-design.md` --- ## File Structure ### Backend — Create | File | Responsibility | |------|---------------| | `backend/database/migrations/2026_03_22_200000_create_ai_personas_table.php` | Persona table | | `backend/app/Models/AiPersona.php` | Model with tenant scope | | `backend/app/Services/Ai/ChatAiService.php` | Grok conversational AI | | `backend/app/Http/Controllers/API/V1/ChatbotController.php` | Tenant persona + settings | | `backend/app/Http/Controllers/API/V1/Admin/AiPersonaAdminController.php` | Superadmin approval | ### Backend — Modify | File | Change | |------|--------| | `backend/app/Jobs/ProcessInboundMessageJob.php` | Replace stub with real logic | | `backend/routes/api.php:95-106,107-126` | Add chatbot + admin persona routes | | `backend/database/seeders/GlobalSettingsSeeder.php:32` | Add credits_per_ai_chat | ### Frontend — Create | File | Responsibility | |------|---------------| | `frontend/src/pages/chatbot/Settings.vue` | Tenant persona config + mode toggle | | `frontend/src/pages/admin/AiPersonas.vue` | Superadmin approval page | ### Frontend — Modify | File | Change | |------|--------| | `frontend/src/components/conversations/ConversationChat.vue:52-57` | Activate AI suggestion | | `frontend/src/components/layout/AppSidebar.vue:44-46` | Add Chatbot nav item | | `frontend/src/router/index.ts` | Add chatbot + admin persona routes | --- ## Task 1: Migration + Model — AiPersona **Files:** - Create: `backend/database/migrations/2026_03_22_200000_create_ai_personas_table.php` - Create: `backend/app/Models/AiPersona.php` - [ ] **Step 1: Create migration** ```php id(); $table->unsignedBigInteger('tenant_id'); $table->string('bot_name', 50); $table->enum('tone', ['formal', 'casual', 'friendly'])->default('friendly'); $table->string('company_name', 100); $table->text('products_services'); $table->text('business_rules'); $table->text('special_instructions')->nullable(); $table->string('working_hours', 200)->nullable(); $table->enum('status', ['draft', 'pending_approval', 'approved', 'rejected'])->default('draft'); $table->text('rejection_reason')->nullable(); $table->unsignedBigInteger('approved_by')->nullable(); $table->timestamp('approved_at')->nullable(); $table->timestamps(); $table->unique('tenant_id'); $table->index('status'); $table->foreign('tenant_id')->references('id')->on('tenants')->cascadeOnDelete(); $table->foreign('approved_by')->references('id')->on('users')->nullOnDelete(); }); } public function down(): void { Schema::dropIfExists('ai_personas'); } }; ``` - [ ] **Step 2: Create AiPersona model** ```php 'datetime', ]; public function tenant() { return $this->belongsTo(Tenant::class); } public function approver() { return $this->belongsTo(User::class, 'approved_by'); } } ``` - [ ] **Step 3: Run migration** Run: `cd backend && php artisan migrate` Expected: 1 migration executed - [ ] **Step 4: Verify syntax** Run: `php -l app/Models/AiPersona.php` - [ ] **Step 5: Commit** ```bash git add backend/database/migrations/2026_03_22_200000_create_ai_personas_table.php backend/app/Models/AiPersona.php git commit -m "feat: add AiPersona migration and model" ``` --- ## Task 2: ChatAiService **Files:** - Create: `backend/app/Services/Ai/ChatAiService.php` - Modify: `backend/database/seeders/GlobalSettingsSeeder.php:32` - [ ] **Step 1: Add credits_per_ai_chat to seeder** In `GlobalSettingsSeeder.php`, add after line 32 (after `credits_per_whatsapp`): ```php ['billing', 'credits_per_ai_chat', '2', 'string'], ``` - [ ] **Step 2: Create ChatAiService** ```php where('tenant_id', $tenantId) ->where('status', 'approved') ->first(); if (! $persona) { return ['ok' => false, 'reply' => null, 'error' => 'Persona não configurada ou não aprovada', 'credits_used' => 0]; } // 2. Carregar últimas 10 mensagens $recentMessages = ConversationMessage::withoutGlobalScopes() ->where('conversation_id', $conversation->id) ->orderByDesc('created_at') ->limit(10) ->get() ->reverse() ->values(); if ($recentMessages->isEmpty()) { return ['ok' => false, 'reply' => null, 'error' => 'Nenhuma mensagem na conversa', 'credits_used' => 0]; } // 3. Montar system prompt $systemPrompt = $this->buildSystemPrompt($persona); // 4. Formatar mensagens como chat history $messages = [['role' => 'system', 'content' => $systemPrompt]]; foreach ($recentMessages as $msg) { $role = $msg->direction === 'inbound' ? 'user' : 'assistant'; if ($msg->content) { $messages[] = ['role' => $role, 'content' => $msg->content]; } } // 5. Chamar Grok API $apiKey = $this->settings->getGlobal('ai', 'grok_api_key', ''); $model = $this->settings->getGlobal('ai', 'grok_model', 'grok-beta'); if (empty($apiKey)) { return ['ok' => false, 'reply' => null, 'error' => 'API key de IA não configurada', 'credits_used' => 0]; } $response = Http::withHeaders([ 'Authorization' => "Bearer {$apiKey}", 'Content-Type' => 'application/json', ]) ->timeout(30) ->post('https://api.x.ai/v1/chat/completions', [ 'model' => $model, 'messages' => $messages, 'temperature' => 0.7, 'max_tokens' => 300, ]); if (! $response->successful()) { $error = $response->json('error.message', $response->body()); Log::channel('ai')->warning('chat.api_failed', ['tenant' => $tenantId, 'error' => $error]); return ['ok' => false, 'reply' => null, 'error' => $error, 'credits_used' => 0]; } $reply = $response->json('choices.0.message.content', ''); $tokensIn = $response->json('usage.prompt_tokens', 0); $tokensOut = $response->json('usage.completion_tokens', 0); // 6. Debitar créditos $creditsAmount = (int) $this->settings->getGlobal('billing', 'credits_per_ai_chat', '2'); $this->credits->debit( $tenantId, $creditsAmount, 'ai_chat', $conversation->id, "Chat IA — conversa #{$conversation->id}" ); Log::channel('ai')->info('chat.reply_generated', [ 'tenant' => $tenantId, 'conversation' => $conversation->id, 'tokens_in' => $tokensIn, 'tokens_out' => $tokensOut, 'credits' => $creditsAmount, 'reply_length' => strlen($reply), ]); return ['ok' => true, 'reply' => $reply, 'error' => null, 'credits_used' => $creditsAmount]; } catch (\Throwable $e) { Log::channel('ai')->error('chat.exception', [ 'tenant' => $tenantId, 'conversation' => $conversation->id, 'error' => $e->getMessage(), ]); return ['ok' => false, 'reply' => null, 'error' => $e->getMessage(), 'credits_used' => 0]; } } private function buildSystemPrompt(AiPersona $persona): string { $toneMap = ['formal' => 'Formal e profissional', 'casual' => 'Casual e descontraído', 'friendly' => 'Amigável e acolhedor']; $tone = $toneMap[$persona->tone] ?? $persona->tone; $prompt = "Você é {$persona->bot_name}, assistente virtual da empresa {$persona->company_name}.\n\n"; $prompt .= "Tom: {$tone}\n"; $prompt .= "Produtos/Serviços: {$persona->products_services}\n"; if ($persona->working_hours) { $prompt .= "Horário de funcionamento: {$persona->working_hours}\n"; } $prompt .= "\nRegras de negócio:\n{$persona->business_rules}\n"; if ($persona->special_instructions) { $prompt .= "\nInstruções especiais:\n{$persona->special_instructions}\n"; } $prompt .= "\nIMPORTANTE: Responda de forma concisa (máximo 500 caracteres). Não invente informações que não estão nas regras acima. Se não souber responder, diga que vai encaminhar para um atendente humano."; return $prompt; } } ``` - [ ] **Step 3: Verify syntax + run seeder** Run: `php -l app/Services/Ai/ChatAiService.php && php artisan db:seed --class=GlobalSettingsSeeder` - [ ] **Step 4: Commit** ```bash git add backend/app/Services/Ai/ChatAiService.php backend/database/seeders/GlobalSettingsSeeder.php git commit -m "feat: add ChatAiService for conversational AI via Grok" ``` --- ## Task 3: ProcessInboundMessageJob — replace stub **Files:** - Modify: `backend/app/Jobs/ProcessInboundMessageJob.php` - [ ] **Step 1: Replace entire file** ```php findOrFail($this->conversationId); // Só processa se conversa está em modo bot if ($conversation->status !== 'bot') { Log::channel('whatsapp')->debug('inbound.skip_not_bot', [ 'conversation' => $this->conversationId, 'status' => $conversation->status, ]); return; } // Verificar se chatbot está habilitado $enabled = $settings->get($this->tenantId, 'chatbot', 'enabled', false); if (! $enabled) { Log::channel('whatsapp')->debug('inbound.skip_disabled', ['tenant' => $this->tenantId]); return; } // Verificar se tem persona aprovada $persona = AiPersona::withoutGlobalScopes() ->where('tenant_id', $this->tenantId) ->where('status', 'approved') ->first(); if (! $persona) { Log::channel('whatsapp')->debug('inbound.skip_no_persona', ['tenant' => $this->tenantId]); return; } // Gerar resposta da IA $result = $ai->generateReply($conversation, $this->tenantId); if (! $result['ok']) { Log::channel('ai')->warning('chat.reply_failed', [ 'conversation' => $this->conversationId, 'error' => $result['error'], ]); return; } $mode = $settings->get($this->tenantId, 'chatbot', 'mode', 'suggestion'); if ($mode === 'autonomous') { // Enviar resposta diretamente via WhatsApp $sendResult = $whatsapp->sendText($conversation->phone, $result['reply'], $this->tenantId); if ($sendResult['ok']) { ConversationMessage::forceCreate([ 'conversation_id' => $conversation->id, 'tenant_id' => $this->tenantId, 'direction' => 'outbound', 'sender_type' => 'ai', 'type' => 'text', 'content' => $result['reply'], 'external_message_id' => $sendResult['message_id'], 'status' => 'sent', 'created_at' => now(), 'sent_at' => now(), ]); $conversation->update(['last_message_at' => now()]); Log::channel('whatsapp')->info('inbound.ai_replied', [ 'conversation' => $this->conversationId, 'mode' => 'autonomous', ]); } else { Log::channel('whatsapp')->warning('inbound.ai_send_failed', [ 'conversation' => $this->conversationId, 'error' => $sendResult['error'], ]); } } else { // Modo sugestão — salvar na metadata da conversa $metadata = $conversation->metadata ?? []; $metadata['ai_suggestion'] = $result['reply']; $conversation->update(['metadata' => $metadata]); Log::channel('whatsapp')->info('inbound.ai_suggestion_saved', [ 'conversation' => $this->conversationId, 'mode' => 'suggestion', ]); } } public function failed(\Throwable $e): void { Log::channel('whatsapp')->error('inbound.job_failed', [ 'conversation' => $this->conversationId, 'error' => $e->getMessage(), ]); } } ``` - [ ] **Step 2: Verify syntax** Run: `php -l app/Jobs/ProcessInboundMessageJob.php` - [ ] **Step 3: Commit** ```bash git add backend/app/Jobs/ProcessInboundMessageJob.php git commit -m "feat: implement ProcessInboundMessageJob with AI autonomous/suggestion modes" ``` --- ## Task 4: ChatbotController + AiPersonaAdminController + Routes **Files:** - Create: `backend/app/Http/Controllers/API/V1/ChatbotController.php` - Create: `backend/app/Http/Controllers/API/V1/Admin/AiPersonaAdminController.php` - Modify: `backend/routes/api.php` - [ ] **Step 1: Create ChatbotController** ```php validate([ 'bot_name' => ['required', 'string', 'max:50'], 'tone' => ['required', 'in:formal,casual,friendly'], 'company_name' => ['required', 'string', 'max:100'], 'products_services' => ['required', 'string', 'max:2000'], 'business_rules' => ['required', 'string', 'max:2000'], 'special_instructions' => ['nullable', 'string', 'max:1000'], 'working_hours' => ['nullable', 'string', 'max:200'], ]); $data['status'] = 'pending_approval'; $data['rejection_reason'] = null; $data['approved_by'] = null; $data['approved_at'] = null; $persona = AiPersona::updateOrCreate( ['tenant_id' => auth()->user()->tenant_id], $data ); return ApiResponse::success($persona, 'Persona salva e enviada para aprovação'); } public function settings() { $tenantId = auth()->user()->tenant_id; $hasApproved = AiPersona::where('status', 'approved')->exists(); return ApiResponse::success([ 'mode' => $this->settings->get($tenantId, 'chatbot', 'mode', 'suggestion'), 'enabled' => (bool) $this->settings->get($tenantId, 'chatbot', 'enabled', false), 'has_approved_persona' => $hasApproved, ]); } public function updateSettings(Request $request) { $tenantId = auth()->user()->tenant_id; $data = $request->validate([ 'mode' => ['nullable', 'in:autonomous,suggestion'], 'enabled' => ['nullable', 'boolean'], ]); if ($data['enabled'] ?? false) { $hasApproved = AiPersona::where('status', 'approved')->exists(); if (! $hasApproved) { return ApiResponse::error('Persona precisa ser aprovada antes de ativar o chatbot.', [], 422); } } if (array_key_exists('mode', $data) && $data['mode'] !== null) { $this->settings->upsert($tenantId, 'chatbot', 'mode', $data['mode'], 'string'); } if (array_key_exists('enabled', $data)) { $this->settings->upsert($tenantId, 'chatbot', 'enabled', $data['enabled'] ? '1' : '0', 'boolean'); } return ApiResponse::success([], 'Configurações atualizadas'); } } ``` - [ ] **Step 2: Create AiPersonaAdminController** ```php validate([ 'status' => ['nullable', 'in:draft,pending_approval,approved,rejected'], ]); $q = AiPersona::withoutGlobalScopes()->with('tenant:id,name'); if (!empty($validated['status'])) { $q->where('status', $validated['status']); } $items = $q->orderByRaw("FIELD(status, 'pending_approval', 'draft', 'approved', 'rejected')") ->orderByDesc('updated_at') ->paginate(20); return ApiResponse::paginated($items, 'OK'); } public function show(int $id) { $persona = AiPersona::withoutGlobalScopes()->with('tenant:id,name')->findOrFail($id); return ApiResponse::success($persona); } public function approve(int $id) { $persona = AiPersona::withoutGlobalScopes()->findOrFail($id); $persona->update([ 'status' => 'approved', 'approved_by' => auth()->id(), 'approved_at' => now(), 'rejection_reason' => null, ]); return ApiResponse::success($persona->fresh(), 'Persona aprovada'); } public function reject(int $id, Request $request) { $data = $request->validate([ 'reason' => ['required', 'string', 'max:500'], ]); $persona = AiPersona::withoutGlobalScopes()->findOrFail($id); $persona->update([ 'status' => 'rejected', 'rejection_reason' => $data['reason'], 'approved_by' => null, 'approved_at' => null, ]); return ApiResponse::success($persona->fresh(), 'Persona rejeitada'); } } ``` - [ ] **Step 3: Register routes in api.php** Read `routes/api.php` first. Add import at top: ```php use App\Http\Controllers\API\V1\ChatbotController; use App\Http\Controllers\API\V1\Admin\AiPersonaAdminController; ``` Add chatbot routes inside `auth:sanctum` group (after conversations block, around line 105): ```php // Chatbot Route::get('chatbot/persona', [ChatbotController::class, 'persona']); Route::put('chatbot/persona', [ChatbotController::class, 'updatePersona']); Route::get('chatbot/settings', [ChatbotController::class, 'settings']); Route::put('chatbot/settings', [ChatbotController::class, 'updateSettings']); ``` Add admin routes inside `superadmin` group (after WhatsApp settings, around line 125): ```php // AI Personas Route::get('ai-personas', [AiPersonaAdminController::class, 'index']); Route::get('ai-personas/{id}', [AiPersonaAdminController::class, 'show']); Route::patch('ai-personas/{id}/approve',[AiPersonaAdminController::class, 'approve']); Route::patch('ai-personas/{id}/reject', [AiPersonaAdminController::class, 'reject']); ``` - [ ] **Step 4: Verify** Run: `php -l app/Http/Controllers/API/V1/ChatbotController.php && php -l app/Http/Controllers/API/V1/Admin/AiPersonaAdminController.php && php artisan route:list --path=v1/chatbot 2>&1 && php artisan route:list --path=v1/admin/ai-personas 2>&1` - [ ] **Step 5: Commit** ```bash git add backend/app/Http/Controllers/API/V1/ChatbotController.php backend/app/Http/Controllers/API/V1/Admin/AiPersonaAdminController.php backend/routes/api.php git commit -m "feat: add ChatbotController and AiPersonaAdminController with routes" ``` --- ## Task 5: Frontend — Chatbot Settings page **Files:** - Create: `frontend/src/pages/chatbot/Settings.vue` - Modify: `frontend/src/router/index.ts` - Modify: `frontend/src/components/layout/AppSidebar.vue` - [ ] **Step 1: Create Settings.vue** ```vue ``` - [ ] **Step 2: Add route in router/index.ts** Read the file. Add before the catch-all route: ```ts { path: '/chatbot/settings', component: () => import('@/pages/chatbot/Settings.vue'), meta: { title: 'Chatbot' }, }, ``` - [ ] **Step 3: Add Chatbot nav item in AppSidebar.vue** Read the file. After the Conversas nav item (around line 44), add: ```html
  • Chatbot
    • ``` - [ ] **Step 4: Build** Run: `cd frontend && npm run build 2>&1 | tail -5` - [ ] **Step 5: Commit** ```bash git add frontend/src/pages/chatbot/Settings.vue frontend/src/router/index.ts frontend/src/components/layout/AppSidebar.vue git commit -m "feat: add Chatbot settings page with persona form and mode toggle" ``` --- ## Task 6: Frontend — Admin AiPersonas approval page **Files:** - Create: `frontend/src/pages/admin/AiPersonas.vue` - Modify: `frontend/src/router/index.ts` - Modify: `frontend/src/components/layout/AppSidebar.vue` - [ ] **Step 1: Create AiPersonas.vue** ```vue ``` - [ ] **Step 2: Add route** In `router/index.ts`, add before catch-all: ```ts { path: '/admin/ai-personas', component: () => import('@/pages/admin/AiPersonas.vue'), meta: { superadmin: true, title: 'Admin • Personas IA' }, }, ``` - [ ] **Step 3: Add admin nav item** In AppSidebar.vue, inside the admin dropdown (after WhatsApp item), add: ```html Personas IA ``` - [ ] **Step 4: Build** Run: `cd frontend && npm run build 2>&1 | tail -5` - [ ] **Step 5: Commit** ```bash git add frontend/src/pages/admin/AiPersonas.vue frontend/src/router/index.ts frontend/src/components/layout/AppSidebar.vue git commit -m "feat: add admin AI Personas approval page" ``` --- ## Task 7: Frontend — Activate AI suggestion in ConversationChat **Files:** - Modify: `frontend/src/components/conversations/ConversationChat.vue:52-57` - [ ] **Step 1: Replace static placeholder with dynamic suggestion** Read `ConversationChat.vue`. Find the AI suggestion placeholder block (lines 52-57): ```html
    💡 Sugestão IA indisponível neste plano
    ``` Replace with: ```html
    💡 {{ aiSuggestion }}
    💡 Sugestão IA indisponível
    ``` In the `