Ana içeriğe atla
Chatwoot etkinken GOWA, WhatsApp mesajlarını (gelenler ve telefondan gönderilen gidenler) bir Chatwoot API kanalı gelen kutusuna iletir ve Chatwoot’taki temsilci yanıtlarını WhatsApp’a geri gönderir. Metin, görsel, ses, video, belge, çıkartma, konum ve kişi desteklenir; grup sohbetleri, gönderenin adı başa eklenerek grup başına tek konuşma olarak görünür.

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
GOWA’yı yeniden başlatın: Chatwoot yolları başlangıçta kaydedilir.
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:
  1. 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.
  2. Gövdenin X-Hub-Signature-256 HMAC değeri.
  3. X-Chatwoot-Webhook-Secret veya X-Gowa-Chatwoot-Secret başlığındaki sır.
  4. 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.
Başarısızlıklar 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):
Yanıt 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.
Cihaza özel herhangi bir yapılandırma oluşturulduğunda CHATWOOT_* hedefi artık yedek hedef olarak kullanılmaz. Yapılandırması olmayan cihazlar yansıtılmaz.
  • api_token, GOWA veritabanında saklanır ve okumalarda maskelenir; webhook_secret asla döndürülmez.
  • chatwoot_url, kimlik bilgileri içermeyen HTTP veya HTTPS olmalıdır. CHATWOOT_ALLOWED_HOSTS olmadan özel, loopback, link-local ve meta veri adresleri reddedilir. CHATWOOT_ALLOWED_HOSTS iç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_id veya inbox_id değiştirilirse 409 dö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 GOWA main 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

Varsayılanlar 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.