تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

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.

caption

معامل text الخاص بصورة الصفحة، إذ يعلّم مرجع الصور لدى Meta الحقل message بأنه مهجور هناك.

X-Business-Use-Case-Usage

ترويسة استجابة يحدد حقل estimated_time_to_regain_access فيها عدد الدقائق حتى تعود الاستدعاءات المقيّدة للعمل.

RESPONSE

قيمة messaging_type للرد على رسالة تلقّتها الصفحة، ضمن نافذة 24 ساعة.

recipient.comment_id

كيف يوجّه الرد الخاص إلى الشخص الذي علّق، عبر نقطة النهاية (endpoint) /{page-id}/messages نفسها.

ما الذي تحتاجه الأمثلة قبل تشغيلها؟

معرّف الصفحة (Page ID) ورمز الوصول token الخاص بتلك الصفحة، ويُقرأ من /me/accounts باستخدام token المستخدم طويل الأمد، إضافةً إلى Python 3 مع مكتبة requests، أو Node.js 18 أو أحدث، الذي لا تحتاج دالة fetch المدمجة فيه إلى أي حزمة. كل مهمة تحتاج أيضًا إلى صلاحيتها على الـ token ومهمتها على الصفحة، وتستدعي الأمثلة Graph API v26.0:

Publish a post or photoPOST /{page-id}/feed and /{page-id}/photos: pages_manage_posts, CREATE_CONTENT
Read and reply to comments/{post-id}/comments and /{comment-id}/comments: pages_manage_engagement, MODERATE
Reply in MessengerPOST /{page-id}/messages: pages_messaging, MESSAGING
Read insightsGET /{page-id}/insights: read_insights, pages_read_engagement, ANALYZE
Check a webhookX-Hub-Signature-256, with the app secret and no token

كيف تنشر منشورًا وصورة في Python؟

بدالة مساعدة واحدة تعيد استخدامها الأمثلة اللاحقة: تضيف graph() رمز الصفحة، وترسل معاملات GET في سلسلة الاستعلام وحقول POST بصيغة JSON كما تفعل أمثلة Meta نفسها، وتحوّل كائن الخطأ من Meta إلى GraphError يحمل code وerror_subcode. تنتظر وتعيد المحاولة فقط لرموز الأخطاء المؤقتة ورموز تجاوز المعدل، للمدة التي تطلبها الترويسة X-Business-Use-Case-Usage متى وردت، وتطلق الأخطاء الأخرى فورًا.

Python: graph(), then a post and a photo
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: graph(), then a post and a photo
// 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 إلى صفحات أقدم.

Python: read a post's comments and reply to the questions
# 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 أدناه. احتفظ بمعرّفات التعليقات التي رددت عليها حتى لا يرد إعادة التشغيل مرتين.

Node.js: read a post's comments and reply to the questions
// 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 أيام.

Python: a Messenger reply and a private reply
# 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 ساعة المعتادة بمجرد أن يكتب الشخص ردًا.

Node.js: a Messenger reply and a private reply
// 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 ردود الفعل والتعليقات والمشاركات.

Python: four Page metrics for the last 28 days
# 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.

Node.js: four Page metrics for the last 28 days
// 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.

Python: check X-Hub-Signature-256
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 التي تسبق أي حدث.

Node.js: check X-Hub-Signature-256
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() المحاولة للرموز المؤقتة ورموز تجاوز المعدل، وتطلق الباقي ليتعامل معه المستدعي:

190, 102The token was refused, and the subcode says why. A new sign-in is the fix
10, 200 to 299A permission was not granted or was removed. Grant it again
4, 17, 32, 613An app, user or Page rate limit. Stop, wait, then resume gradually
80001Page calls made with a Page token are throttled; the header gives the minutes
368Blocked for policy violations. Wait, and review what was being sent
100An invalid parameter. Fix the request before sending it again
551The person is not available on Messenger. Do not retry
1, 2A temporary issue on Meta's side. Wait and retry

كيف تشغّل المهام نفسها عبر easyCoexistence؟

كأدوات MCP يستدعيها Claude أو ChatGPT أو وكيلك الخاص على صفحة متصلة، ويحتفظ easyCoexistence بـ token الصفحة. لا تُسلَّم رموز الصفحات أبداً، لذا تعمل الأمثلة أعلاه برمز من تطبيق Meta الخاص بك؛ وتعيد get_social_credentials معرّف الصفحة وقاعدة Graph API. أداة كل مهمة:

Publishpublish_facebook_post with message, link, image_url or video_url, now or at scheduled_at
Commentslist_social_comments, then reply_to_comment; private set to true sends the one Messenger message
Messengersend_social_dm, with recipient_id set to the sender's ID from the forwarded event
Insightsget_social_insights with metrics and a period, or object_id for one post
Eventsset_social_webhook_destination; each forward carries X-EC-Signature, made with the Page's own secret

الأخطاء الشائعة

  • استدعاء endpoints الخاصة بالصفحة برمز المستخدم. معظمها يتوقع token الصفحة نفسه، والاستدعاءات بـ token المستخدم أو التطبيق تُحتسب على حدود المعدل الخاصة بالمستخدم أو التطبيق بدلًا من حدود الصفحة.
  • نشر النص نفسه مرتين متتاليتين. ترفض Meta المنشورات المتطابقة المتتالية بالخطأ 506، لذا على مهمة تُعاد تشغيلها أن تغيّر المحتوى أو تتخطى المنشور.
  • جمع المشاهدين الفريدين اليوميين. يحسب page_total_media_view_unique المشاهدين الفريدين في كل فترة، فلا تُجمع القيم اليومية لتعطي شهرًا؛ اطلب period بالقيمة days_28 بدلًا من ذلك.
  • إرسال token الصفحة إلى متصفح أو تطبيق. يجب أن تعمل هذه الاستدعاءات على الخادم، حيث يبقى token بعيدًا عن متناول أي شخص يقرأ العميل.
إنجاز ذلك باستخدام EasyCoexistence

من 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 مشمولة.

تابع القراءة

دليل Facebook Pages API لعام 2026: من تطبيقك إلى أول منشورمسار Facebook Pages API لعام 2026 خطوة بخطوة: تطبيق Meta، وFacebook Login for Business، والأذونات، ورمز الصفحة، وأول منشور، وMessenger.التحقق من خطاف الويب (webhook) في Facebook: hub.challenge و X-Hub-Signature-256التحقق من webhook على Facebook: إعادة hub.challenge عند تطابق hub.verify_token، ثم فحص X-Hub-Signature-256 لكل حدث بمفتاح App Secret الخاص بالتطبيق.مقاييس Facebook Page Insights في 2026: ما يعمل وما أوقفته Metaمقاييس Facebook Page Insights العاملة حتى أواخر 2026 والمُوقفة من Meta مع تواريخ الإيقاف، مثل page_impressions وpage_fans ومقاييس الوصول وغيرها.وسوم رسائل Messenger في 2026: ما الذي يمكن لصفحة Facebook إرساله بعد نافذة الـ24 ساعةما يمكن لصفحة Facebook إرساله بعد نافذة الـ24 ساعة في Messenger لعام 2026: HUMAN_AGENT وCUSTOMER_FEEDBACK والوسوم الثلاثة المتقاعدة وبدائلها.لماذا يتوقف اتصال صفحة Facebook API (واجهة برمجة التطبيقات) عن العمل، وكيف تُبقيه نشطاًأسباب توقف رمز الوصول (token) أو خطاف الويب (webhook) في صفحة Facebook، والخطأ الذي يعيده كل سبب، وكيفية اكتشافه مبكراً وإعادة ربط الصفحة.تغييرات Facebook Graph API في 2026: ما الذي توقف عن العمل وما الذي ينبغي فعلهتغييرات Facebook Graph API في 2026 من الأحدث إلى الأقدم: الإصدار v26.0، والإصدارات المتوقفة، وتغييرات البروتوكول، وعلامات الرسائل المحذوفة، وحل كل تغيير.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في