Ana içeriğe atla
GOWA, REST API ile aynı süreçten bir Model Context Protocol uç noktası sunar. Akış destekli HTTP aktarımını destekleyen herhangi bir MCP istemcisi bunun üzerinden mesaj gönderebilir, sohbetleri okuyabilir ve grupları yönetebilir.
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (varsayılan http://localhost:3000/mcp)
  • Varsayılan olarak etkindir. MCP_ENABLED=false veya --mcp-enabled=false ile devre dışı bırakın.
  • Durum bilgisi tutmaz: çağrılar arasında canlı tutulması gereken bir oturum el sıkışması yoktur.
Eski bir sürümden mi yükseltiyorsunuz? Bağımsız ./whatsapp mcp komutu ve 8080 portundaki SSE uç noktası (/sse) kaldırılmıştır. ./whatsapp rest çalıştırın ve istemcileri /mcp adresine yönlendirin. Eski, her işlem için ayrı araç içeren kümenin yerini aşağıdaki birleştirilmiş araçlar almıştır.

İstemci bağlama

/mcp, REST API ile aynı Basic Auth korumasının arkasındadır. Authorization başlığını ve birden fazla cihaz çalıştırıyorsanız X-Device-Id başlığını gönderin:
YWRtaW46Y2hhbmdlbWU=, base64("admin:changeme") değeridir; kendi değerinizi echo -n 'user:pass' | base64 ile oluşturun. Basic Auth kapalıysa Authorization başlığını, yalnızca bir cihaz varsa X-Device-Id başlığını eklemeyin. Yapılandırmanın tam biçimi istemciye bağlıdır. Bir istemci yalnızca stdio sunucularını başlatabiliyorsa mcp-remote gibi bir köprü kullanın.

Araçlar

GOWA yedi araç sunar. Her biri işlemi seçen bir type (gönderim) veya action (diğer tümü) bağımsız değişkeni alır. Bağımsız değişkenlere ilişkin notlar:
  • whatsapp_send her zaman type ve phone gerektirir. Medya yalnızca URL ile gönderilir (image_url, video_url, audio_url, file_url, sticker_url); MCP yerel dosya yükleyemez. link, link ve caption gerektirir; forward, message_id gerektirir.
  • whatsapp_send, zamanlama alanlarını kabul eder (scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, occurrence_limit). Sonucu whatsapp_schedule ile yönetin (get, pause, resume ve cancel, schedule_id gerektirir).
  • whatsapp_message, phone (sohbet) ve message_id gerektirir; edit ayrıca message gerektirir.
  • v9.9.0 sonrasındaki GOWA main sürümlerinde, whatsapp_message, action: "edit" ile kullanıldığında, açıklamayı değiştirmek için media_type: "image" veya media_type: "document" kabul eder. Özgün medya türüyle eşleştirin ve link eklemeyin. Bkz. Açıklama düzenleme.
  • whatsapp_chat: get_messages, chat_jid gerektirir; archive, chat_jid ve archived gerektirir.
  • whatsapp_app: login_code, phone gerektirir.
Deneysel düğme, konum isteği ve karusel gönderimleri yalnızca REST üzerinden kullanılabilir. Bkz. Etkileşimli mesajlar. Bülten araçları kanal keşfini, geçmiş sayaçlarını ve otomatik yenilenen canlı güncelleme aboneliklerini destekler. Bkz. Bültenler. Medya URL’sinden indirmeler, REST gönderimleriyle aynı genel adres kontrollerini uygular ve HTTP_PROXY veya HTTPS_PROXY kullanmadan doğrudan bağlanır. Yerel dosyalardan yükleme için REST API gerekir. MCP istemciniz her aracın tam girdi şemasını gösterir. HTTP uç noktası POST ve DELETE kabul eder. GET SSE akışı devre dışıdır.

Cihaz seçimi

Her çağrı cihazını şu sırayla belirler:
  1. Araç çağrısındaki device_id bağımsız değişkeni.
  2. MCP bağlantısındaki X-Device-Id başlığı.
  3. Tam olarak bir cihaz varsa kayıtlı tek cihaz.
Aksi halde çağrı device identification required: set the X-Device-Id header or pass device_id hatasıyla başarısız olur. Bkz. Çoklu cihaz.

OAuth kullanan uzak istemciler

Claude özel bağlayıcıları gibi barındırılan istemciler Basic Auth başlığı ekleyemez. GOWA, bunlar için /mcp üzerinde bir OAuth 2.1 yetkilendirme sunucusu çalıştırabilir. Varsayılan olarak kapalıdır.
Gereksinimler ve davranış:
  • APP_BASIC_AUTH ayarlanmalıdır: yetkilendirme sayfası kullanıcıların aynı hesaplarla giriş yapmasını sağlar. Bu olmadan başlangıç başarısız olur.
  • Yayıncı ve kaynak, http://gowa:3000 gibi dahili adresler değil, istemcilerin gördüğü genel HTTPS URL’leri olmalıdır.
  • OAuth açıkken /mcp, Bearer belirteci veya Basic Auth kabul eder. Belirteçler REST veya arayüz yollarında kabul edilmez.
  • İstemciler kendilerini kaydeder (RFC 7591 dinamik istemci kaydı). Kayıt gövdeleri 16 KiB, her yönlendirme URI’si 2 KiB ile sınırlıdır. Kayıtlar saatte 40 ve saklanan istemciler 1.000 ile sınırlıdır; kullanılmayanlar 24 saat sonra temizlenir.
  • PKCE S256 zorunludur. Kodların süresi 5 dakika, erişim belirteçlerinin süresi 1 saat sonra dolar; yenileme belirteçleri döndürülür ve eski bir belirteci yeniden kullanmak tüm belirteç ailesini iptal eder. Yalnızca belirteçlerin SHA-256 karmaları MCP_OAUTH_DB_URI içinde saklanır (varsayılan file:storages/oauth.db).
Yönlendirme URI’leri kayıtlı değerlerle tam olarak eşleşmelidir. Yerel istemciler dinamik portlu HTTP loopback IP geri çağrılarını kullanabilir. localhost geri çağrıları açıkça belirtilmiş bir port ve tam eşleşme gerektirir. Diğer yönlendirmeler HTTPS gerektirir. OAuth resource, standart MCP URL’sine bağlıdır; belirteç istekleri bunu atlayabilir ancak sağlanan değer eşleşmelidir. Başarılı yetkilendirme yanıtları iss içerir. Süresi dolan kodlar ve belirteçler OAuth yazma işlemlerinde temizlenir. Döndürülmüş yenileme belirteci karmaları, etkin bir aileye karşı yeniden kullanımı tespit etmek için gerektiği sürece, en fazla 30 günlük bir ek yenileme belirteci ömrü boyunca tutulur. OAuth veritabanını silmek veya değiştirmek mevcut istemcileri ve yetkileri geçersiz kılar. Yayıncıya göre uç noktalar: /oauth/authorize, /oauth/token, /oauth/register. Keşif meta verileri, etki alanı kökünde yol eklemeli well-known URL’lerini kullanır; dolayısıyla APP_BASE_PATH=/gowa ile vekiliniz şu adresleri yönlendirmelidir:
Keşfi dışarıdan kontrol edin:
Ardından https://gowa.example.com/mcp adresini özel bağlayıcı olarak ekleyin ve bir APP_BASIC_AUTH hesabıyla giriş yapın.
GOWA’nın önündeki Cloudflare Access, bot kontrolleri veya kimlik doğrulama vekillerinin well-known, /oauth/* veya /mcp yollarına müdahale etmediğinden emin olun. Vekilinizde /oauth/authorize üzerindeki başarısız girişlere hız sınırı uygulayın.