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

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": "توضیح برای هوش مصنوعی"
  }

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

# Poshtyar AI VoIP API 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 Tool Webhooks:
  - Must return `200 OK` JSON in under 3 seconds
  - Format: `{ "success": true, "result": { ... }, "message": "..." }`
  - Protect endpoints with `X-INTERNAL-TOKEN` header verification