Membangun agen WhatsApp dengan Vercel AI SDK

Bagaimana route handler menerima pesan WhatsApp?

Dengan dua method pada satu route, yang ditetapkan sebagai tujuan webhook nomor dengan secret acak yang panjang di path.

GET menjawab verifikasi dari Meta. Baca hub.mode, hub.verify_token, dan hub.challenge dari query, cocokkan token, lalu kembalikan challenge sebagai teks biasa. Mengembalikannya lewat helper JSON adalah kesalahan klasik: isinya tiba dengan tanda kutip di sekelilingnya dan Meta tidak pernah mulai mengirim.

POST menerima event. Kembalikan 200 dengan cepat dan jalankan panggilan model sesudahnya, karena Meta mencoba kembali pengiriman yang lambat dan cold start yang menjalankan model secara inline bisa menjawab pesan yang sama dua kali. Pada platform yang menghentikan fungsi begitu respons dikirim, serahkan pekerjaannya ke antrean atau ke mekanisme platform untuk pekerjaan setelah respons.

Secret di path adalah autentikasinya. Meta menandatangani setiap pengiriman dengan app secret milik Tech Provider, jadi header X-Hub-Signature-256 tidak bisa diperiksa di sisi Anda.

Bagaimana AI SDK memuat alat WhatsApp?

Dengan createMCPClient dari @ai-sdk/mcp dan transport HTTP, yang direkomendasikan dokumentasi AI SDK untuk produksi. Transport menerima URL server dan sebuah authProvider, dan OAuth lewat authProvider adalah cara server MCP EasyCoexistence diotorisasi: server ini menerbitkan metadata OAuth, mendukung dynamic client registration dan PKCE, lalu menerbitkan token sendiri setelah login. Tidak ada kunci API yang perlu ditaruh di header.

Alat milik klien langsung masuk ke generateText atau streamText. Model lalu melihat list_numbers, send_message, send_template, get_number_health, dan lainnya, dengan deskripsi yang menyebut jendela layanan pelanggan 24 jam. Tutup klien setelah panggilan selesai, di callback onEnd untuk stream atau di blok finally untuk selainnya, sesuai permintaan dokumentasi AI SDK.

Pakai ini saat model yang perlu memutuskan. Untuk membalas pesan yang baru masuk, panggilan Cloud API langsung dari handler lebih singkat.

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();
}

Apa yang berubah karena nomor memakai Coexistence?

Ada dua hal yang perlu diketahui kode Anda. Pertama, seseorang mungkin sudah ada dalam percakapan. Aplikasi WhatsApp Business tetap berfungsi pada nomor itu, dan setiap balasan yang diketik di ponsel tiba di route sebagai event echo. Handler yang menjeda model untuk sebuah kontak setelah echo mencegahnya menjawab di atas seseorang.

Kedua, pengiriman dibatasi tetap 20 pesan per detik untuk nomor tersebut. Agen percakapan tidak pernah mendekatinya, tetapi loop broadcast yang ditulis dengan Promise.all di atas daftar kontak akan mencapainya, jadi bagi dalam batch.

Selebihnya adalah Cloud API biasa. Dalam 24 jam sejak pesan terakhir pelanggan, teks bebas diizinkan. Setelah itu, hanya template yang disetujui yang bisa terkirim, dan teks bebas mengembalikan kesalahan 131047 tanpa pelanggan melihat apa pun.

Kesalahan umum

• Mengembalikan challenge dengan helper respons JSON. Tanda kutip di sekelilingnya membuat pemeriksaan Meta gagal.
• Menjalankan generateText sebelum menjawab Meta. Pada cold start, pengiriman ulang menghasilkan jawaban kedua.
• Lupa menutup klien MCP. Setiap permintaan meninggalkan satu koneksi terbuka sampai platform menghentikannya.

Pertanyaan yang sering diajukan

Lanjut membaca