Langsung ke konten utama
GOWA menyediakan endpoint Model Context Protocol dari proses yang sama dengan REST API. Semua klien MCP yang mendukung transport streamable HTTP dapat mengirim pesan, membaca chat, dan mengelola grup melaluinya.
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (default http://localhost:3000/mcp)
  • Aktif secara default. Nonaktifkan dengan MCP_ENABLED=false or --mcp-enabled=false.
  • Stateless: tidak ada handshake sesi yang perlu dipertahankan di antara pemanggilan.
Jika Anda memperbarui dari rilis lama, perintah mandiri ./whatsapp mcp dan endpoint SSE-nya pada port 8080 (/sse) sudah dihapus. Jalankan ./whatsapp rest dan arahkan klien ke /mcp. Kumpulan tool lama yang menyediakan satu tool untuk setiap operasi telah diganti dengan tool terpadu di bawah ini.

Hubungkan klien

/mcp dilindungi Basic Auth yang sama dengan REST API. Kirim header Authorization, serta X-Device-Id jika Anda menjalankan lebih dari satu perangkat:
YWRtaW46Y2hhbmdlbWU= adalah base64("admin:changeme"); buat nilai Anda sendiri dengan echo -n 'user:pass' | base64. Hilangkan Authorization jika Basic Auth tidak aktif, dan X-Device-Id jika hanya ada satu perangkat. Format konfigurasi bergantung pada klien. Jika klien hanya dapat menjalankan server stdio, gunakan perantara seperti mcp-remote.

Tool

GOWA menyediakan tujuh tool. Masing-masing menerima argumen type (untuk pengiriman) atau action (untuk semua tool lainnya) untuk memilih operasi. Catatan tentang argumen:
  • whatsapp_send selalu memerlukan type dan phone. Media dikirim hanya melalui URL (image_url, video_url, audio_url, file_url, sticker_url); MCP tidak dapat mengunggah file lokal. link memerlukan link dan caption; forward memerlukan message_id.
  • whatsapp_send menerima field jadwal (scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, occurrence_limit). Kelola hasilnya dengan whatsapp_schedule (get, pause, resume, dan cancel memerlukan schedule_id).
  • whatsapp_message memerlukan phone (chat) dan message_id; edit juga memerlukan message.
  • Pada GOWA main setelah v9.9.0, whatsapp_message dengan action: "edit" menerima media_type: "image" atau media_type: "document" untuk mengganti caption. Sesuaikan dengan jenis media asli dan hilangkan link. Lihat Edit caption.
  • whatsapp_chat: get_messages memerlukan chat_jid; archive memerlukan chat_jid dan archived.
  • whatsapp_app: login_code memerlukan phone.
Pengiriman tombol, permintaan lokasi, dan carousel yang bersifat eksperimental hanya tersedia melalui REST. Lihat pesan interaktif. Tool newsletter mendukung penemuan saluran, penghitung riwayat, dan langganan pembaruan langsung yang diperpanjang secara otomatis. Lihat newsletter. Pengunduhan URL media menerapkan pemeriksaan alamat publik yang sama dengan pengiriman REST dan terhubung langsung tanpa HTTP_PROXY atau HTTPS_PROXY. Pengunggahan file lokal memerlukan REST API. Klien MCP menampilkan skema input lengkap setiap tool. Endpoint HTTP menerima POST dan DELETE. Streaming GET SSE dinonaktifkan.

Pemilihan perangkat

Setiap pemanggilan menentukan perangkatnya dengan urutan berikut:
  1. Argumen device_id pada pemanggilan tool.
  2. Header X-Device-Id pada koneksi MCP.
  3. Satu-satunya perangkat terdaftar, jika hanya ada satu perangkat.
Jika tidak, pemanggilan gagal dengan device identification required: set the X-Device-Id header or pass device_id. Lihat Multi-perangkat.

Klien jarak jauh dengan OAuth

Klien yang dihosting, seperti konektor kustom Claude, tidak dapat menyertakan header Basic Auth. Untuk klien tersebut, GOWA dapat menjalankan server otorisasi OAuth 2.1 untuk /mcp. Fitur ini tidak aktif secara default.
Persyaratan dan perilaku:
  • APP_BASIC_AUTH harus diatur: halaman otorisasi menggunakan akun yang sama untuk login pengguna. Proses startup gagal tanpa pengaturan ini.
  • Issuer dan resource harus berupa URL HTTPS publik yang diakses klien, bukan alamat internal seperti http://gowa:3000.
  • Saat OAuth aktif, /mcp menerima token Bearer atau Basic Auth. Token tidak diterima pada rute REST atau UI.
  • Klien mendaftarkan dirinya sendiri (pendaftaran klien dinamis RFC 7591). Body pendaftaran dibatasi hingga 16 KiB dan setiap URI pengalihan hingga 2 KiB. Pendaftaran dibatasi hingga 40 per jam dan 1,000 klien tersimpan; klien yang tidak digunakan dihapus setelah 24 jam.
  • PKCE S256 wajib digunakan. Kode kedaluwarsa setelah 5 menit, token akses setelah 1 jam; refresh token dirotasi, dan penggunaan ulang token lama mencabut seluruh keluarga token. Hanya hash SHA-256 token yang disimpan, di MCP_OAUTH_DB_URI (default file:storages/oauth.db).
URI pengalihan harus sama persis dengan nilai yang didaftarkan. Klien native dapat menggunakan callback IP loopback HTTP dengan port dinamis. Callback localhost memerlukan port eksplisit dan kecocokan persis. Pengalihan lainnya memerlukan HTTPS. OAuth resource terikat pada URL MCP kanonis; permintaan token boleh menghilangkannya, tetapi nilai yang disertakan harus cocok. Respons otorisasi yang berhasil menyertakan iss. Kode dan token yang kedaluwarsa dihapus selama penulisan OAuth. Hash refresh token yang telah dirotasi dipertahankan selama diperlukan untuk mendeteksi penggunaan ulang pada keluarga token aktif, paling lama satu masa berlaku refresh token tambahan selama 30 hari. Menghapus atau mengganti database OAuth membatalkan klien dan pemberian akses yang ada. Endpoint, relatif terhadap issuer: /oauth/authorize, /oauth/token, /oauth/register. Metadata discovery menggunakan URL well-known dengan penyisipan path pada root domain, sehingga dengan APP_BASE_PATH=/gowa, proxy Anda harus merutekan:
Periksa discovery dari luar:
Lalu tambahkan https://gowa.example.com/mcp sebagai konektor kustom dan login dengan akun APP_BASIC_AUTH.
Pastikan Cloudflare Access, tantangan bot, atau proxy autentikasi di depan GOWA tidak mencegat path well-known, /oauth/*, atau /mcp. Batasi laju upaya login yang gagal pada /oauth/authorize di proxy Anda.