راهنمای هوش مصنوعی و پرامپت‌ها

https://docs.poshtyar.com/llms.txt

شما یک مهندس ارشد نرم‌افزار هستید که وظیفه دارید کدهای اتصال به وب‌سرویس پلتفرم تلفنی هوش مصنوعی «پشتیار» (Poshtyar) را در پروژه من پیاده‌سازی کنید.

مشخصات فنی و استانداردهای وب‌سرویس پشتیار به شرح زیر است:

۱. برقراری تماس خروجی (Outbound Call API):
- Endpoint: POST https://api.poshtyar.com/api/v1/external/calls/originate
- Header الزامی: X-API-KEY: poshtyar_live_YOUR_API_KEY
- Header محتوا: Content-Type: application/json
- ساختار بدنه درخواست (JSON Body):
  {
    "phone_number": "09123456789", // شماره همراه مقصد ۱۰ یا ۱۱ رقمی (الزامی)
    "operator_id": "OP_ID_HERE", // شناسه اپراتور ساخته شده در پنل (الزامی)
    "recipient_name": "نام مخاطب", // اختیاری جهت خوش‌آمدگویی شخصی‌سازی‌شده
    "topic": "موضوع یا هدف تماس", // اختیاری (مثلاً تایید سفارش یا یادآوری نوبت)
    "description": "سناریو و جزئیات دقیق برای هدایت مکالمه هوش مصنوعی", // اختیاری
    "opener_text": "جمله آغازین اپراتور بلافاصله پس از برداشتن گوشی", // اختیاری
    "retry_policy": [300, 1800, 7200], // فواصل ثانیه‌ای تلاش مجدد در صورت عدم پاسخ (اختیاری)
    "outbound_type": "ai" // نوع تماس: "ai" برای مکالمه هوشمند یا "audio_file" برای فایل صوتی
  }

- ساختار پاسخ موفق (200 OK):
  { "status": "success", "message": "تماس خروجی با موفقیت برقرار شد" }

- خطاهای متداول:
  - 400: شماره تماس یا شناسه اپراتور الزامی است
  - 401: کلید API نامعتبر است (X-API-KEY ارسال نشده یا اشتباه است)
  - 403: دسترسی به وب‌سرویس تماس خروجی فعال نیست
  - 500: موجودی کیف پول کاربر کافی نیست

۲. استانداردهای سرور دریافت وب‌هوک ابزارها (Tool Webhooks):
اگر اپراتور هوش مصنوعی نیاز به اجرای وب‌هوک در حین مکالمه داشته باشد:
- درخواست ورودی از سمت پشتیار:
  POST https://your-server.com/api/webhook
  Headers: X-INTERNAL-TOKEN: secret_token
  Body: { "call_id": "...", "caller_number": "...", "operator_id": "...", "arguments": { ... } }
- پاسخ سرور شما باید کد 200 OK به همراه فرمت JSON زیر با زمان پاسخ زیر ۳ ثانیه باشد:
  {
    "success": true,
    "result": { "status": "ارسال شده", "tracking_code": "12345" },
    "message": "توضیح برای هوش مصنوعی"
  }

۳. استانداردهای اتصال به سامانه CRM (اتصال پیش و پس از تماس):
اگر کاربر از شما خواست سامانه CRM یا پایگاه داده مشتریانش را به پشتیار متصل کنید، دو اندپوینت زیر را پیاده‌سازی نمایید:

الف) استعلام پرونده مشتری قبل از تماس (Pre-Call Lookup):
- متد: POST
- آدرس نمونه: https://your-crm.com/api/customer
- بدنه ارسالی از پشتیار:
  { "phone": "09123456789" }
- پاسخ مورد انتظار سرور CRM شما (JSON):
  {
    "name": "نام و نام خانوادگی مشتری",
    "status": "وضعیت مشتری (مثلاً مشتری VIP، در انتظار پرداخت، کاربر فعال)",
    "notes": "خلاصه سوابق گذشته یا ترجیحات مشتری"
  }
- اگر شماره مشتری جدید بود:
  { "found": false, "message": "مخاطب جدید است" }

ب) ثبت خلاصه مکالمه پس از پایان تماس (Post-Call Logging):
- متد: POST
- آدرس نمونه: https://your-crm.com/api/save-call
- بدنه ارسالی از پشتیار:
  {
    "phone": "09123456789",
    "summary": "خلاصه مکالمه صوتی تولید شده توسط مدل هوش مصنوعی"
  }
- پاسخ مورد انتظار سرور شما:
  { "success": true, "message": "گزارش تماس در پرونده مشتری ذخیره شد" }

لطفاً کدهای اتصال را با بهترین الگوهای معماری، مدیریت تمیز خطاها (Error Handling)، اعتبارسنجی ورودی‌ها و با در نظر گرفتن متغیرهای محیطی (.env) در زبان و فریم‌ورک درخواستی من بنویسید.

من می‌خواهم سامانه CRM / پایگاه داده مشتریان پروژه‌ام را به پلتفرم تلفنی هوش مصنوعی پشتیار (Poshtyar) متصل کنم تا در تماس‌های تلفنی، مشتریان با نام شناخته شوند و سوابقشان بررسی شود.

پشتیار برای اتصال به CRM به دو اندپوینت ساده HTTP POST نیاز دارد:
۱. اندپوینت استعلام سابقه (Pre-Call): شماره تماس مشتری را با کلید "phone" دریافت می‌کند، در دیتابیس جستجو کرده و اطلاعاتی مثل "name"، "status" و "notes" را به صورت JSON بازمی‌گرداند.
۲. اندپوینت ثبت گزارش (Post-Call): پس از پایان مکالمه، "phone" و "summary" (خلاصه مکالمه) را دریافت کرده و در پرونده مشتری ذخیره می‌کند.

لطفاً این دو اندپوینت را به صورت کاملاً تمیز، بهینه و آماده در [زبان یا فریم‌ورک پروژه من مانند: Laravel / Express / FastAPI / Django / WordPress] برایم بنویس.

# Poshtyar AI VoIP API & CRM Integration Rules

- When integrating Poshtyar Outbound Calls:
  - Always use `POST https://api.poshtyar.com/api/v1/external/calls/originate`
  - Pass the authentication token using header `X-API-KEY: process.env.POSHTYAR_API_KEY`
  - Required fields in JSON body: `phone_number` and `operator_id`
  - Optional fields: `recipient_name`, `topic`, `description`, `opener_text`, `retry_policy`, `outbound_type`
  - Always clean up and validate phone numbers (support standard Iranian mobile formats e.g. 0912xxxxxxx or +98912xxxxxxx)
  - Handle HTTP error codes gracefully: 400 (bad input), 401 (invalid key), 403 (access denied), 500 (low balance)

- When writing CRM Integration Webhooks:
  - Pre-Call Lookup Endpoint: receives `{ "phone": "09123456789" }`, queries DB, returns `{ "name": "...", "status": "...", "notes": "..." }` or `{ "found": false }`
  - Post-Call Logging Endpoint: receives `{ "phone": "09123456789", "summary": "..." }`, stores note in CRM, returns `{ "success": true }`
  - Keep response time under 2 seconds and use standard UTF-8 JSON.

- When writing Tool Webhooks:
  - Must return `200 OK` JSON in under 3 seconds
  - Format: `{ "success": true, "result": { ... }, "message": "..." }`
  - Protect endpoints with `X-INTERNAL-TOKEN` header verification