Gereksinimler
- Chatwoot’un genel bir URL üzerinden erişebildiği GOWA (temsilci yanıtı webhook’ları için).
- Yönetici erişimi olan bir Chatwoot hesabı ve kullanıcı API erişim belirteci.
- En az bir oturum açmış WhatsApp cihazı.
Kurulum
1
API kanalı gelen kutusu oluşturun
Chatwoot’ta Ayarlar → Gelen Kutuları → Gelen Kutusu Ekle → API yoluna gidin. Gelen kutusu URL’sindeki sayısal gelen kutusu kimliğini ve Chatwoot’un kanal için gösterdiği webhook sırrını not edin. Alternatif olarak gelen kutusunu GOWA’nın oluşturmasını sağlayın (bkz. Otomatik hazırlama).
2
Kimlikleri ve belirteci alın
Hesap kimliği,
/app/accounts/<id>/... içindeki sayıdır. Profil Ayarları bölümünden bir kullanıcı erişim belirteci kopyalayın. Her iki kimlik de kanalın identifier veya hmac_token değeri değil, sayısal kimlikler olmalıdır.3
GOWA'yı yapılandırın
.env
4
Chatwoot'u GOWA'ya yönlendirin
API kanalının webhook URL’sini
https://gowa.example.com/chatwoot/webhook olarak ayarlayın (APP_BASE_PATH kullanılıyorsa temel yolu ekleyin). Bu yol herkese açıktır: Basic Auth ile değil, webhook sırrıyla korunur.5
Test edin
Başka bir telefondan WhatsApp numarasına mesaj gönderin; gelen kutusunda görünmelidir. Chatwoot’tan yanıt verin ve WhatsApp’a ulaştığını kontrol edin.
Yapılandırma
Çoğu ayarın ayrıca bir
--chatwoot-* bayrağı vardır; CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID ve CHATWOOT_INBOX_ID yalnızca ortam değişkeni olarak kullanılabilir. Bkz. Yapılandırma başvurusu.
v9.9.0 sonrasındaki GOWA main sürümlerinde, normal webhook teslimlerini ayrı filtrelerken mesajları Chatwoot’a yansıtmaya devam etmek için CHATWOOT_EVENTS=message ayarlayın. message seçicisi tepkilerin, alındı bildirimlerinin, düzenlemelerin ve silmelerin de Chatwoot filtresinden geçmesine izin verir. Ayrı okuma, düzenleme ve silme ayarları geçerliliğini korur.
CHATWOOT_EVENTS değerini boş bırakarak WHATSAPP_WEBHOOK_EVENTS değerini devralın. Etkin filtre boşsa desteklenen tüm olaylara izin verir. message hariç tutulursa GOWA başlangıçta bir uyarı kaydeder ve WhatsApp mesajlarını Chatwoot’a yansıtmayı durdurur.
Bu derlemelerde GOWA, nginx’in varsayılan başlık ayarlarıyla iletebilmesi için Chatwoot kullanıcı belirtecini api-access-token başlığında gönderir.
Webhook sırrı
Etkin webhook sırrı boşsa teslim reddedilir.CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true, etkin sır boş olduğunda imzasız teslime açıkça izin verir. Sır yapılandırılmışsa her istek bunu aşağıdakilerden biriyle kanıtlamalıdır:
- Chatwoot imzası (
X-Chatwoot-Signature+X-Chatwoot-Timestamp), önerilir. API kanalının kendi webhook sırrını kullanın. GOWA,<timestamp>.<raw body>değerinin HMAC-SHA256 karmasını kontrol eder ve yapılandırılmış toleransın dışındaki zaman damgalarını reddeder. - Gövdenin
X-Hub-Signature-256HMAC değeri. X-Chatwoot-Webhook-SecretveyaX-Gowa-Chatwoot-Secretbaşlığındaki sır.- Yalnızca imza atamayan veya başlık ekleyemeyen Chatwoot sürümleri için webhook URL’sinde
?secret=. Bu durumda sır erişim günlüklerinde görünür.
401 döndürür; GOWA nedeni günlüğe kaydeder (signature does not match yanlış sır, timestamp outside the tolerance window saat sapması demektir).
Cihazın webhook_secret değeri, hem ortak hem de cihaza özel uç noktalarda o cihaz için genel sırrın yerini alır. Cihaz sırrı yoksa genel sır geçerlidir. GOWA gönderme, silme, okundu işaretleme veya veri yazmadan önce yönlendirilen cihazın sırrını doğrular. Birden fazla cihaz aynı hesap ve gelen kutusu kimliklerini kullanıyorsa cihaza özel geri çağrı URL’sini tercih edin.
Daha önce 2xx almış, yinelenen bir Chatwoot imzalı istek zaman damgası penceresi içinde 200 ile onaylanır ve atlanır. Başarısız istekler yeniden denenebilir. Hâlâ işlenmekte olan aynı istek, en fazla 30 saniye bekledikten sonra 503 döndürebilir. Yeniden oynatma belleği sürece özeldir, yeniden başlatmada kaybolur ve 65.536 kabul edilmiş istekle sınırlıdır. GOWA örnekleri arasında paylaşılmaz. Aynı Chatwoot mesajının ayrı ayrı imzalanmış iki teslimi yine de iki kez gönderime neden olabilir. Yalnızca gövde HMAC’leri, sır başlıkları ve sorgu sırları bu teslim tekilleştirmesini sağlamaz.
Otomatik hazırlama
CHATWOOT_AUTO_CREATE=true olduğunda ve CHATWOOT_INBOX_ID bulunmadığında GOWA, başlangıçta CHATWOOT_INBOX_NAME adlı bir API gelen kutusu arar ve onu yeniden kullanır veya webhook’u CHATWOOT_WEBHOOK_URL olacak şekilde bir tane oluşturur.
Her cihaz için bir gelen kutusu
Ortam değişkenleri tüm cihazların paylaştığı tek bir hedef yapılandırır. Her cihazı kendi gelen kutusuna, hesabına veya Chatwoot sunucusuna yönlendirmek için cihaza özel yapılandırmaları kaydedin (Basic Auth geçerlidir):webhook_url içerir (<base>/chatwoot/webhook/<device_id>); bunu ilgili gelen kutusunun webhook’u olarak ayarlayın. Diğer yollar: GET /chatwoot/configs, GET ve DELETE /devices/{device_id}/chatwoot/config.
api_token, GOWA veritabanında saklanır ve okumalarda maskelenir;webhook_secretasla döndürülmez.chatwoot_url, kimlik bilgileri içermeyen HTTP veya HTTPS olmalıdır.CHATWOOT_ALLOWED_HOSTSolmadan özel, loopback, link-local ve meta veri adresleri reddedilir.CHATWOOT_ALLOWED_HOSTSiçinde açıkça eşleşen bir ana makine güvenilir kabul edilir ve özel ağdaki kendi barındırdığınız Chatwoot’u hedefleyebilir. Bu izin listesine yalnızca kontrol ettiğiniz ana makineleri ekleyin.- Konuşmalar bağlandıktan sonra
chatwoot_url,account_idveyainbox_iddeğiştirilirse409döner; bunun yerine yapılandırmayı silip yeniden oluşturun. - Cihaz eşleştirilmeden önce yapılandırma oluşturulabilir.
- Doğrudan veritabanı aktarımı yalnızca tek (ortam) yapılandırma modunda çalışır.
Yanıtlar ve biçimlendirme
Bir temsilci Chatwoot’ta Yanıtla kullandığında GOWA, gönderen cihazın yerel deposunda ve aynı sohbette çözümleyebiliyorsa özgün WhatsApp mesajını alıntılar. Bu, sesin dosya olarak gönderilmesi durumunda da dahil olmak üzere metin ve tüm ekler için geçerlidir. Açıklama yalnızca ilk ekte kalır. Gelen bir WhatsApp mesajı için GOWA,in_reply_to_external_id değerini WAID:<id> önekiyle çözümler. Önceki bir temsilci yanıtı için sayısal in_reply_to, aynı cihaz, konuşma, hesap, gelen kutusu ve yapılandırmadaki kalıcı bir mesaj bağlantısı üzerinden çözümlenir. Birden fazla eki olan mesaj ilk dosyasını alıntılar. Hedef çözümlenemiyorsa yanıt alıntısız teslim edilir.
Gelen WhatsApp yanıtları ve tepkileri, Chatwoot’ta referans verilen mesaja bağlanır. Temsilci yanıtlarındaki Markdown bağlantıları ve vurgular, okunabilir WhatsApp metnine dönüştürülür. Listeler, satır sonları ve kod korunur. Boş imza ayırıcıları kaldırılır. CHATWOOT_SIGN_MSG, bu dönüşümden sonra temsilci adını başa ekler.
Yalnızca uygun, herkese açık giden temsilci mesajları gönderilir. Özel notlar ve hariç tutulan sohbetler iletilmez. GOWA, ortak geri çağrıları yönlendirmek için yapılandırılmış cihazı ve hesap/gelen kutusu kimliğini kullanır. Cihaza özel geri çağrılar belirsizlik içermeyen bir rota sağlar.
Anketler ve temsilci silme işlemleri
v9.9.0 sonrasındaki GOWAmain sürümlerinde Chatwoot; anket oluşturmayı, düzenlemeleri ve eklenen seçenekleri yansıtır. Tek tek oyları işlemek için WhatsApp webhook’larında message olayına abone olun ve yapılandırılmış anket verilerini okuyun.
Bu derlemelerde silmeleri yalnızca Chatwoot’tan WhatsApp’a eşitlemek için CHATWOOT_REVOKE_ON_DELETE=true ayarlayın. Silme işlemi, etkin Chatwoot yapılandırması altındaki giden mesajların kalıcı bağlantılarıyla eşleşmelidir. GOWA, ayrı gönderilmiş ekler dahil her bağlantılı WhatsApp mesajını geri çeker. CHATWOOT_FORWARD_DELETES=true olduğunda WhatsApp’tan yapılan silmeler yine özel not olarak görünür. Bağlantılı mesajları her iki yönde silmek için CHATWOOT_MESSAGE_DELETE=true kullanın.
Geçmişi içe aktarma
days_limit=3, include_media=true ve include_groups=true değerleridir. Eşitleme, GOWA’nın yerel sohbet deposunu okur ve arka planda çalışır. Her cihaz aynı anda bir eşitleme çalıştırabilir.
v9.9.0 sonrasındaki GOWA main sürümlerinde geçmiş eşitleme, telefondan süresi dolmuş medyayı yeniden yüklemesini isteyebilir. Telefon çevrimiçi olmalı ve dosya hâlâ telefonda bulunmalıdır. Telefon 30 saniye içinde yanıt vermezse eşitleme o çalıştırma için sonraki yeniden yükleme isteklerini atlar ve mesajları içe aktarmaya devam eder. Dosyası kullanılamayan bir mesaj eksiz içe aktarılır.
REST yolu özgün zaman damgalarını ayarlayamaz; içe aktarılan mesajlara aktarım zamanı atanır. Kendi barındırdığınız Chatwoot için CHATWOOT_IMPORT_DB_URI, doğrudan Chatwoot PostgreSQL veritabanına yazar ve özgün zaman damgalarını korur.
CHATWOOT_REOPEN_CONVERSATION=true ile v9.9.0 sonrasındaki GOWA main sürümlerinde geçmiş eşitleme, çözümlenmiş bir konuşmayı yalnızca içe aktarılacak yeni mesaj varsa yeniden açar. REST eşitleme, göndermeden önce konuşmayı yeniden açar ve açma başarısız olursa sonraki eşitlemede sohbeti tekrar dener. Doğrudan PostgreSQL aktarımı konuşmayı mesaj yazımıyla aynı işlemde yeniden açar. Ayar kapalıyken REST eşitleme yeni mesajlar için yeni bir konuşma oluştururken doğrudan aktarım çözümlenmiş konuşmayı kullanmaya devam eder.
Teslim ve yeniden denemeler
Geçici bir Chatwoot hatasıyla (ağ hatası, HTTP 429 veya 5xx) karşılaşan canlı mesajlar yerel depolamada kuyruğa alınır ve üst sınırı olan üstel beklemeyle arka planda yeniden denenir. Diğer 4xx hataları günlüğe kaydedilir ve atılır.Sorun giderme
APP_DEBUG=true ile çalıştırın ve Chatwoot: ve Chatwoot Webhook: ile başlayan günlük satırlarını arayın. Üst projenin Chatwoot kılavuzu, doğrudan veritabanı aktarımını ve biçimlendirme kurallarını daha ayrıntılı ele alır.