11. WhatsApp webhook

<< İçindekileri Görüntülemek İçin Tıklayın >>

Yer:  Teknik Kılavuzlar > Netsim System Agent İstemci Protokolü Referansı >

11. WhatsApp webhook

WhatsApp Business Cloud API'nin (Meta) gönderdiği gelen mesajlar ve giden mesaj durumları (sent, delivered, read, failed) motorun WHATSAPP paketindeki iki PSQL yordamıyla karşılanır (SQL kılavuzu "WhatsApp"): webhook, olayların yazılacağı veritabanının iki ENDPOINT nesnesi ve bir credential'dır; ajan bunları REST işlemcisiyle sunar. Mesaj gönderme de aynı paketin işidir.

Kurulum (olayların yazılacağı veritabanında bir kez, msql ile):

set catalog <veritabanı>;
create credential wa_webhook type CUSTOM identity '<doğrulama belirteci>' password '<App Secret>'
  tags (MQTOPIC = '/whatsapp/event');
create endpoint whatsapp_verify  method GET  path '/' as call WhatsApp.WebhookVerify;
create endpoint whatsapp_receive method POST path '/' as call WhatsApp.WebhookReceive;
commit;

Conf'ta REST işlemcili bir uygulama (örnek conf'taki WhatsAppWebhook girdisi):

Anahtar Öndeğer Anlam
processor, path REST, /whatsapp Meta'ya verilen geri çağırma adresi https://<sunucu>/whatsapp/ (sonda /); eğik çizgisiz istek de aynı uca düşer. Ajan düz HTTP konuşur; Meta HTTPS ister, TLS ters vekilin işidir.
database — Olayların yazıldığı motor veritabanı: hizmette kayıtlı bir veritabanının adı; uçlar ve wa_webhook credential'ı bu veritabanındadır. Olaylar ivd$whatsapp_event sistem tablosuna WhatsApp.RecordEvent ile yazılır. Firebird, PostgreSQL, ODBC ya da sqlite dosyası depolu olmalıdır: istek bir işçi süreçte koşar ve depoya o sürecin kendi bağlantısıyla erişilir.
sessionManager — Olay bildiriminin yayınlandığı oturum yöneticisi. Tüketiciler /message uygulamasına bağlandığı için onunla aynı olmalıdır (örnek conf: default). Tüketici POST /message/OpenSession (Basic) ve POST /message/SUBSCRIBE {"topic": "/whatsapp/event"} ile abone olur.
statementTimeoutMs, maxBodyBytes, reloadIntervalSec REST öndeğerleri REST işlemcisinin genel anahtarları (bkz. §3.5).
  • Sırlar credential'dadır: doğrulama belirteci wa_webhook'un IDENTITY'si, App Secret PASSWORD'ü; conf'ta sır yoktur. İmza Crypto.hmac_sha256('credential:wa_webhook', gövde) ile sır PSQL'e gelmeden doğrulanır. MQTOPIC etiketi bildirim konusudur (yoksa /whatsapp/event; '-' kapatır).
  • GET: hub.mode=subscribe ve hub.verify_token eşleşirse hub.challenge düz metin olarak döner; aksi 403, eksik parametre 400.
  • POST: X-Hub-Signature-256 imzası tutmazsa ya da credential yoksa 403. Geçerli istekte her mesaj ve durum ayrı satır olarak yazılır ve tek commit ile kaydedilir. Yanıt 200 {"result": true, "events": N, "duplicates": M}. Aynı olay (tür + wamid + durum) ikinci kez yazılmaz; Meta'nın yeniden gönderimi bu yüzden zararsızdır. Veritabanı hatası 500 döner ve Meta olayı yeniden gönderir. Bozuk JSON 400 alır; WhatsApp dışı bir nesne 200 ile yok sayılır. Bu uç ClientREST'in 202 sözleşmesini kullanmaz: Meta 2xx dışını yeniden deneme sebebi sayar.
  • Bildirim (MessageQueue.Publish) kalıcı değildir: abonesi olmayan bildirim düşer, olay tabloda kalır. Gövde JSON: eventId, eventKind (MESSAGE | STATUS) ve ivd$whatsapp_event kolonlarının camelCase adları (accountId, phoneNumberId, wamid, sender, senderName, recipient, messageType, status, text, mediaId, replyToWamid, errorCode, errorMessage, eventTime ISO 8601 UTC); olmayan alan null, ham JSON gönderilmez. ClientREST oturumları kendiliğinden /broadcast, /user/<ad> ve /session/<anahtar> kanallarına abonedir.
  • Tablo tanımı: IVEDI_Code/docs/whatsapp-paketi.md, 2B. Canlı sınama: python NetsimSystemAgent/tools/whatsapp_webhook_test.py. Bu araç ajanın yalıtılmış bir kopyasını ayrı bir portta başlatır ve kendi süreçlerini durdurur.