התחברותהתחילו תקופת ניסיון
easyCoexistence ממשקי API רשמיים

איך מייבאים את היסטוריית הצ'אטים ואנשי הקשר של אפליקציית WhatsApp Business דרך ה-API

מספר WhatsApp Business המחובר דרך Coexistence יכול לשלוח ל-API את אנשי הקשר הקיימים שלו ועד 180 ימים של צ'אטים אחד על אחד, פעם אחת בלבד, תוך 24 שעות מההטמעה. אנשי הקשר מגיעים כוובהוקים מסוג smb_app_state_sync, והצ'אטים כוובהוקים של היסטוריה, בחלקים הממוינים לפי metadata.chunk_order. הייבוא הושלם כאשר הערך של metadata.progress הוא 100. העסק בוחר באפליקציה אם לשתף את הצ'אטים.

easyCoexistence מחבר את מספרי WhatsApp Business של הלקוחות שלכם דרך Coexistence ומבקש מ-Meta את אנשי הקשר ואת היסטוריית הצ'אטים ברגע שהוובהוק שלכם במקום.

180 days

עד כמה אחורה מגיעים וובהוקים של היסטוריה, החל מהרגע שבו העסק הוטמע ל-Cloud API.

24 hours

חלון הזמן לאחר ההטמעה שבו חייבים לסנכרן את אנשי הקשר והיסטוריית ההודעות של העסק.

2593109

קוד השגיאה בוובהוק של ההיסטוריה כאשר העסק כיבה את שיתוף ההיסטוריה באפליקציית WhatsApp Business.

Once

כל כמה זמן יכול כל סנכרון לרוץ; הרצה חוזרת מחייבת שהלקוח ינתק את המספר ויבצע שוב את Embedded Signup.

100

ערך progress שמסמן שסנכרון היסטוריה הושלם.

איך הייבוא מתחיל?

עם יעד וובהוק על המספר. כאשר המספר מתחבר עם webhook_url שכבר מוגדר בסשן החיבור, או כאשר מגדירים אחד עם PUT /connections/{id}/webhook תוך 24 שעות מהחיבור, easyCoexistence מבקש מ-Meta את הנתונים פעם אחת: POST /{phone_number_id}/smb_app_data עם sync_type smb_app_state_sync לאנשי הקשר, ואחר כך history לצ'אטים, בסדר המתועד על ידי Meta. יומן האירועים של המספר רושם history_sync_requested עם ערכי request_id של Meta לצורך תמיכה, או history_sync_failed עם הסיבה.

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

מה נושאים וובהוקי אנשי הקשר?

שדה smb_app_state_sync, עם מערך state_sync בתוך value. כל פריט הוא מסוג contact, ובו אובייקט contact שמכיל את full_name, את first_name ואת phone_number; פעולה מסוג add או remove; וגם metadata.timestamp. בפעולת remove לא נשלחים השמות. Meta ממשיכה לשלוח את הוובהוקים האלה אחרי הייבוא בכל פעם שהעסק מוסיף, עורך או מסיר איש קשר באפליקציית WhatsApp Business, כך שספר הכתובות שלכם נשאר מסונכרן עם הטלפון.

מה נושאים וובהוקי ההיסטוריה?

שדה history, עם מערך history בתוך value. כל פריט מכיל metadata עם phase, chunk_order וגם progress, ומערך threads, אחד לכל לקוח. השדה id של thread הוא מספר הלקוח, והשדה messages מכיל את השיחה האחד על אחד, נכנסת ויוצאת, כאשר השדה from מציין איזה צד שלח כל הודעה. כל הודעה כוללת id, timestamp, type, את התוכן תחת השם של הסוג, וגם history_context.status, למשל READ או DELIVERED. קבוצות אינן נכללות.

A history webhook, as Meta sends it
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "history",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
            "history": [
              {
                "metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
                "threads": [
                  {
                    "id": "<CUSTOMER_NUMBER>",
                    "messages": [
                      {
                        "from": "<CUSTOMER_NUMBER>",
                        "id": "wamid.<ID>",
                        "timestamp": "1790726400",
                        "type": "text",
                        "text": { "body": "<MESSAGE_TEXT>" },
                        "history_context": { "status": "READ" }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

איך הודעות מדיה מיובאות?

תחילה כמציינות מקום. הודעת מדיה מגיעה עם הערך media_placeholder בשדה type, בלי תוכן ובלי מזהה מדיה. אחר כך Meta שולחת וובהוקים של היסטוריה נפרדים הנושאים את מזהי המדיה, אך רק למדיה שנשלחה עד 14 ימים מההטמעה. את הקבצים האלה מושכים מ-Meta עם האסימון של הלקוח. מדיה ישנה יותר נשארת מציין מקום, ולכן מציגים אותה כקובץ מצורף שאינו זמין, במקום להשאיר פער בשרשור.

באיזה סדר מגיעים החלקים, ומתי הייבוא נגמר?

לא בהכרח לפי הסדר. Meta מחלקת את הצ'אטים לשלושה שלבים, מהחדש לישן: phase 0 הוא היום שלפני ההטמעה, phase 1 מגיע עד יום 90, ואילו phase 2 מגיע עד יום 180. חלקים יכולים להגיע מחוץ לרצף, ולכן מיינו אותם לפי השדה metadata.chunk_order. השדה metadata.progress מציין את אחוז הסנכרון כולו, וערך 100 פירושו שהסנכרון הושלם. מספר השלב לבדו לא מעיד שהשלב הסתיים.

מה קורה אם העסק מסרב לשתף צ'אטים?

במהלך החיבור, אפליקציית WhatsApp Business שואלת את העסק אם לשתף את היסטוריית הצ'אטים שלו. סירוב מגיע כוובהוק של היסטוריה בלי הודעות, עם המערך errors שהקוד בו הוא 2593109, שכותרתו History sync is turned off by the business from the WhatsApp Business App. אנשי הקשר עדיין מגיעים, והודעות חיות זורמות כרגיל מהרגע שהמספר חובר.

אפשר להריץ את הייבוא שוב?

לא באותו חיבור. Meta מאפשרת כל סנכרון פעם אחת, תוך 24 שעות מההטמעה, ואי אפשר להפעיל אותו מחדש. להרצה חוזרת הלקוח צריך לנתק את המספר ולחבר אותו מחדש, מה שנחשב להטמעה חדשה. כאשר היעד שלכם עדיין שמור, easyCoexistence מבקש שוב את הייבוא, ולכן יש לסנן כפילויות לפי השדה id של כל הודעה. זה כולל גם מספר שחוזר אחרי כלל 14 הימים.

מה צריך להיות מוכן לפני ששולחים את קישור החיבור?

נקודת הקצה שלכם חייבת להיות פעילה ולענות. Meta בודקת את הכתובת בלחיצת יד מסוג GET כשהיעד מיושם, והייבוא מתבקש פעם אחת, מיד אחר כך. אם לחיצת היד נכשלת, המספר עדיין מתחבר אבל בלי יעד, והשדה last_error בסשן מסביר למה. לא מיובא דבר, אלא אם תתקנו את נקודת הקצה ותגדירו אותה עם PUT /connections/{id}/webhook בתוך 24 השעות. מספר בלי webhook_url לא מקבל ייבוא כלל, כי תוכן שנשלח אל easyCoexistence נזרק.

איך מגדירים

  1. Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.

טעויות נפוצות

  • דחיית חלקי היסטוריה גדולים. המטענים של Meta יכולים להגיע ל-3 MB, בעוד Express מפענח את ה-JSON עד 100 KB בלבד כברירת מחדל. לכן העלו את המגבלה, אחרת החלקים נכשלים ו-Meta ממשיכה לנסות אותם שוב.
  • עיבוד חלקים לפי סדר ההגעה. הם יכולים להגיע מחוץ לרצף, לכן מיינו לפי השדה metadata.chunk_order וחכו שהערך של progress יהיה 100 לפני שמכריזים שהייבוא הושלם.
  • הכנסת היסטוריה בלי מניעת כפילויות. הודעות חיות יכולות לחפוף לייבוא, וחיבור מחדש מריץ אותו שוב. לכן יש לזהות כל הודעה לפי השדה id שלה.
  • שליחת קישור החיבור לפני שנקודת הקצה עונה ללחיצת היד של Meta. היעד אז לא מיושם, ואם לא תגדירו אותו תוך 24 שעות, היסטוריית המספר לא תיובא לעולם.
עושים את זה עם EasyCoexistence

כך ההיסטוריה עוברת ישירות לנקודת הקצה שלכם בלי שום אחסון בדרך, וכל מספר נמצא במעקב 24/7. US$ 9 עד US$ 0.75 לחיבור בחודש, יורד ככל שמוסיפים חיבורים, עם 3 הימים הראשונים בחינם.

שאלות נפוצות

כמה אחורה מגיע ייבוא היסטוריית הצ'אטים של WhatsApp?

עד 180 ימים לפני שהמספר הוטמע ל-Cloud API, וזה כולל צ'אטים אחד על אחד בשני הכיוונים.

האם מיובאים צ'אטים של קבוצות?

לא. Meta לא כוללת הודעות שהן חלק משיחת קבוצה.

האם צ'אטים ישנים של לקוח יגיעו לוובהוק שלי?

כן, עד 180 ימים של צ'אטים אחד על אחד, נשלחים פעם אחת תוך 24 שעות מההטמעה, אם העסק בחר באפליקציה לשתף אותם.

האם easyCoexistence שומר עותק של הצ'אטים המיובאים?

לא. Meta שולחת את ההיסטוריה ישירות אל webhook_url שלכם, בדומה להודעות חיות, ושום דבר לא נשמר בדרך.

המשיכו לקרוא

איך מקבלים בוובהוק (Webhook) את הודעות WhatsApp ואת התגובות ברשתות החברתיות של הלקוחות שלכםוובהוק לכל חיבור: הודעות WhatsApp ישירות מ-Meta, מאומתות בסוד בכתובת, ותגובות ו-DM מהרשתות החברתיות חתומות בכותרת X-EC-Signature.איך לדעת מתי חיבור של לקוח ב-WhatsApp או ברשת חברתית מתנתקאירועי connection.* ו-channel.*: ה-payload, סיבות כמו PRIMARY_INACTIVITY, חתימת X-EC-Signature וניסיונות חוזרים במשך כ-33 שעות.איך מקבלים את אסימוני ה-API של לקוחותיכם ב-WhatsApp, Instagram ו-TikTokמה קריאת פרטי הגישה מחזירה עבור מספר WhatsApp של לקוח ועבור כל חשבון רשת, שדה אחר שדה, וכיצד פועלים סיבוב האסימונים והשדה token_ready.וובהוק historyהשדה שמעביר פעם אחת את היסטוריית הצ׳אט במספר Coexistence: מה מגיע, מתי ולמה.וובהוק (Webhook) smb_app_state_syncסנכרון אנשי הקשר מאפליקציית WhatsApp Business מגיע בשדה הזה. מה הוא כולל ולמה הוא נפרד מהיסטוריית ההודעות.איך לחבר את WhatsApp ל-API בלי לאבד את השיחותחיבור מספר WhatsApp Business ל-Cloud API בלי לאבד שיחות. למה הן נשארות בטלפון ומה באמת מסתנכרן.

מחברים את הערוץ הראשון שלכם תוך שתי דקות.

בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.

  • 3 ימי ניסיון חינם
  • ביטול בכל עת
  • רק ממשקי API רשמיים
  • ניטור 24/7

נבדק ב-