إعلانات Click-to-WhatsApp

اعرف أي إعلان بدأ كل محادثة واتساب

عندما ينقر شخص على إعلان Click-to-WhatsApp أو منشور مُموَّل، تحمل رسالته الأولى بيانات الإعلان. يحفظها StartMessaging على جهة الاتصال الجديدة، ويعرضها في نظام إدارة العملاء، ويرسلها إلى أنظمتك عبر webhook، فلا يصل أي عميل من الإعلانات مجهول المصدر.

✦ تجربة مجانية لمدة 14 يوماً · رقم واتساب للأعمال الخاص بك · تُصدر Meta فواتير الرسائل مباشرةً

بيانات الإعلان تصل مع الرسالة الأولى

تُنشئ إعلاناتك وتدفع ثمنها في مدير إعلانات Meta. عندما ينقر عميل على أحدها ويرسل رسالته الأولى، يُرفق واتساب بيانات إحالة: نوع المصدر، ومعرّف الإعلان أو المنشور، ورابطه، والعنوان، ونص الإعلان، ومعرّف النقرة (ctwaClid). يقرأها StartMessaging لحظة وصول الرسالة إلى صندوق الوارد المشترك.

  • يعمل مع إعلانات Click-to-WhatsApp والمنشورات المُموَّلة
  • التقاط العنوان ونص الإعلان ومعرّف الإعلان أو المنشور ورابطه
  • الاحتفاظ بمعرّف النقرة (ctwaClid) لتقارير التحويل الخاصة بك
  • شارة “تنتهي نافذة الإعلان المجانية…” ما دامت نافذة Meta المجانية ومدتها 72 ساعة مفتوحة
اقرأ دليل النسب →
نسب العملاء المحتملين لإعلانات Click-to-WhatsApp

كل عميل من الإعلانات يصل إلى CRM مع إعلانه

تحصل جهة الاتصال التي أُنشئت من نقرة على إعلان على المصدر "إعلان Click-to-WhatsApp" وعلى بيانات الإعلان كحقول مخصصة: ctwa_source_type وctwa_source_id وctwa_source_url وctwa_headline وctwa_body وctwa_clid. افتح جهة الاتصال لترى بطاقة "من إعلان Click-to-WhatsApp" تعرض الإعلان الذي نقر عليه. تُعيَّن هذه الحقول مرة واحدة بواسطة تلك الرسالة الأولى. أما جهة الاتصال الموجودة مسبقًا فتحتفظ بمصدرها وحقولها الأصلية، وتظل بيانات الإحالة تصل عبر webhook ‏message.received.

  • تسجيل مصدر العميل كـ "إعلان Click-to-WhatsApp"
  • حفظ تفاصيل الإعلان كحقول مخصصة تُعيَّن مرة واحدة
  • يظهر في صفحة جهة الاتصال بجانب الوسوم والملاحظات
جهة اتصال أُنشئت من إعلان Click-to-WhatsApp في CRM
كيف يعمل

من النقر على الإعلان إلى عميل مؤهَّل

01

1. شغّل الإعلان في مدير إعلانات Meta

أنشئ إعلان Click-to-WhatsApp، أو موّل منشورًا بزر واتساب، يفتح محادثة مع الرقم الذي ربطته بـ StartMessaging.

02

2. ينقر العميل ويكتب

تصل رسالته الأولى إلى صندوق الوارد المشترك لفريقك مرفقةً ببيانات الإحالة من الإعلان.

03

3. تُنشأ جهة الاتصال مع بيانات الإعلان

تحصل جهة الاتصال الجديدة على المصدر ctwa_ad وحقول ctwa_* المخصصة. تستقبل أنظمتك بيانات الإحالة في message.received والمصدر في contact.created.

04

4. وجّه العميل المحتمل

يرحّب تدفق الشات بوت المرتبط بمشغّل الرسالة الأولى بكل محادثة جديدة، بما فيها النقرات على الإعلانات: اطرح أسئلة التأهيل، وأضف وسمًا، وانقل جهة الاتصال إلى مرحلة في مسار المبيعات، وعيّن موظفًا.

05

5. أبلغ عن التحويل بنفسك

عندما يشتري العميل، يرسل نظامك أنت معرّف ctwaClid المحفوظ إلى واجهة Conversions API من Meta، ولا يرسل StartMessaging التحويلات إلى Meta نيابةً عنك. ولنسب البيع إلى حملة في StartMessaging، أبلغ عنه عبر POST /api/v1/conversions في باقة Business.

أين تُحفظ بيانات الإعلان

إحالة واحدة وثلاثة أماكن لاستخدامها

قد يكون أي حقل من حقول الإحالة فارغًا عندما لا ترسله Meta.

بيانات الإعلان على جهة الاتصال (CRM) webhook ‏message.received REST API
نوع المصدر، معرّف الإعلان أو المنشور، الرابط ctwa_source_type, ctwa_source_id, ctwa_source_url referral.sourceType, sourceId, sourceUrl سمات جهة الاتصال في GET /api/v1/contacts
العنوان ونص الإعلان ctwa_headline وctwa_body (يُقتطع عند 500 حرف) referral.headline, referral.body سمات جهة الاتصال
معرّف النقرة ctwa_clid referral.ctwaClid سمات جهة الاتصال
مصدر العميل "إعلان Click-to-WhatsApp" source "ctwa_ad" في contact.created source: "ctwa_ad"
جهة اتصال موجودة تنقر على إعلان تحتفظ بمصدرها وحقولها ✓ تظل الإحالة تصل دون تغيير
نافذة نقطة الدخول المجانية (72 ساعة) شارة “تنتهي نافذة الإعلان المجانية…” على المحادثة freeEntryPointExpiresAt على المحادثة
Webhooks

اقرأ بيانات الإعلان من الرسالة الأولى

تحقّق من ترويسة X-SM-Signature، ثم احفظ referral.ctwaClid مع العميل المحتمل.

{
  "id": "evt_01JCA4M8ZP",
  "type": "message.received",
  "createdAt": "2026-10-07T09:15:04.000Z",
  "workspaceId": "ws_9f2c",
  "data": {
    "message": {
      "id": "msg_51c0",
      "conversationId": "conv_8e21",
      "contactId": "ct_4a7d",
      "from": "+919812345678",
      "type": "text",
      "text": "Hi, is the festive offer still on?",
      "media": null,
      "reply": null,
      "context": null,
      "form": null,
      "referral": {
        "sourceType": "ad",
        "sourceId": "120210000000000000",
        "sourceUrl": "https://fb.me/abc123",
        "headline": "Festive sale on silk sarees",
        "body": "Tap to chat with us on WhatsApp",
        "ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"
      },
      "timestamp": "2026-10-07T09:15:02.000Z"
    },
    "contact": {
      "id": "ct_4a7d",
      "phone": "+919812345678",
      "name": "Asha"
    }
  }
}
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
const SECRET = process.env.SM_WEBHOOK_SECRET; // the whole whsec_… string

function verify(rawBody, headers) {
  const ts = headers['x-sm-timestamp'];
  const sigs = headers['x-sm-signature'];
  if (!/^\d+$/.test(ts ?? '') || typeof sigs !== 'string') return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = createHmac('sha256', SECRET).update(`${ts}.`).update(rawBody).digest();
  return sigs.split(',').some((part) => {
    const m = /^v1=([0-9a-f]{64})$/.exec(part.trim());
    return m !== null && timingSafeEqual(Buffer.from(m[1], 'hex'), expected);
  });
}

app.post('/webhooks/startmessaging', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verify(req.body, req.headers)) return res.sendStatus(401);
  res.sendStatus(200); // answer within 5 seconds, then do the work

  const event = JSON.parse(req.body);
  if (event.type !== 'message.received') return;

  const { referral, from } = event.data.message;
  if (!referral) return; // not the first message from an ad

  // Any referral field can be null when Meta leaves it out.
  await saveAdLead({
    eventId: event.id, // delivered at least once: deduplicate on this
    phone: from,
    adId: referral.sourceId,
    headline: referral.headline,
    ctwaClid: referral.ctwaClid, // keep it for Meta's Conversions API
  });
  // When this lead converts, your own server sends ctwaClid to Meta's
  // Conversions API. StartMessaging does not send conversions to Meta.
});
import hmac, hashlib, json, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ['SM_WEBHOOK_SECRET'].encode()  # the whole whsec_… string

def verify(raw_body, ts, sigs):
    if not ts or not ts.isdigit() or not sigs:
        return False
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(SECRET, f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return any(
        hmac.compare_digest(part.strip()[3:], expected)
        for part in sigs.split(',') if part.strip().startswith('v1=')
    )

@app.post('/webhooks/startmessaging')
def startmessaging_webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get('X-SM-Timestamp'), request.headers.get('X-SM-Signature')):
        return '', 401
    event = json.loads(raw)
    if event['type'] == 'message.received':
        message = event['data']['message']
        referral = message.get('referral')
        if referral:  # first message from a Click-to-WhatsApp ad
            save_ad_lead(
                event_id=event['id'],  # deduplicate on this
                phone=message['from'],
                ad_id=referral.get('sourceId'),
                headline=referral.get('headline'),
                ctwa_clid=referral.get('ctwaClid'),  # for Meta's Conversions API
            )
    return '', 200
الأسئلة الشائعة

إعلانات Click-to-WhatsApp — الأسئلة الشائعة

هل أنشئ الإعلانات داخل StartMessaging؟

لا. تُنشئ إعلانات Click-to-WhatsApp وتستهدف جمهورها وتدفع ثمنها في مدير إعلانات Meta، أو تموّل منشورًا من صفحتك على فيسبوك أو حسابك على إنستغرام. وجّه الإعلان إلى رقم واتساب الذي ربطته بـ StartMessaging، وسيقرأ StartMessaging بيانات الإعلان من كل محادثة جديدة يبدؤها.

ما البيانات التي يلتقطها StartMessaging من الإعلان؟

كل ما ترسله Meta في بيانات الإحالة مع الرسالة الأولى: نوع المصدر، ومعرّف الإعلان أو المنشور، ورابطه، والعنوان، ونص الإعلان، ومعرّف النقرة (ctwaClid). قد يكون أي منها فارغًا عندما لا ترسله Meta. وتحفظها جهة الاتصال الجديدة في الحقول المخصصة ctwa_source_type وctwa_source_id وctwa_source_url وctwa_headline وctwa_body (يُقتطع عند 500 حرف) وctwa_clid.

ماذا يحدث عندما تنقر جهة اتصال موجودة على إعلان؟

تحتفظ جهة الاتصال بمصدرها وحقولها المخصصة الأصلية، إذ تُعيَّن مرة واحدة فقط بواسطة الرسالة التي أنشأتها. وتظل بيانات الإحالة تصل عبر webhook ‏message.received، ليتمكن نظامك من تسجيل النقرة الجديدة على الإعلان.

هل يرسل StartMessaging التحويلات إلى Conversions API من Meta؟

لا. يحتفظ StartMessaging بمعرّف النقرة (ctwaClid) على جهة الاتصال وفي الـ webhook. وعندما يتحول العميل المحتمل إلى عميل، يرسل خادمك أنت، أو أداة أتمتة تتحكم بها، معرّف ctwaClid إلى Conversions API من Meta. ولنسب عملية بيع إلى حملة في StartMessaging، تضيف باقة Business الطلب POST /api/v1/conversions: أبلغ عن البيع برقم هاتف العميل، فتُنسب إلى آخر حملة سُلّمت إليه ضمن نافذة التحويل لديك.

هل تحتسب Meta رسوماً على الرسائل في محادثة قادمة من إعلان؟

ليس داخل نافذة نقطة الدخول المجانية. عندما يراسلك عميل من إعلان Click-to-WhatsApp وتردّ في الوقت المناسب، تفتح Meta نافذة نقطة دخول مجانية مدتها 72 ساعة لا تحتسب خلالها أي رسوم على رسائل تلك المحادثة، بما فيها القوالب. ويعرض صندوق الوارد شارة “تنتهي نافذة الإعلان المجانية…” حتى ذلك الحين، وتعيد الواجهة البرمجية وقت انتهائها في الحقل freeEntryPointExpiresAt على المحادثة. ولا تحل هذه النافذة محل قاعدة الـ24 ساعة: بعد مرور 24 ساعة العميل تظل بحاجة إلى قالب معتمد. وبعد انتهائها تُطبَّق أسعار Meta المعتادة.

هل يمكنني الرد تلقائيًا على العملاء القادمين من الإعلانات؟

نعم. يبدأ تدفق الشات بوت المرتبط بمشغّل الرسالة الأولى مع أول رسالة من جهة الاتصال في المحادثة، لذا يرحّب بكل محادثة جديدة، بما فيها النقرات على الإعلانات. يمكنه طرح الأسئلة وإضافة الوسوم ونقل جهة الاتصال إلى مرحلة في مسار المبيعات وتحويل المحادثة إلى موظف. وتعمل الردود التلقائية بالكلمات المفتاحية أيضًا. ولأن العميل كتب أولًا، تكون نافذة الـ 24 ساعة مفتوحة ويمكنك الرد برسائل حرة. تدفقات الشات بوت متاحة في خطة Business وفي التجربة المجانية لمدة 14 يومًا، والردود التلقائية بالكلمات المفتاحية في خطتي Team وBusiness.

هل يمكنني إرسال العملاء القادمين من الإعلانات إلى نظام CRM أو جدول بيانات خاص بي؟

نعم. اشترك في message.received (تحمل بيانات الإحالة) وcontact.created (تحمل source "ctwa_ad")، أو زامن البيانات عبر GET /api/v1/contacts مع updatedSince، الذي يعيد مصدر كل جهة اتصال وسمات ctwa_* الخاصة بها. تعمل Zapier وMake وPabbly Connect عبر وحدات webhook وHTTP العامة لديها؛ ولا توجد بعد تطبيقات رسمية لـ StartMessaging في هذه المتاجر.

واجهة برمجة تطبيقات واتساب

حوّل النقرات على الإعلانات إلى عملاء محتملين متتبَّعين

تجربة مجانية لمدة 14 يومًا. اربط رقم واتساب للأعمال الخاص بك وشاهد الإعلان وراء كل محادثة جديدة.