Skip to navigation

گزارش‌های مصرف

این اندپوینت فعال است. همه موارد این صفحه قابل فراخوانی‌اند، به‌جز تفکیک اینستاگرام بر اساس نقطه ورود که هنوز پیش‌انتشار است و ابتدای آن مشخص شده است.

یک اندپوینت، فعالیت همه ربات‌های حساب شما را گزارش می‌کند.

curl "https://api-chat.parstechai.com/v1/usage?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
Response
{
"window": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-30T23:59:59Z" },
"data": [
{
"robot_id": "a3f9c21b4e7d40a8",
"external_id": "shop_10422",
"name": "Rose Flower Shop",
"messages": {
"total": 1840,
"units": 1840,
"by_role": { "client": 900, "ai": 820, "operator": 120 }
},
"conversations": { "total": 312 },
"channels_connected": 1
}
],
"pagination": { "limit": 50, "offset": 0, "total_count": 128, "has_more": true },
"metadata": {
"processed_at": "2026-10-01T09:15:22Z",
"cache_hit": false
}
}

by_role پاسخ‌های هوش مصنوعی را از پاسخ‌های انسانی جدا می‌کند؛ همان چیزی که برای نشان‌دادن سهم خودکارسازی از پشتیبانی به مشتریان خودتان لازم دارید.

messages.total و messages.units یک عدد نیستند. رباتی که از مدل با دقت بالاتر استفاده می‌کند، به ازای هر پیام دو واحد مصرف می‌کند؛ پس مشتری‌ای که روی این مدل ۱٬۰۰۰ پیام فرستاده، total: 1000 و units: 2000 نشان می‌دهد.

تطبیق صورتحساب را با units انجام دهید. total را به‌عنوان تعداد پیام به مشتری نشان دهید.

external_id شناسه شما برای ربات است. تا زمانی که ساخت ربات از طریق API منتشر نشود، مقدار آن null است؛ پس امروز همه ربات‌ها این‌جا null برمی‌گردانند. تا آن زمان تطبیق را بر اساس robot_id انجام دهید.

بازه پیش‌فرض ۳۰ روز گذشته است و نمی‌تواند بیش از یک سال باشد. درخواست بازه‌ای بزرگ‌تر، from بعد از to، یا limit بیشتر از 100، خطای 400 برمی‌گرداند.

این گزارش فعالیت ربات‌ها را نشان می‌دهد، نه موجودی باقی‌مانده شما را. به این پرسش پاسخ می‌دهد که «این مشتری چقدر مصرف کرد؟»، نه «چقدر از حساب باقی مانده است؟». موجودی بسته خارج از محدوده این API است.

metadata.processed_at لحظه‌ای است که ارقام تا آن زمان دقیق‌اند. مصرف به‌صورت دوره‌ای محاسبه می‌شود، پس ممکن است گفتگویی که چند ثانیه پیش انجام شده هنوز شمرده نشده باشد.

یک ربات

برای محدودکردن گزارش به یک ربات، robot_id را بفرستید.

curl "https://api-chat.parstechai.com/v1/usage?robot_id=a3f9c21b4e7d40a8&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"

صفحه‌بندی

با limit و offset صفحه‌بندی کنید. pagination.total_count تعداد ربات‌های منطبق با درخواست شما در همه صفحه‌هاست؛ پس پیش از شروع می‌دانید چند فراخوانی لازم است.

curl "https://api-chat.parstechai.com/v1/usage?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&limit=50&offset=50" \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
Python
import math, requests
params = {"from": FROM, "to": TO, "limit": 50, "offset": 0}
first = requests.get(URL, headers=HEADERS, params=params, timeout=30).json()
pages = math.ceil(first["pagination"]["total_count"] / first["pagination"]["limit"])
robots = list(first["data"])
for page in range(1, pages):
params["offset"] = page * params["limit"]
robots += requests.get(URL, headers=HEADERS, params=params, timeout=30).json()["data"]

تفکیک اینستاگرام بر اساس نقطه ورود

پیش‌انتشار؛ هنوز قابل فراخوانی نیست. این بخش شکل API را تعهد می‌کند، نه تاریخ آن را. ارسال breakdown=source در حال حاضر همان پاسخ استاندارد بالا را بدون فیلدهای اضافه برمی‌گرداند. بقیه موارد این صفحه فعال‌اند.

مشتری‌ای که بیشتر حجمش از پاسخ به استوری می‌آید، محصولی متفاوت از مشتری‌ای دارد که کامنت‌ها آن را پیش می‌برند؛ و یک total واحد این تفاوت را پنهان می‌کند.

curl "https://api-chat.parstechai.com/v1/usage?robot_id=a3f9c21b4e7d40a8&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&breakdown=source" \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
Response
{
"data": [
{
"robot_id": "rbt_8fK2mQ",
"external_id": "shop_10422",
"channel": "instagram",
"window": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-30T23:59:59Z" },
"messages": {
"total": 1840,
"by_role": { "client": 900, "ai": 820, "operator": 120 }
},
"conversations": { "total": 312 },
"channels_connected": 1,
"by_source": {
"direct": { "conversations": 180, "messages": 1120 },
"comment": { "conversations": 84, "messages": 310 },
"story_reply": { "conversations": 36, "messages": 290 },
"story_mention": { "conversations": 12, "messages": 120 }
},
"totals": { "conversations": 312, "messages": 1840 }
}
],
"pagination": { "limit": 50, "offset": 0, "total_count": 1, "has_more": false },
"metadata": {
"request_id": "req_8f2Kq9mR",
"processed_at": "2026-10-01T09:15:22Z"
}
}

breakdown=source فیلدهایی اضافه می‌کند و چیزی را جایگزین نمی‌کند. messages، conversations و channels_connected همچنان وجود دارند؛ پس یک تجزیه‌گر هر دو شکل را پوشش می‌دهد.

منبعمعنی
directدایرکتی که مشتری شروع کرده است
commentبا یک کامنت زیر پست ایجاد شده است
story_replyمشتری به یک استوری پاسخ داده است
story_mentionمشتری در استوری خودش حساب را منشن کرده است
reelاز یک ریلز آغاز شده است

همین واژگان source در هر رویداد message هم می‌آید؛ پس می‌توانید بدون فراخوانی دوم، هر رویداد را به نقطه ورودش نسبت دهید.

پیدا کردن کسری‌ها

اگر تحویل یک وب‌هوک همه تلاش‌های دوباره خود را مصرف کرده باشد، از طریق همین API متوجه می‌شوید. شمارش‌های این‌جا را با آنچه برای همان بازه ذخیره کرده‌اید مقایسه کنید.