Πώς να εισάγετε το ιστορικό συνομιλιών και τις επαφές της εφαρμογής WhatsApp Business μέσω του API
Ένας αριθμός WhatsApp Business app που συνδέεται μέσω Coexistence μπορεί να στείλει στο API, μία φορά και εντός 24 ωρών από την ένταξη, τις υπάρχουσες επαφές του και έως 180 ημέρες συνομιλιών ένα προς ένα. Οι επαφές φτάνουν ως webhooks smb_app_state_sync και οι συνομιλίες ως webhooks history, σε τμήματα ταξινομημένα κατά metadata.chunk_order. Το metadata.progress στο 100 σημαίνει ότι η εισαγωγή ολοκληρώθηκε. Η επιχείρηση επιλέγει στην εφαρμογή αν θα μοιραστεί τις συνομιλίες.
Η easyCoexistence συνδέει τους αριθμούς της εφαρμογής WhatsApp Business των πελατών σας μέσω Coexistence και ζητά από τη Meta τις επαφές και το ιστορικό συνομιλιών τους τη στιγμή που το webhook σας είναι έτοιμο.
Πόσο πίσω φτάνουν τα webhooks ιστορικού, μετρώντας από τη στιγμή που η επιχείρηση εντάχθηκε στο Cloud API.
Χρόνος μετά την ένταξη εντός του οποίου πρέπει να συγχρονιστούν οι επαφές και το ιστορικό μηνυμάτων μιας επιχείρησης.
Κωδικός σφάλματος στο webhook ιστορικού όταν η επιχείρηση έχει απενεργοποιήσει την κοινοποίηση ιστορικού στην εφαρμογή WhatsApp Business.
Πόσο συχνά μπορεί να εκτελείται κάθε συγχρονισμός. Για επανάληψη, ο πελάτης πρέπει να αποσυνδεθεί και να ολοκληρώσει ξανά το Embedded Signup.
Η τιμή progress που σημαίνει ότι ο συγχρονισμός ιστορικού ολοκληρώθηκε.
Πώς ξεκινά η εισαγωγή;
Με ένα webhook προορισμού στον αριθμό. Όταν η σύνδεση γίνεται με 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 με την αιτία.
Τι περιέχουν τα webhooks επαφών;
Πεδίο smb_app_state_sync, με πίνακα state_sync στην τιμή. Κάθε στοιχείο έχει type contact, ένα αντικείμενο contact με full_name, first_name και phone_number, μια ενέργεια add ή remove, και metadata.timestamp. Τα ονόματα παραλείπονται στο remove. Η Meta συνεχίζει να στέλνει αυτά τα webhooks μετά την εισαγωγή όποτε η επιχείρηση προσθέτει, επεξεργάζεται ή αφαιρεί επαφή στην εφαρμογή WhatsApp Business, ώστε το βιβλίο διευθύνσεών σας να συμβαδίζει με το τηλέφωνο.
Τι περιέχουν τα webhooks ιστορικού;
Πεδίο history, με πίνακα history στην τιμή. Κάθε στοιχείο έχει metadata, με phase, chunk_order και progress, και threads, ένα ανά πελάτη. Το id του thread είναι ο αριθμός του πελάτη, και το messages καταγράφει εκείνη τη συνομιλία ένα προς ένα, εισερχόμενα και εξερχόμενα, με το from να δείχνει ποια πλευρά έστειλε κάθε μήνυμα. Ένα μήνυμα φέρει id, timestamp, type, το περιεχόμενό του κάτω από το όνομα του τύπου, και history_context.status, όπως READ ή DELIVERED. Οι ομαδικές συνομιλίες δεν περιλαμβάνονται.
{
"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" }
}
]
}
]
}
]
}
}
]
}
]
}Πώς εισάγονται τα μηνύματα πολυμέσων;
Αρχικά ως placeholders. Ένα μήνυμα πολυμέσων έρχεται με type media_placeholder, χωρίς περιεχόμενο και χωρίς media ID. Στη συνέχεια η Meta στέλνει ξεχωριστά webhooks ιστορικού με τα media ID, αλλά μόνο για πολυμέσα που στάλθηκαν εντός 14 ημερών από την ένταξη. Ανακτήστε αυτά τα αρχεία από τη Meta με το token του πελάτη. Τα πολυμέσα παλαιότερα από αυτό μένουν placeholder, οπότε εμφανίστε τα ως συνημμένο που δεν είναι διαθέσιμο, αντί να αφήνετε κενό στη συνομιλία.
Με ποια σειρά φτάνουν τα τμήματα και πότε ολοκληρώνεται η εισαγωγή;
Όχι κατ' ανάγκη με τη σειρά. Η Meta χωρίζει τις συνομιλίες σε τρεις φάσεις, από τη νεότερη προς την παλαιότερη: η φάση 0 είναι η ημέρα πριν την ένταξη, η φάση 1 φτάνει έως την ημέρα 90 και η φάση 2 έως την ημέρα 180. Τα τμήματα μπορεί να φτάσουν εκτός ακολουθίας, οπότε ταξινομήστε τα κατά metadata.chunk_order. Το metadata.progress είναι το ποσοστό του συνολικού συγχρονισμού, και το 100 σημαίνει ότι ολοκληρώθηκε. Ο αριθμός φάσης από μόνος του δεν δείχνει ότι μια φάση τελείωσε.
Τι γίνεται αν η επιχείρηση αρνηθεί να μοιραστεί τις συνομιλίες;
Κατά τη σύνδεση, η εφαρμογή WhatsApp Business ρωτά την επιχείρηση αν θα μοιραστεί το ιστορικό συνομιλιών της. Η άρνηση φτάνει ως webhook ιστορικού χωρίς μηνύματα και με πίνακα errors, του οποίου ο κωδικός είναι 2593109, με τίτλο «History sync is turned off by the business from the WhatsApp Business App». Οι επαφές εξακολουθούν να φτάνουν, και τα ζωντανά μηνύματα ρέουν κανονικά από τη στιγμή που συνδέθηκε ο αριθμός.
Μπορεί να εκτελεστεί ξανά η εισαγωγή;
Όχι στην ίδια σύνδεση. Η Meta επιτρέπει κάθε συγχρονισμό μία φορά, εντός 24 ωρών από την ένταξη, και δεν μπορεί να επαναληφθεί. Για να τρέξει ξανά, ο πελάτης πρέπει να αποσυνδέσει τον αριθμό και να τον συνδέσει ξανά, πράξη που μετράει ως νέα ένταξη. Αν ο προορισμός σας είναι ακόμα αποθηκευμένος, η easyCoexistence ζητά ξανά την εισαγωγή, οπότε αφαιρέστε τα διπλότυπα με βάση το id κάθε μηνύματος. Αυτό ισχύει και για αριθμό που επιστρέφει μετά τον κανόνα των 14 ημερών.
Τι πρέπει να είναι έτοιμο πριν στείλετε τον σύνδεσμο σύνδεσης;
Το endpoint σας, σε λειτουργία και απαντώντας. Η Meta ελέγχει το URL με τη χειραψία GET της όταν εφαρμόζεται ο προορισμός, και η εισαγωγή ζητείται μία φορά, αμέσως μετά. Αν η χειραψία αποτύχει, ο αριθμός συνδέεται αλλά χωρίς προορισμό, το last_error της συνεδρίας εξηγεί το λόγο, και δεν εισάγεται τίποτα εκτός αν διορθώσετε το endpoint και το ορίσετε με PUT /connections/{id}/webhook μέσα στις 24 ώρες. Αριθμός χωρίς webhook_url δεν παίρνει καθόλου εισαγωγή, επειδή το περιεχόμενο που στέλνεται στη easyCoexistence απορρίπτεται.
Πώς να το ρυθμίσετε
- 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.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
Συνηθισμένα λάθη
- Απόρριψη μεγάλων τμημάτων ιστορικού. Τα payloads της Meta μπορεί να φτάσουν τα 3 MB, ενώ το Express αναλύει JSON μόνο έως 100 KB από προεπιλογή. Αυξήστε το όριο, αλλιώς τα τμήματα αποτυγχάνουν και η Meta συνεχίζει να τα ξαναστέλνει.
- Επεξεργασία τμημάτων με βάση τη σειρά άφιξης. Μπορεί να φτάσουν εκτός ακολουθίας, οπότε ταξινομήστε κατά metadata.chunk_order και περιμένετε progress 100 πριν δηλώσετε την εισαγωγή ολοκληρωμένη.
- Εισαγωγή ιστορικού χωρίς αφαίρεση διπλοτύπων. Τα ζωντανά μηνύματα μπορεί να επικαλύπτονται με την εισαγωγή, και μια επανασύνδεση την εκτελεί ξανά, οπότε χρησιμοποιήστε το id κάθε μηνύματος ως κλειδί.
- Αποστολή του συνδέσμου σύνδεσης πριν το endpoint απαντήσει στη χειραψία της Meta. Τότε ο προορισμός δεν εφαρμόζεται, και αν δεν τον ορίσετε μέσα σε 24 ώρες, το ιστορικό του αριθμού δεν εισάγεται ποτέ.
Έτσι το ιστορικό πηγαίνει κατευθείαν στο endpoint σας, χωρίς αποθήκευση στη διαδρομή, και κάθε αριθμός παρακολουθείται 24/7. Από US$ 9 έως US$ 0,75 ανά σύνδεση ανά μήνα, με μείωση όσο προσθέτετε συνδέσεις, και οι πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Πόσο πίσω φτάνει η εισαγωγή του ιστορικού συνομιλιών WhatsApp;
Έως 180 ημέρες πριν ο αριθμός ενταχθεί στο Cloud API, καλύπτοντας συνομιλίες ένα προς ένα και προς τις δύο κατευθύνσεις.
Εισάγονται ομαδικές συνομιλίες;
Όχι. Η Meta δεν περιλαμβάνει μηνύματα που ανήκουν σε ομαδική συνομιλία.
Θα φτάσουν στο webhook μου οι παλιές συνομιλίες WhatsApp ενός πελάτη;
Ναι, έως 180 ημέρες συνομιλιών ένα προς ένα, που στέλνονται μία φορά εντός 24 ωρών από την ένταξη, αν η επιχείρηση επιλέξει στην εφαρμογή να τις μοιραστεί.
Η easyCoexistence κρατά αντίγραφο των εισαχθέντων συνομιλιών;
Όχι. Η Meta στέλνει το ιστορικό κατευθείαν στο webhook_url σας, όπως τα ζωντανά μηνύματα, και τίποτα δεν αποθηκεύεται στη διαδρομή.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις