Φτιάξτε έναν πράκτορα WhatsApp με το Vercel AI SDK

Πώς λαμβάνει το route handler τα μηνύματα WhatsApp;

Με δύο μεθόδους στην ίδια διαδρομή, η οποία ορίζεται ως προορισμός του webhook του αριθμού, με ένα μακρύ τυχαίο μυστικό μέσα στο path.

Το GET απαντά στην επαλήθευση της Meta. Διαβάστε τα hub.mode, hub.verify_token και hub.challenge από το query, συγκρίνετε το token και επιστρέψτε το challenge ως απλό κείμενο. Το κλασικό λάθος είναι να το επιστρέψετε μέσω βοηθητικής συνάρτησης JSON: το σώμα φτάνει με εισαγωγικά γύρω του και η Meta δεν ξεκινά ποτέ να παραδίδει.

Το POST λαμβάνει τα γεγονότα. Επιστρέψτε 200 γρήγορα και καλέστε το μοντέλο μετά, επειδή η Meta επαναλαμβάνει τις αργές αποκρίσεις και ένα cold start που εκτελεί το μοντέλο στην ίδια ροή μπορεί να απαντήσει δύο φορές στο ίδιο μήνυμα. Σε πλατφόρμες που τερματίζουν τη συνάρτηση μόλις σταλεί η απόκριση, αναθέστε την εργασία σε μια ουρά ή στον μηχανισμό της πλατφόρμας για εργασία μετά την απόκριση.

Το μυστικό στο path είναι η αυθεντικοποίηση. Η Meta υπογράφει κάθε παράδοση με το app secret του Tech Provider, οπότε η κεφαλίδα X-Hub-Signature-256 δεν μπορεί να ελεγχθεί από τη δική σας πλευρά.

Πώς φορτώνει το AI SDK τα εργαλεία του WhatsApp;

Με το createMCPClient από το @ai-sdk/mcp και το μεταφορικό HTTP, το οποίο συνιστά η τεκμηρίωση του AI SDK για παραγωγή. Το μεταφορικό δέχεται το URL του server και έναν authProvider, και το OAuth μέσω authProvider είναι ο τρόπος εξουσιοδότησης του MCP server του EasyCoexistence: δημοσιεύει μεταδεδομένα OAuth, υποστηρίζει δυναμική εγγραφή client και PKCE, και εκδίδει δικά του tokens μετά από μια σύνδεση. Δεν υπάρχει κλειδί API για να μπει σε κεφαλίδα.

Τα εργαλεία του client μπαίνουν κατευθείαν στο generateText ή στο streamText. Το μοντέλο βλέπει τότε τα list_numbers, send_message, send_template, get_number_health και τα υπόλοιπα, με περιγραφές που δηλώνουν το παράθυρο των 24 ωρών. Κλείστε τον client όταν τελειώσει η κλήση, στο callback onEnd για ένα stream ή σε ένα μπλοκ finally σε άλλη περίπτωση, όπως ζητά η τεκμηρίωση του AI SDK.

Χρησιμοποιήστε το εκεί όπου το μοντέλο πρέπει να αποφασίζει. Για την απάντηση στο μήνυμα που μόλις έφτασε, μια άμεση κλήση του Cloud API από το handler είναι συντομότερη.

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://easycoexistence.com/api/mcp",
    authProvider, // your OAuthClientProvider implementation
  },
});

try {
  const tools = await mcp.tools();
  // pass tools to generateText({ model, tools, prompt })
} finally {
  await mcp.close();
}

Τι αλλάζει επειδή ο αριθμός είναι στο Coexistence;

Δύο πράγματα που πρέπει να γνωρίζει ο κώδικας. Πρώτον, ένας άνθρωπος μπορεί να βρίσκεται ήδη στη συνομιλία. Η εφαρμογή WhatsApp Business συνεχίζει να λειτουργεί στον αριθμό και κάθε απάντηση που πληκτρολογείται στο κινητό φτάνει στη διαδρομή ως γεγονός echo. Ένα handler που θέτει σε παύση το μοντέλο για μια επαφή μετά από ένα echo το εμποδίζει να απαντήσει πάνω από έναν άνθρωπο.

Δεύτερον, η αποστολή έχει σταθερό όριο 20 μηνυμάτων ανά δευτερόλεπτο για τον αριθμό. Ένας συνομιλιακός πράκτορας δεν πλησιάζει ποτέ αυτό το όριο, αλλά ένας βρόχος μαζικής αποστολής γραμμένος με Promise.all πάνω σε λίστα επαφών θα το πλησιάσει, οπότε στείλτε τα σε παρτίδες.

Τα υπόλοιπα είναι το συνηθισμένο Cloud API. Μέσα σε 24 ώρες από το τελευταίο μήνυμα του πελάτη επιτρέπεται το ελεύθερο κείμενο. Μετά από αυτό περνά μόνο ένα εγκεκριμένο template, ενώ το ελεύθερο κείμενο επιστρέφει το σφάλμα 131047 χωρίς ο πελάτης να δει τίποτα.

Συνηθισμένα λάθη

• Επιστροφή του challenge με βοηθητική συνάρτηση απόκρισης JSON. Τα εισαγωγικά γύρω του αποτυγχάνουν στον έλεγχο της Meta.
• Εκτέλεση του generateText πριν από την απόκριση στη Meta. Σε cold start η επανάληψη παράγει δεύτερη απάντηση.
• Παράλειψη κλεισίματος του MCP client. Κάθε αίτημα αφήνει μια σύνδεση ανοιχτή μέχρι να την τερματίσει η πλατφόρμα.

Συχνές ερωτήσεις

Συνεχίστε την ανάγνωση