> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatwoot Entegrasyonu

> WhatsApp konuşmalarını bir Chatwoot gelen kutusuna yansıtın ve temsilcilerin Chatwoot üzerinden yanıt vermesini sağlayın.

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.

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## 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](#otomatik-haz%C4%B1rlama)).

**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**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

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

| Değişken | Varsayılan | Açıklama |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | Ana anahtar. |
| `CHATWOOT_URL` | — | Chatwoot temel URL'si; sonunda eğik çizgi olmamalıdır. |
| `CHATWOOT_API_TOKEN` | — | Kullanıcı API erişim belirteci. |
| `CHATWOOT_ACCOUNT_ID` | — | Sayısal hesap kimliği. |
| `CHATWOOT_INBOX_ID` | — | Sayısal gelen kutusu kimliği. `CHATWOOT_AUTO_CREATE=true` ile isteğe bağlıdır; ayarlandığında her zaman önceliklidir. |
| `CHATWOOT_DEVICE_ID` | — | Temsilci yanıtlarını gönderen cihaz (yuva kimliği veya JID). Birden fazla cihaz olduğunda zorunludur. |
| `CHATWOOT_WEBHOOK_URL` | — | Genel GOWA webhook URL'si; gelen kutusu otomatik oluşturulurken kullanılır. |
| `CHATWOOT_WEBHOOK_SECRET` | — | Gelen Chatwoot webhook'larını doğrular. İmzasız isteklere açıkça izin veren ayar etkin değilse, etkin sırrın boş olması çağrıları reddeder. |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | Etkin sır bulunmayan istekleri kabul eder. Bunu güvenilir bir ağla sınırlayın. |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | `X-Chatwoot-Timestamp` için en yüksek yaş / saat sapması. |
| `CHATWOOT_AUTO_CREATE` | `false` | Başlangıçta `CHATWOOT_INBOX_NAME` adlı API gelen kutusunu yeniden kullanır veya oluşturur. |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | Otomatik hazırlama için gelen kutusu adı. |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | Cihaz bağlandığında geçmişi otomatik içe aktarır. |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | İçe aktarılacak geçmişin gün sayısı. |
| `CHATWOOT_IMPORT_DB_URI` | — | Doğrudan geçmiş aktarımı için Chatwoot PostgreSQL URI'si (özgün zaman damgalarını korur). |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | Doğrudan aktarım: indirilemeyen medya için `[image]` tarzı yer tutucular ekler. |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | Doğrudan aktarım: eklerin oluşturulması için medyayı REST API üzerinden yükler. |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | Kişi yeniden yazdığında çözümlenmiş konuşmayı tekrar açar. |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | Yeni konuşmaları `pending` olarak oluşturur; `open` kullanmaz. |
| `CHATWOOT_IGNORE_JIDS` | — | Asla yansıtılmayan, virgülle ayrılmış JID'ler veya joker desenler (`@g.us`, `@s.whatsapp.net`, `@lid`). |
| `CHATWOOT_SIGN_MSG` | `false` | Temsilci yanıtlarının başına temsilci adını ekler. |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | İmza ile mesaj arasındaki ayırıcı. |
| `CHATWOOT_FORWARD_EDITS` | `true` | WhatsApp düzenlemelerini özel not olarak yansıtır. |
| `CHATWOOT_FORWARD_DELETES` | `true` | Herkesten silme işlemlerini özel not olarak yansıtır. |
| `CHATWOOT_EVENTS` | `WHATSAPP_WEBHOOK_EVENTS` değerini izler | Chatwoot'a iletilecek virgülle ayrılmış olaylar. |
| `CHATWOOT_MESSAGE_READ` | `false` | Okunma durumunu iki yönlü eşitler. |
| `CHATWOOT_MESSAGE_DELETE` | `false` | Diğer taraftaki bağlantılı mesajı siler. |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | Temsilci Chatwoot mesajını sildiğinde bağlantılı giden WhatsApp mesajlarını geri çeker. |
| `CHATWOOT_ALLOWED_HOSTS` | — | Cihaza özel `chatwoot_url` değerinin hedefleyebileceği ana makinelerin izin listesi. |

Ç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](https://gowa-docs.mintlify.site/tr/configuration.md).

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):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

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`.

> [!WARNING]
>
> 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](https://gowa-docs.mintlify.site/tr/concepts/webhooks.md#alb%C3%BCmler-ve-yap%C4%B1land%C4%B1r%C4%B1lm%C4%B1%C5%9F-mesajlar) `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

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

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

| Belirti | Kontrol |
| - | - |
| Temsilci yanıtları teslim edilmiyor | `CHATWOOT_DEVICE_ID` ayarlanmış ve cihaz oturum açmış olmalı; webhook URL'si doğru ve genel erişime açık olmalı; günlüklerde `DEVICE_NOT_AVAILABLE`, kullanılabilir cihaz olmadığını gösterir. |
| `401` hatası: `/chatwoot/webhook` | Sır uyuşmazlığı veya saat sapması (yukarıya bakın). |
| WhatsApp mesajları Chatwoot'ta eksik | `CHATWOOT_ENABLED` değerini, kullanıcı belirtecini, hesap ve gelen kutusu kimliklerini ve `CHATWOOT_URL` bağlantısını kontrol edin. Yeni derlemelerde etkin olay filtresinin `message` içerdiğini kontrol edin. |
| `CHATWOOT_NOT_CONFIGURED` | URL, belirteç, hesap kimliği veya gelen kutusu kimliği eksik. |

`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](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md), doğrudan veritabanı aktarımını ve biçimlendirme kurallarını daha ayrıntılı ele alır.


## Related topics

- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/tr/index.md)
- [Chatwoot webhook uç noktası](https://gowa-docs.mintlify.site/tr/api-reference/chatwoot/chatwoot-webhook-uç-noktası.md)
- [Chatwoot eşitleme ilerlemesini getir](https://gowa-docs.mintlify.site/tr/api-reference/chatwoot/chatwoot-eşitleme-ilerlemesini-getir.md)
- [Mesaj geçmişini Chatwoot ile eşitle](https://gowa-docs.mintlify.site/tr/api-reference/chatwoot/mesaj-geçmişini-chatwoot-ile-eşitle.md)
- [Bir cihazın Chatwoot yapılandırmasını sil](https://gowa-docs.mintlify.site/tr/api-reference/chatwoot/bir-cihazın-chatwoot-yapılandırmasını-sil.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.