/devices/{device_id}/webhook üzerinden cihaz başına yapılandırın.
Teslimat nasıl çalışır
Her hedef URL’ye teslimat, kendi gizli anahtarı ve yeniden denemeleriyle bağımsız olarak yapılır.Yapılandırma
--webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify ve --webhook-all-device-receipts.
Özel bir imzalama anahtarını açıkça belirleyin. Ayarlanmamış bir anahtar veya daha önce yayımlanan secret değeri, GOWA’nın yeniden başlatıldığında değişen rastgele bir anahtar oluşturmasına ve bir uyarı kaydetmesine neden olur. Alıcıların yeniden başlatmalar arasında imzaları doğrulayabilmesi için açıkça belirlenmiş ortak bir anahtar gerekir. HTTPS sertifikaları varsayılan olarak doğrulanır.
Olaylar
İzin listesindeki olay adları büyük/küçük harfe duyarsızdır.
Veri yükü
Her istek aynı zarfı kullanır:
Yanıtlar
replied_to_id ve quoted_body ekler. Alındı bildirimleri ids (dizi) ve receipt_type kullanır. Grup katılımcısı olayları chat_id, type ve jids taşır. Grup adı değişiklikleri ayrı bir group.info yapısı kullanır.
sender_display_name yalnızca from boş olmayan bir dize olduğunda görünür. Başka bir gönderen için GOWA sırasıyla kayıtlı kişi adını, canlı olayın profil adını, saklanan profil adını, işletme adını ve JID’nin kullanıcı bölümünü tercih eder. Etkin hesap için önce hesabın profil adını, ardından JID kimliğini tercih eder. Çözümleme eldeki bilgilerle yapılır. Eski from_name alanı, mesaj olayının profil adı olarak kalır.
WhatsApp doğrulanmış ad sertifikası sağladığında gelen mesajlar is_business: true, verified_name ve verified_level içerebilir. Aksi halde bu alanlar bulunmaz. Alanların yokluğu, gönderenin bir işletme olup olmadığını göstermez; verified_level, resmî bir rozet garantisi değil, üst kaynaktan gelen ham değerdir.
Medya
WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (varsayılan) olduğunda medya statics/media/ altında saklanır ve medya alanı yolu içerir:
{"path": "...", "caption": "..."} olur ve açıklama body içinde de yer alır. Otomatik indirme kapalıyken alan {"url": "https://mmg.whatsapp.net/...", "caption": "..."} olur; dosyayı daha sonra GET /message/{message_id}/download?phone=<chat> ile alın.
Veri yüklerinin tam kataloğu (anketler, konumlar, kişiler, bir kez görüntüleme, reklam yönlendirmeleri ve daha fazlası) üst kaynaktaki webhook veri yükü başvurusunda bulunur.
Albümler ve yapılandırılmış mesajlar
Bir albüm birden fazlamessage olayı olarak gelir. Başlıkta mesaj gövdesi yoktur ve beklenen öğe sayılarını taşır:
album_id: "ALBUM_HEADER_ID" içeren kendi normal medya olayıyla gelir. Öğeleri bu kimliğe göre gruplandırın. Başlık indirilebilir bir medya öğesi değildir ve Chatwoot’a iletilmez.
Anket oluşturma, oylar, düzenlemeler ve eklenen seçenekler de message kullanır. body alanına güvenmek yerine yapılandırılmış poll nesnesini inceleyin. Seçenek karmaları, seçenek adlarının tam hâlinin küçük harfli onaltılık SHA-256 karmalarıdır. Mevcut WHATSAPP_WEBHOOK_EVENTS=message abonelikleri bu etkileşimleri alır.
Çevrimiçi ve çevrimdışı durumu
Olayları alan cihazı kullanarak her bir kişiye ayrı ayrı abone olun:results.subscribed: true ve results.jid içerir. Grup ve kanal JID’leri reddedilir. Abonelik, cihazınızın çevrimiçi durumu ayarını geçersiz kılmaz. Sürekli güncellemeler için GOWA’yı şu ayarlarla başlatın:
state, available veya unavailable olur. Bilinmiyorsa veya kişinin gizlilik ayarlarıyla gizlenmişse last_seen bulunmaz. Uygun olduğunda from_lid dahil edilir. Yazma ve kayıt, ayrı chat_presence olayları olarak kalır ve bu aboneliği kullanmaz.
Grup adı değişiklikleri
name_set_by, LID’den telefon JID’sine çözümlenir; WhatsApp işlemi yapanı belirtmediğinde bu alan bulunmaz. Olay izin listeniz diğer olayları dışlıyorsa group.info olayına açıkça abone olun.
Kanal sayacı güncellemeleri
newsletter.message, kesin olarak yeni gönderi gövdesi sunmak yerine canlı sayaçları bildirir. Girdiler her zaman server_id içerir. WhatsApp sağlamadığında message_id, type ve timestamp bulunmaz. Sıfır olan veya bulunmayan sayaçlar atlanabilir.
reaction_counts, WhatsApp’ın tepki sayılarını içerir. Güncellemeleri kanal kimliği ve sunucu kimliğine göre işleyin. Eksik bir sayacı sıfırlanmış olarak değerlendirmeyin.
Hesap kısıtlamaları ve oturum kapatma
Cihaz olayları her zamansession_id taşır; böylece aynı WhatsApp numarasını kullanan yuvalar ayırt edilebilir. Olay, kendisini üreten yuvanın webhook yapılandırmasını kullanır. Uzaktan oturum kapatma, yeniden eşleştirme için yuvayı korur ve oturum kapatılmadan önceki kimliği bildirir. Yuvanın webhook ayarları yeniden eşleştirmede korunur. Bu olaylar Chatwoot’a gönderilmez.
Kodlar değiştirilmeden iletilir ve neden metni whatsmeow’dan gelir. Bilinmeyen kodlar da alınır. Oturum kapatma kodları
403 ve 406 tek başına kesin nedeni göstermez. Geçici yasak süresinin sıfır olması, WhatsApp’ın sona erme zamanı vermediği anlamına gelir. Yeni kişilere ulaşma zaman kilidi, yeni sohbet başlatmayı kısıtlar ve 463 gönderim hatasına yol açabilir.
İmzaları doğrulama
Her istek, webhook gizli anahtarıyla hesaplanan ham istek gövdesinin HMAC-SHA256 değeri olanX-Hub-Signature-256: sha256=<hex> üst bilgisini taşır. JSON’u ayrıştırmadan önce, alınan baytların tam hâli üzerinden hesaplayın.
Teslimat ve yeniden denemeler
- Her deneme 10 saniye sonra zaman aşımına uğrar.
- 2xx dışındaki tüm yanıtlar veya ağ hataları yeniden denenir. GOWA, aralarında 1 sn, 2 sn, 4 sn ve 8 sn bekleyerek en fazla 5 deneme yapar. Olay işleyicisinin bağlam süresi sınırı, tüm denemeler tamamlanmadan teslimatı durdurabilir.
- Son başarısızlıktan sonra olay bırakılır ve günlüğe kaydedilir. Kalıcı kuyruk veya teslim edilemeyen olay deposu yoktur.
- Birden fazla URL’ye teslimat bağımsız olarak yapılır.
2xx yanıtı verin. Yeniden denenen bir olay birden fazla kez gelebileceğinden işleyicileri yinelendiğinde aynı sonucu verecek şekilde tasarlayın.
Bağlı cihaz alındı bildirimleri
GOWA, yinelenenleri azaltmak için varsayılan olarak kişilerin onay bildirimlerini yalnızca birincil cihazlardan iletir. Mevcut hesabın kendiread ve read-self bildirimleri tüm cihazlarından geçer. Hesabın kendisine ait bu bildirimlerde payload.from, hesap JID’sidir ve payload.ids, okunmuş gelen mesajları tanımlar.
Kişinin telefonu çevrimdışıyken de dahil olmak üzere bağlı cihazlardan gelen kişi alındı bildirimlerini de almak için WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true veya --webhook-all-device-receipts=true ayarlayın. CLI bayrağı, açıkça belirtilen false dahil, ortam ayarını geçersiz kılar.
Bu isteğe bağlı özellik, yinelenen veya sırası bozulmuş onay bildirimleri üretebilir. Güncellemeleri hesap, sohbet ve mesaj kimliği başına yinelendiğinde aynı sonucu verecek şekilde uygulayın. Eski bir bildirim geldiğinde okunmuş bir mesajı asla teslim edildi durumuna düşürmeyin. Mesaj kimlikleri ve gönderen JID’leri, cihaz son ekleri olmadan standart biçimlerini korur.
Olayları filtreleme
Türe göre:WHATSAPP_WEBHOOK_EVENTS=message,message.ack yalnızca bu olayları iletir.
Sohbete veya gönderene göre: WHATSAPP_WEBHOOK_IGNORE_JIDS, chat_id, from, chat_lid ve from_lid ile eşleşir. @ ile başlayan girdiler tüm adres alanı için joker karakterdir (@g.us, @s.whatsapp.net, @lid); diğerleri tam JID eşleşmesidir.
from alanı bir kullanıcı JID’si olduğundan @s.whatsapp.net grup mesajlarıyla da eşleşir. Grupları sessize almak için @g.us kullanın. İki filtre birlikte uygulanır: bir olay yalnızca türüne izin veriliyorsa ve JID’si yok sayılmıyorsa gönderilir.
Cihaz başına webhook’lar
Bir yuvaya kendi webhook’unu, gizli anahtarını ve olay izin listesini atayın:POST /devices tarafından kabul edilir. Mevcut ayarı GET /devices/{device_id}/webhook ile okuyun. Temizlemek için "webhook_url": "" gönderin.
Cihazın webhook_secret veya webhook_events alanı boşsa ilgili genel ayar kullanılır. Saklanan cihaz webhook_insecure_skip_verify boole değeri genel TLS ayarının yerini alır. Özellikle false, genel doğrulamayı atlama etkin olsa bile sertifika doğrulamasını etkin tutar.
Varsayılan olarak cihaz başına URL, bu yuva için genel WHATSAPP_WEBHOOK değerinin yerini alır. WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true ile bunun yerine genel URL’lere eklenir: cihaz URL’si cihazın gizli anahtarını ve izin listesini kullanır, genel URL’ler genel ayarları korur ve her ikisinde bulunan bir URL olayı bir kez alır. JID yok sayma kuralları her ikisine de uygulanır.
Yerel test
Yerel bir alıcıyı tünelle (örneğinngrok http 8080) dışarı açın ve WHATSAPP_WEBHOOK değerini tünel URL’sine ayarlayın. --debug=true ile GOWA her teslimat denemesini ve başarısızlığı günlüğe kaydeder.
Olayları almanın diğer yolları
/ws?device_id=<id>adresindeki WebSocket, eşleştirme ve durum olaylarını kontrol paneli istemcilerine gönderir. Mesaj teslimatı için webhook’ları kullanın.- Sorgulama:
GET /chatsveGET /chat/{chat_jid}/messages, GOWA’nın yerel sohbet deposunu okur. Bkz. Mesaj alma.
