ClientPilot AI

Telegram AI Copilot for Business Client Conversations

ClientPilot AI is a Laravel-based Telegram bot for human-in-the-loop client conversation management. It helps review incoming business messages, generate AI-assisted replies, keep conversation memory, and surface safety risks while the user still manually decides what to send.

What It Does

• Receives client/job messages through Telegram
• Creates per-client conversation records
• Generates native-language client analysis for the user
• Suggests ready-to-send replies in the selected client reply language
• Stores the reply the user actually sent
• Supports feedback, custom reply logging, regenerate, memory summary, and risk-aware guidance

ClientPilot AI does not send messages automatically to external marketplaces or communication platforms.

Human-in-the-Loop Workflow

The workflow is intentionally manual:

1. AI analyzes and suggests
2. The user reviews inside Telegram
3. The user manually sends the final reply on the target platform
4. The bot stores the selected or custom reply for continuity

Telegram Bot Flow

Current implemented flow:

1. /start
2. + New Client
3. Select target reply language
4. Paste the client/job message
5. Receive native-language Client Analysis
6. Start chat for that client
7. Paste each new client message
8. Receive ready-to-send reply suggestions
9. Use available actions:
   • Select sent option
   • Feedback
   • Custom reply
   • Regenerate
   • Pause / resume / close client
   • View summary

Language Behavior

ClientPilot AI separates internal user-facing language from client-facing reply language.

• NATIVE_LANGUAGE is global
• Static Telegram bot UI/messages use NATIVE_LANGUAGE
• Client Analysis is NATIVE_LANGUAGE only
• reply option target_text uses client.target_language
• native_meaning uses NATIVE_LANGUAGE

Supported target reply languages:

• English
• Turkish
• Spanish
• Portuguese

Existing clients without a stored target_language fall back to the global TARGET_LANGUAGE config.

Verified Profile Context

config/upwork_profile.php is used as Mehrdad's verified profile context for reply suggestion grounding.

This context is used to help the AI:

• ground replies in verified skills, services, and projects
• use direct claims only when supported
• use adjacent wording when the job is related but not an exact profile match
• avoid inventing projects, links, clients, or exact experience

The profile config is treated as verified context only. It is not a public portfolio page and should not contain secrets.

Risk Guard

Risk Guard reviews risky client situations during reply suggestion generation.

It currently focuses on cases such as:

• off-platform communication requests
• off-platform payment requests
• starting before funded milestone / clear agreement
• unpaid sample requests
• suspicious files
• sensitive credential requests
• unrealistic deadlines
• oversized scope with weak budget signals

Important behavior:

• technical mentions like WhatsApp Business API or Meta Cloud API should not be treated as off-platform communication by themselves
• actual off-platform communication/payment requests should still be treated carefully
• Risk Guard warns and steers replies to a safer path; it does not block the user from continuing

Main Stack

• Laravel
• PHP
• MySQL
• Telegram Bot API
• OpenAI-compatible AI provider
• Queues / Jobs
• PHPUnit tests

Configuration Notes

Relevant configuration values include:

NATIVE_LANGUAGE=fa
TARGET_LANGUAGE=en
TARGET_PLATFORM_NAME=Upwork

• NATIVE_LANGUAGE: global language for bot-facing explanations shown to the user
• TARGET_LANGUAGE: global fallback reply language
• TARGET_PLATFORM_NAME: configurable marketplace/platform display name

The platform name is configurable so the same structure can later be used for Upwork, Freelancer, Fiverr, LinkedIn, or similar client conversation workflows.

Deployment Basics

Typical production maintenance commands:

php artisan migrate --force
php artisan optimize:clear
php artisan queue:restart

If you run queue workers under Supervisor, restart the worker process after deployment.

Testing

Run the test suite with:

php artisan test

Safety Notes

• Do not commit .env
• Do not commit real Telegram tokens, AI keys, webhook secrets, passwords, or private credentials
• Keep reply automation disabled unless you intentionally build that in a future scope
• AI request logging should stay masked for sensitive payload content

Current Scope Summary

The current implementation includes:

• Telegram webhook + allowed user flow
• Client creation and management
• Per-client target reply language selection
• Native-only Client Analysis
• Reply suggestion generation with target-language replies
• Selected reply saving
• Feedback flow
• Custom reply flow
• Regenerate flow
• Memory summary
• Risk Guard
• Verified profile grounding from config
• Inline callback actions for dynamic Telegram buttons

License

License not specified yet.