Facebook Pages API بلغتي Python وNode.js: أمثلة عملية
تستدعي أمثلة Python وNode.js واجهة Facebook Pages API عبر طلبات HTTPS عادية إلى graph.facebook.com/v26.0 باستخدام رمز الوصول (token) الخاص بالصفحة: ينشر POST /{page-id}/feed وPOST /{page-id}/photos، و/{post-id}/comments يقرأ التعليقات ويرد عليها، وPOST /{page-id}/messages يرسل ردًا في Messenger، وGET /{page-id}/insights يقرأ المقاييس، ويتحقق HMAC-SHA256 من النص الخام عبر X-Hub-Signature-256 في كل خطاف ويب (webhook).
يمنح easyCoexistence الصفحة المتصلة هذه المهام كأدوات MCP، من publish_facebook_post وreply_to_comment إلى send_social_dm وget_social_insights، ويعيد توجيه أحداثها موقّعة بـ X-EC-Signature، ويمنح كودك الخاص معرّف الصفحة وقاعدة API عبر get_social_credentials.
معامل text الخاص بصورة الصفحة، إذ يعلّم مرجع الصور لدى Meta الحقل message بأنه مهجور هناك.
ترويسة استجابة يحدد حقل estimated_time_to_regain_access فيها عدد الدقائق حتى تعود الاستدعاءات المقيّدة للعمل.
قيمة messaging_type للرد على رسالة تلقّتها الصفحة، ضمن نافذة 24 ساعة.
كيف يوجّه الرد الخاص إلى الشخص الذي علّق، عبر نقطة النهاية (endpoint) /{page-id}/messages نفسها.
ما الذي تحتاجه الأمثلة قبل تشغيلها؟
معرّف الصفحة (Page ID) ورمز الوصول token الخاص بتلك الصفحة، ويُقرأ من /me/accounts باستخدام token المستخدم طويل الأمد، إضافةً إلى Python 3 مع مكتبة requests، أو Node.js 18 أو أحدث، الذي لا تحتاج دالة fetch المدمجة فيه إلى أي حزمة. كل مهمة تحتاج أيضًا إلى صلاحيتها على الـ token ومهمتها على الصفحة، وتستدعي الأمثلة Graph API v26.0:
كيف تنشر منشورًا وصورة في Python؟
بدالة مساعدة واحدة تعيد استخدامها الأمثلة اللاحقة: تضيف graph() رمز الصفحة، وترسل معاملات GET في سلسلة الاستعلام وحقول POST بصيغة JSON كما تفعل أمثلة Meta نفسها، وتحوّل كائن الخطأ من Meta إلى GraphError يحمل code وerror_subcode. تنتظر وتعيد المحاولة فقط لرموز الأخطاء المؤقتة ورموز تجاوز المعدل، للمدة التي تطلبها الترويسة X-Business-Use-Case-Usage متى وردت، وتطلق الأخطاء الأخرى فورًا.
import json, os, time
import requests
GRAPH = "https://graph.facebook.com/v26.0"
PAGE_ID = os.environ["PAGE_ID"]
PAGE_TOKEN = os.environ["PAGE_TOKEN"] # the Page's own token, from /me/accounts
RETRY = {1, 2, 4, 17, 32, 613, 80001} # temporary or rate limited
class GraphError(Exception):
def __init__(self, err):
super().__init__(err.get("message"))
self.code, self.subcode = err.get("code"), err.get("error_subcode")
def wait_seconds(response, attempt):
usage = json.loads(response.headers.get("x-business-use-case-usage", "{}"))
minutes = [u.get("estimated_time_to_regain_access", 0) for v in usage.values() for u in v]
return max([60 * m for m in minutes] + [30 * 2 ** attempt])
def graph(method, path, retries=3, **fields):
fields["access_token"] = PAGE_TOKEN
send = {"params": fields} if method == "GET" else {"json": fields}
for attempt in range(retries + 1):
response = requests.request(method, f"{GRAPH}/{path}", timeout=30, **send)
body = response.json()
if "error" not in body:
return body
err = GraphError(body["error"])
if err.code not in RETRY or attempt == retries:
raise err
time.sleep(wait_seconds(response, attempt))
post = graph("POST", f"{PAGE_ID}/feed", message="Open until 11pm this Friday.")
photo = graph("POST", f"{PAGE_ID}/photos",
url="https://example.com/menu.jpg", caption="This week's menu")
print(post["id"], photo["post_id"])كيف تنشرها في Node.js؟
بالدالة المساعدة نفسها في Node.js 18 أو أحدث، تُحفظ بامتداد .mjs ليعمل await على المستوى الأعلى، مع استخدام fetch المدمجة بدلًا من مكتبة عميل. يرسل استدعاء الصورة url وcaption، أي حقل text الخاص بمسار photos، فتعيد Meta معرّف الصورة id ومعرّف منشور الصفحة post_id الذي يحمل الصورة، بينما يعيد استدعاء المنشور المعرّف id وحده.
// Node.js 18 or later, saved as an .mjs file: fetch and top-level await are built in.
const GRAPH = "https://graph.facebook.com/v26.0";
const { PAGE_ID, PAGE_TOKEN } = process.env; // the Page's own token, from /me/accounts
const RETRY = new Set([1, 2, 4, 17, 32, 613, 80001]); // temporary or rate limited
class GraphError extends Error {
constructor(err) {
super(err.message);
this.code = err.code;
this.subcode = err.error_subcode;
}
}
function waitMs(response, attempt) {
const usage = JSON.parse(response.headers.get("x-business-use-case-usage") ?? "{}");
const minutes = Object.values(usage).flat().map((u) => u.estimated_time_to_regain_access ?? 0);
return Math.max(30_000 * 2 ** attempt, ...minutes.map((m) => m * 60_000));
}
async function graph(method, path, fields = {}, retries = 3) {
const url = new URL(`${GRAPH}/${path}`);
const init = { method };
const all = { ...fields, access_token: PAGE_TOKEN };
if (method === "GET") {
for (const [key, value] of Object.entries(all)) url.searchParams.set(key, String(value));
} else {
init.headers = { "Content-Type": "application/json" };
init.body = JSON.stringify(all);
}
for (let attempt = 0; ; attempt++) {
const response = await fetch(url, init);
const body = await response.json();
if (!body.error) return body;
if (!RETRY.has(body.error.code) || attempt === retries) throw new GraphError(body.error);
await new Promise((done) => setTimeout(done, waitMs(response, attempt)));
}
}
const post = await graph("POST", `${PAGE_ID}/feed`, { message: "Open until 11pm this Friday." });
const photo = await graph("POST", `${PAGE_ID}/photos`, {
url: "https://example.com/menu.jpg",
caption: "This week's menu",
});
console.log(post.id, photo.post_id);كيف تقرأ التعليقات وتردّ عليها في Python؟
اقرأ تعليقات المنشور بالمعاملات fields وfilter=stream لتعليقات كل المستويات بترتيب زمني، وorder=reverse_chronological للأحدث أولًا، ثم رد بصفة الصفحة بإرسال رسالة إلى مسار comments الخاص بالتعليق نفسه. يجب أن يصدر token عن شخص يملك صلاحية MODERATE، وإلا تحذف Meta معرّفات التعليقات، ويحتاج الرد إلى pages_manage_engagement. يقودك paging.next إلى صفحات أقدم.
# graph() as in the first example
post_id = post["id"] # {page-id}_{post-id}, as the publish call returned it
page = graph("GET", f"{post_id}/comments", fields="id,message,created_time,can_reply_privately",
filter="stream", order="reverse_chronological", limit=50)
for comment in page["data"]:
if "?" in comment.get("message", ""):
graph("POST", f"{comment['id']}/comments",
message="Thanks for asking! Our hours are on the Page.")
older = page.get("paging", {}).get("next") # follow it to read further backكيف تقرأ التعليقات وتردّ عليها في Node.js؟
الاستدعاءان نفسهما، مع استخدام كائن URL لبناء سلسلة الاستعلام: طلب GET بالمعاملات fields وfilter وorder، ثم POST إلى /{comment-id}/comments. يحدد can_reply_privately، المطلوب في fields، هل ما زال بإمكان الصفحة إرسال رد خاص لذلك المعلّق، وهذا مهم قبل مثال Messenger أدناه. احتفظ بمعرّفات التعليقات التي رددت عليها حتى لا يرد إعادة التشغيل مرتين.
// graph() as in the first example
const postId = post.id; // {page-id}_{post-id}, as the publish call returned it
const page = await graph("GET", `${postId}/comments`, {
fields: "id,message,created_time,can_reply_privately",
filter: "stream",
order: "reverse_chronological",
limit: 50,
});
for (const comment of page.data) {
if ((comment.message ?? "").includes("?")) {
await graph("POST", `${comment.id}/comments`, {
message: "Thanks for asking! Our hours are on the Page.",
});
}
}
const older = page.paging?.next; // follow it to read further backكيف ترسل ردًا عبر Messenger في Python؟
أرسل POST إلى /{page-id}/messages مع recipient.id يساوي معرّف الشخص المحدد بالنطاق الخاص بالصفحة (Page-scoped ID) من webhook الرسائل، وmessaging_type بقيمة RESPONSE، والنص. يلتقط المثال الرفضين اللذين لا يستحقان إعادة المحاولة: الخطأ 10 مع subcode 2534022 أو 2018278 عندما تكون نافذة 24 ساعة قد أُغلقت، والخطأ 551 عندما يكون الشخص غير متاح. تضع دالة private_reply() مكان المعرّف recipient.comment_id، وهي الرسالة الواحدة التي يسمح بها التعليق خلال 7 أيام.
# graph(), GraphError and PAGE_ID as in the first example
def reply(psid, text):
"""psid: sender.id from the messages webhook, within 24 hours of the person's message."""
try:
return graph("POST", f"{PAGE_ID}/messages", recipient={"id": psid},
messaging_type="RESPONSE", message={"text": text})
except GraphError as e:
if (e.code == 10 and e.subcode in (2534022, 2018278)) or e.code == 551:
return None # the window has closed, or the person is unavailable: no retry
raise
def private_reply(comment_id, text):
"""One Messenger message to the person who commented, within 7 days of the comment."""
return graph("POST", f"{PAGE_ID}/messages", recipient={"comment_id": comment_id},
message={"text": text})كيف ترسل ردًا عبر Messenger في Node.js؟
نص الطلب نفسه بلغة JavaScript، مع recipient وmessaging_type وmessage، ترسلها graph() بصيغة JSON. تعيد Meta عند قبول الإرسال recipient_id وmessage_id، ويستحسن تخزينهما مع المحادثة. يحمل الرد الخاص رابطًا يعود إلى التعليق الذي يردّ عليه، وتستمر المحادثة ضمن نافذة 24 ساعة المعتادة بمجرد أن يكتب الشخص ردًا.
// graph(), GraphError and PAGE_ID as in the first example
async function reply(psid, text) {
// psid: sender.id from the messages webhook, within 24 hours of the person's message
try {
return await graph("POST", `${PAGE_ID}/messages`, {
recipient: { id: psid },
messaging_type: "RESPONSE",
message: { text },
});
} catch (e) {
const closed =
e instanceof GraphError && ((e.code === 10 && [2534022, 2018278].includes(e.subcode)) || e.code === 551);
if (closed) return null; // the window has closed, or the person is unavailable: no retry
throw e;
}
}
function privateReply(commentId, text) {
// one Messenger message to the person who commented, within 7 days of the comment
return graph("POST", `${PAGE_ID}/messages`, {
recipient: { comment_id: commentId },
message: { text },
});
}كيف تقرأ إحصاءات الصفحة في Python؟
أرسل GET إلى /{page-id}/insights مع قائمة مقاييس مفصولة بفواصل، وperiod=day، ونافذة زمنية بين since وuntil بالثواني منذ UNIX، ويغطي الطلب الواحد حتى 90 يومًا. ثلاثة من هذه المقاييس حلّت محل مقاييس أوقفتها Meta: page_media_view محل page_impressions، وpage_total_media_view_unique محل page_impressions_unique، وpage_follows محل page_fans، بينما يحسب page_post_engagements ردود الفعل والتعليقات والمشاركات.
# graph() and PAGE_ID as in the first example
until = int(time.time())
since = until - 28 * 86400 # one request can cover up to 90 days
metrics = "page_media_view,page_total_media_view_unique,page_post_engagements,page_follows"
data = graph("GET", f"{PAGE_ID}/insights", metric=metrics, period="day", since=since, until=until)
for metric in data["data"]:
for point in metric["values"]:
print(metric["name"], point["end_time"][:10], point["value"])كيف تقرأ إحصاءات الصفحة في Node.js؟
الاستدعاء نفسه، مع حساب since وuntil من Date.now() بالثواني. تعود كل مقياس باسمه وفترته وقائمة values من أزواج value وend_time، زوج لكل يوم؛ ومع ضبط since يقع أول end_time في اليوم الذي يلي since، لتدخل بيانات ذلك اليوم. يحتاج token إلى read_insights وpages_read_engagement، من شخص يملك مهمة ANALYZE.
// graph() and PAGE_ID as in the first example
const until = Math.floor(Date.now() / 1000);
const since = until - 28 * 86400; // one request can cover up to 90 days
const data = await graph("GET", `${PAGE_ID}/insights`, {
metric: "page_media_view,page_total_media_view_unique,page_post_engagements,page_follows",
period: "day",
since,
until,
});
for (const metric of data.data) {
for (const point of metric.values) {
console.log(metric.name, point.end_time.slice(0, 10), point.value);
}
}كيف تتحقق من توقيع webhook في Python؟
أعد حساب X-Hub-Signature-256 من النص الخام للطلب ومن سر التطبيق، ثم قارن القيمتين بزمن ثابت. توقّع Meta كل طلب POST بـ HMAC-SHA256 للحمولة، ومفتاحه App Secret من الإعدادات الأساسية في App Dashboard، وتكتبه بعد sha256=. مرّر النص بصيغة bytes قبل أي تحليل لـ JSON، إذ يعطيك request.body في Django وawait request.body() في FastAPI البايتات التي وقّعتها Meta.
import hashlib, hmac, os
APP_SECRET = os.environ["APP_SECRET"].encode() # App Dashboard, Settings, Basic
def signed_by_meta(raw_body: bytes, header: str) -> bool:
"""raw_body: the request body exactly as received. header: X-Hub-Signature-256."""
expected = "sha256=" + hmac.new(APP_SECRET, raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), (header or "").encode())
# Django: signed_by_meta(request.body, request.headers.get("X-Hub-Signature-256"))
# FastAPI: signed_by_meta(await request.body(), request.headers.get("X-Hub-Signature-256"))كيف تتحقق من توقيع webhook في Node.js؟
الفحص نفسه باستخدام node:crypto، الذي يحتاج النص كـ Buffer: في Express يُبقي express.raw الطلب غير محلَّل على ذلك المسار. تُطلق timingSafeEqual خطأ عند اختلاف طولي المدخلات، لذا يُجرى اختبار الطول أولًا. أجب بالرمز 200 بسرعة ونفّذ العمل لاحقًا، لأن Meta تعيد محاولة الطلبات الفاشلة وقد ترسل الحدث مرتين؛ وتغطي صفحة التحقق مصافحة hub.challenge التي تسبق أي حدث.
import crypto from "node:crypto";
const APP_SECRET = process.env.APP_SECRET; // App Dashboard, Settings, Basic
function signedByMeta(rawBody, header = "") {
// rawBody: a Buffer holding the request body exactly as received. header: X-Hub-Signature-256
const digest = crypto.createHmac("sha256", APP_SECRET).update(rawBody).digest("hex");
const expected = Buffer.from(`sha256=${digest}`);
const given = Buffer.from(header);
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}
// Express: app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
// if (!signedByMeta(req.body, req.get("X-Hub-Signature-256"))) return res.sendStatus(401);
// res.sendStatus(200); // then work on JSON.parse(req.body) after answering
// });ما رموز الأخطاء التي ينبغي للكود أن يتصرف بناءً عليها؟
الرموز التي تفرّق بينها أدلة الأخطاء في Meta، لأن كلًا منها يستدعي استجابة مختلفة: إعادة المحاولة مع token مرفوض أو معامل خاطئ تفشل مرة أخرى، بينما ينجح الاستدعاء المقيَّد بعد الانتظار. تعيد graph() المحاولة للرموز المؤقتة ورموز تجاوز المعدل، وتطلق الباقي ليتعامل معه المستدعي:
كيف تشغّل المهام نفسها عبر easyCoexistence؟
كأدوات MCP يستدعيها Claude أو ChatGPT أو وكيلك الخاص على صفحة متصلة، ويحتفظ easyCoexistence بـ token الصفحة. لا تُسلَّم رموز الصفحات أبداً، لذا تعمل الأمثلة أعلاه برمز من تطبيق Meta الخاص بك؛ وتعيد get_social_credentials معرّف الصفحة وقاعدة Graph API. أداة كل مهمة:
الأخطاء الشائعة
- استدعاء endpoints الخاصة بالصفحة برمز المستخدم. معظمها يتوقع token الصفحة نفسه، والاستدعاءات بـ token المستخدم أو التطبيق تُحتسب على حدود المعدل الخاصة بالمستخدم أو التطبيق بدلًا من حدود الصفحة.
- نشر النص نفسه مرتين متتاليتين. ترفض Meta المنشورات المتطابقة المتتالية بالخطأ 506، لذا على مهمة تُعاد تشغيلها أن تغيّر المحتوى أو تتخطى المنشور.
- جمع المشاهدين الفريدين اليوميين. يحسب page_total_media_view_unique المشاهدين الفريدين في كل فترة، فلا تُجمع القيم اليومية لتعطي شهرًا؛ اطلب period بالقيمة days_28 بدلًا من ذلك.
- إرسال token الصفحة إلى متصفح أو تطبيق. يجب أن تعمل هذه الاستدعاءات على الخادم، حيث يبقى token بعيدًا عن متناول أي شخص يقرأ العميل.
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل أحتاج إلى SDK لاستدعاء Facebook Pages API؟
لا. Graph API يعمل عبر HTTPS مع JSON، لذا تكفي طلبات Python وfetch المدمجة في Node.js 18 أو أحدث، كما تُظهر الأمثلة في هذه الصفحة.
هل يمكن للكود نفسه النشر على عدة صفحات؟
نعم. يعيد /me/accounts token منفصلًا لكل صفحة، فاحتفظ بواحد لكل صفحة ومرّر PAGE_ID وPAGE_TOKEN المطابقين؛ تُحتسب الاستدعاءات بـ token الصفحة على حد المعدل الخاص بتلك الصفحة.
من أين يأتي PSID الخاص برد Messenger؟
من webhook الرسائل: إن sender.id في كل حدث رسالة هو معرّف الشخص المحدد بالنطاق الخاص بالصفحة، وهو فريد لذلك الشخص وتلك الصفحة. أما معرّفات المستخدمين من Facebook Login فهي محددة بالتطبيق ولا تعمل مع Messenger Platform.
كم تكلّف easyCoexistence لصفحة Facebook؟
تُحتسب كل صفحة متصلة اتصالًا واحدًا، بسعر من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا حسب عددها، وأول 3 أيام مجانية؛ وأدوات MCP مشمولة.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في