پیجهای مجاز
/pagesدسترسی لازم:pages:read
این API برای همگامسازی مخاطبان، رسیدگی به دایرکت و کامنت و دریافت آمار جریانهای موجود طراحی شده است. ساخت یا تغییر جریان در این API ارائه نمیشود.
در پنل، بخش API و اتصال به نرمافزارها، یک اتصال با پیجها و دسترسیهای لازم بسازید. در هر درخواست، کلید را در هدر Authorization با روش Bearer ارسال کنید. کلید یک سال اعتبار دارد و از پنل قابل تغییر یا لغو است.
درخواستها را از سرور برنامه خود بفرستید. توکن را در کد مرورگر یا مخزن عمومی قرار ندهید. درخواست با Bearer به کوکی و راهاندازی CSRF نیاز ندارد. فقط پیجهایی که مالکشان هستید و برای اتصال انتخاب کردهاید در دسترساند؛ پیج اشتراکی تیم قابل واگذاری نیست. دایرکت و کامنت فعلاً فقط برای اینستاگرام پشتیبانی میشوند.
آدرس پایه API
https://highfollower.com/api/v1curl 'https://highfollower.com/api/v1/pages' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Accept: application/json'/pagesدسترسی لازم:pages:read
{
"status": "ok",
"message": "",
"data": [],
"meta": {
"per_page": 50,
"next_cursor": null,
"has_more": false
}
}پارامتر page شناسه داخلی پیج است و با page_id اینستاگرام تفاوت دارد. کلید conversation_key را از فهرست گفتگوها بگیرید و برای قرار دادن در URL کدگذاری کنید.
فهرستها بهجز /pages و /tags صفحهبندی مکاننما دارند. per_page را بین ۱ تا ۱۰۰ (پیشفرض ۵۰) بفرستید؛ سپس meta.next_cursor را همراه فیلترهای قبلی در cursor قرار دهید تا meta.has_more برابر false شود. مکاننما را تغییر ندهید. مخاطبان بهترتیب صعودی updated_at و id و پیامها از جدید به قدیم برمیگردند. برای همگامسازی مخاطبان از بازههای همپوشان updated_since و بهروزرسانی بر اساس شناسه استفاده کنید. تاریخها ISO 8601 هستند و به UTC تبدیل میشوند.
done و updated_since؛ کامنتها: media_id و parent_id. آمار جریان period=7
هر دو مسیر ارسال پاسخ به هدر Idempotency-Key با مقدار UUID و متن غیرخالی message تا ۱۰۰۰ کاراکتر نیاز دارند. برای هر پاسخ جدید یک UUID جدید بسازید. تکرار همان کلید با همان پیج، مقصد و متن، نتیجه ثبتشده را برمیگرداند؛ تغییر محتوا با همان کلید خطای 409 میدهد. پاسخ 503 با status=uncertain یعنی ارسال در جریان است یا نتیجه مشخص نیست؛ پیش از ارسال دوباره صندوق ورودی را بررسی کنید و هرگز برای تکرار خودکار، کلید جدید نسازید.
curl -X POST 'https://highfollower.com/api/v1/pages/12/conversations/CONVERSATION_KEY/replies' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Accept: application/json' \
-H 'Idempotency-Key: 7d598e78-eaf7-4eb4-9c48-7e57ef887902' \
-H 'Content-Type: application/json' \
-d '{"message":"Hello! How can we help?"}'برای تغییر وضعیت گفتگو، فیلد status را با open یا done بفرستید. برای جایگزینی برچسب مخاطب، آرایه tag_ids را بفرستید؛ آرایه خالی همه برچسبها را حذف میکند.
آدرس و رویدادها را در اتصال تنظیم کنید و از ارسال آزمایشی استفاده کنید. هر وبهوک شامل id، type، api_version، occurred_at، platform_page_id، platform و data است. پیام و کامنت، ورودی و خروجی را پوشش میدهند. رویداد synced علامت دریافت دوباره فهرست از API است.
یک دامنه عمومی HTTPS روی پورت ۴۴۳ با IPv4 عمومی و بدون نام کاربری، رمز عبور یا fragment در نشانی وارد کنید. تغییر مسیر دنبال نمیشود. هر رویداد را همراه دسترسی خواندن مرتبط فعال کنید. فقط پس از ذخیره پایدار رویداد پاسخ 2xx بدهید. امکان تحویل تکراری یا نامرتب وجود دارد؛ دادهها را بهصورت دورهای با API تطبیق دهید.
message.createdconversations:readmessage.deletedconversations:readconversation.updatedconversations:readdirects.syncedconversations:readcomment.createdcomments:readcomment.deletedcomments:readcomment.updatedcomments:readcomments.syncedcomments:readcontact.updatedcontacts:readlead.createdleads:readwebhook.test—{
"id": "f5e0c74f-364c-44ae-bc5b-486a2afba3b5",
"type": "message.created",
"api_version": "v1",
"occurred_at": "2026-10-02T10:00:00.000000Z",
"platform_page_id": 12,
"platform": "instagram",
"data": {
"id": "provider-message-id",
"message_id": "provider-message-id",
"conversation_key": "existing-conversation-key",
"sender": {
"id": "provider-user-id"
},
"message": {
"text": "Hello"
}
}
}X-HighFollower-Event-Id: f5e0c74f-364c-44ae-bc5b-486a2afba3b5
X-HighFollower-Timestamp: <Unix seconds>
X-HighFollower-Signature: sha256=<hex HMAC-SHA256>رویداد lead.created پس از ثبت موفق هر رکورد جدید در دادههای جمعآوریشده فلو ارسال میشود و به دسترسی leads:read نیاز دارد. هر فیلد ذخیرهشده یک رکورد جداست؛ ویرایش رکورد قبلی یا تکرار اجرای همان ذخیره، رویداد جدید ایجاد نمیکند. دادهها شامل شناسه لید، پیج، فلو و اجرا، شناسه فرستنده، نام و مقدار فیلد، منبع و زمان ثبت هستند. این رویداد مستقل از contact.updated است و نیازی به ذخیره همان مقدار در پروفایل مخاطب ندارد.
{
"id": "591396d6-5561-52a5-9506-14e23f4e5c25",
"type": "lead.created",
"api_version": "v1",
"occurred_at": "2026-10-31T10:00:00.000000Z",
"platform_page_id": 12,
"platform": "instagram",
"data": {
"id": 42,
"platform_page_id": 12,
"automation_flow_id": 7,
"execution_id": 103,
"flow_node_id": "collect-phone",
"sender_id": "provider-user-id",
"field_name": "phone",
"value": "+989120000000",
"source_type": "direct",
"source_id": "provider-message-id",
"created_at": "2026-10-31T10:00:00.000000Z"
}
}امضا را روی بدنه خام، پیش از تبدیل JSON، بررسی کنید: HMAC-SHA256(secret, timestamp + "." + raw_body). هدر X-HighFollower-Signature با sha256= شروع میشود. زمان X-HighFollower-Timestamp را با حداکثر اختلاف پنج دقیقه کنترل کنید و id رویداد را برای جلوگیری از پردازش تکراری ذخیره کنید.
import hashlib, hmac, json, time
def verify_webhook(raw_body, headers, secret):
timestamp = headers["X-HighFollower-Timestamp"]
if abs(time.time() - int(timestamp)) > 300:
raise ValueError("Expired webhook")
digest = hmac.new(
secret.encode(), timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(
"sha256=" + digest, headers["X-HighFollower-Signature"]
):
raise ValueError("Invalid signature")
return json.loads(raw_body)
# Deduplicate the verified payload["id"] in your database.
# Return 2xx after durably accepting the event.پاسخ 2xx یعنی دریافت موفق. خطای شبکه، ۴۰۸، ۴۲۵، ۴۲۹ و 5xx تا هشت تلاش تکرار میشوند؛ سایر وضعیتها، از جمله redirect، ناموفقاند. تأخیر تلاشها: ۱، ۵، ۱۵، ۶۰، ۱۸۰، ۳۶۰ و ۷۲۰ دقیقه بهعلاوه تأخیر صف. شناسه رویداد ثابت است. سابقه ۳۰ روز نگهداری میشود. تغییر آدرس یا امضا، تحویلهای در انتظار قبلی را لغو میکند.
API و وبهوک به اشتراک پولی فعال Pro نیاز دارند (پیشفرض ۱۰ اتصال فعال؛ سقف دقیق را در اشتراک خود ببینید). دوره آزمایشی این دسترسی را ندارد. سقف درخواست برای هر اتصال ۱۲۰ و برای هر IP مبدأ ۲۴۰ درخواست در دقیقه است. در خطای 429 بهاندازه ثانیههای Retry-After صبر کنید. پاسخدهی به پیج فعال، اتصال معتبر به سرویس و اعتبار کافی نیاز دارد. پایان اشتراک درخواستها و وبهوکها را متوقف میکند، ولی کلیدها باقی میمانند.
401: توکن نامعتبر، لغوشده یا منقضی. 403: دسترسی ناکافی یا پیج غیرفعال برای ارسال. 404: منبع وجود ندارد یا خارج از دسترسی است. 409: استفاده از Idempotency-Key قبلی برای محتوای متفاوت. 422: ورودی نامعتبر یا plan_limit_reached. 429: عبور از سقف درخواست. 503 همراه status=uncertain: ارسال در جریان است یا نتیجه نامشخص است؛ قبل از ارسال مجدد صندوق ورودی را بررسی کنید.