> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp
> Flextell'in WhatsApp entegrasyonu — API'den mesaj okumak, göndermek ve medya işlemek.
Flextell, her tenant için bir veya birden fazla WhatsApp kanalı kurabilir. Bu sayfa, hâlihazırda kurulmuş bir WhatsApp kanalını API üzerinden nasıl tükettiğinizi açıklar.
WhatsApp bağlantısını kurmak (QR okutma, instance oluşturma) API ile yapılmaz — panel üzerinden yapılır. API istemcileri yalnızca **kurulmuş** kanallar üzerinde mesajlaşma işlemleri yapar.
Flextell'in WhatsApp entegrasyonu, açık kaynaklı [**Evolution API**](https://doc.evolution-api.com) üzerine inşa edilmiştir. Resmi WhatsApp Business API (WABA) değil, WhatsApp Web tabanlı bir bağlantı kurulur. Bu mimari sayesinde **24 saat penceresi** ve **önceden onaylı şablon mesajı** gibi WABA kısıtlamaları Flextell'de geçerli değildir — hastaya istediğiniz zaman serbest metin gönderebilirsiniz. Karşılığında, bağlantı QR ile telefonunuza bağlı olduğundan telefonun çevrimdışı olması veya WhatsApp tarafından numaranın kısıtlanması durumunda kanal kopabilir (bkz. [Kanal durumu](#kanal-durumu)).
## Önemli noktalar
* WhatsApp kanalı, `type: "whatsapp"` olarak `GET /v1/channels` yanıtında görünür.
* `address` alanı, kanalın bağlı olduğu **telefon numarası**dır (E.164 formatında, ör. `+905551234567`).
* Bir hasta WhatsApp'tan mesaj attığında Flextell, hastayı telefon numarasına göre bulur veya otomatik oluşturur.
* Yanıtlar tek bir kanaldan (aynı numaradan) döner — hastanın göreceği gönderen numarası, kanalın `address`'idir.
## Görüşme oluşturma
Bir hastaya ilk mesajı siz atacaksanız önce bir görüşme açmanız gerekir:
```bash theme={null}
curl --request POST \
--url https://dev.flextell.ai/api/v1/conversations \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12" \
--header "Content-Type: application/json" \
--data '{
"customer_id": 391,
"channel_id": 4
}'
```
## Metin mesajı gönderme
```bash theme={null}
curl --request POST \
--url https://dev.flextell.ai/api/v1/conversations/58/messages \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12" \
--header "Content-Type: application/json" \
--data '{
"body": "Merhaba, yarınki randevunuzu hatırlatırız."
}'
```
Başarılı olduğunda yanıt:
```json theme={null}
{
"success": true,
"data": {
"id": 1043,
"conversation_id": 58,
"sender_type": "user",
"body": "Merhaba, yarınki randevunuzu hatırlatırız.",
"status": "queued",
"created_at": "2026-04-19T10:15:00+03:00"
}
}
```
`status` alanı mesajın teslim durumunu yansıtır: `queued` → `sent` → `delivered` → `read`. Güncellemeler [`ChatLogCreated`](/realtime/events#chatlogcreated) event'i ile gelmez — bu event yalnızca yeni `chat_log` için tetiklenir. Durum güncellemeleri için mesajı REST üzerinden tekrar sorgulayabilirsiniz.
## Medya gönderme
WhatsApp'ta medya göndermek için multipart endpoint'i kullanın:
```bash theme={null}
curl --request POST \
--url https://dev.flextell.ai/api/v1/conversations/58/messages/media \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12" \
--form "file=@/path/to/xray.jpg" \
--form "caption=Röntgen sonucu hazır."
```
### Desteklenen medya türleri
| Kategori | MIME örnekleri | Maksimum boyut |
| -------- | --------------------------------------- | -------------------------------------------------- |
| Görsel | `image/jpeg`, `image/png`, `image/webp` | 5 MB |
| Ses | `audio/ogg`, `audio/mpeg`, `audio/mp4` | 16 MB |
| Video | `video/mp4` | 16 MB |
| Belge | `application/pdf`, Office formatları | 50 MB (Flextell tarafı); WhatsApp tarafında 100 MB |
Sınırlar **WhatsApp'ın kendi kısıtlamalarıdır**. Flextell'in genel `/v1/files` yüklemesi 50 MB'a kadar destekler ama WhatsApp'a iletilebilecek dosya boyutu daha küçük olabilir.
### Ses kayıtları (voice note)
Ses dosyaları **OGG Opus** formatında ve 16 MB altında gönderildiğinde WhatsApp tarafında "sesli mesaj" olarak görünür. MP3 veya MP4 gönderirseniz "ses belgesi" olarak listelenir.
## Gelen mesajları okuma
Flextell, hastanın attığı her mesajı otomatik olarak görüşmeye düşer ve `ChatLogCreated` event'i yayar. API tarafında:
```bash theme={null}
curl --request GET \
--get "https://dev.flextell.ai/api/v1/conversations/58/messages" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12" \
--data-urlencode "per_page=50"
```
Gelen bir medya mesajında `media_type` alanı `image`, `audio`, `video`, `document` gibi bir değer alır ve `download_url` (kısa ömürlü) ile indirilebilir.
## Okundu olarak işaretleme
```bash theme={null}
curl --request POST \
--url https://dev.flextell.ai/api/v1/conversations/58/read \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12"
```
Bu çağrı **Flextell tarafındaki** badge ve `unread_count` değerini düşürür; [`ConversationRead`](/realtime/events#conversationread) event'ini tetikleyerek açık olan diğer istemcileri de senkronlar. Çağrının kendisi WhatsApp'a "okundu" sinyali göndermez.
Hastanın WhatsApp ekranında mavi tik görüp görmemesi bu endpoint'ten **bağımsızdır**. [AI asistan](/guides/ai-agent-control) açıkken gelen mesajlar, asistan yanıt üretmeden önce Flextell tarafından otomatik olarak WhatsApp'ta okundu (mavi tik) olarak işaretlenir. Asistan kapalıyken ve sadece insan kullanıcı sohbeti yönettiğinde mesajlar hastanın ekranında gri tik olarak kalır.
## Kanal durumu
Zaman zaman WhatsApp bağlantısı kopabilir (telefon internetten düşer, session geçersiz olur). Bu durumda:
* `GET /v1/channels` yanıtında ilgili kanalın `status` değeri `disconnected` olur.
* Yeni mesaj gönderme çağrılarınız **422** ile sonuçlanabilir.
* Bağlantıyı geri almak için panel üzerinden QR kod yeniden okutulmalıdır.
`disconnected` bir kanala mesaj göndermeye çalışmayın — kullanıcınıza "WhatsApp bağlantısını yenileyin" uyarısı gösterin. Bu durumu saptamak için `GET /v1/channels`'ı periyodik (örn. 5 dakikada bir) polling'e alabilirsiniz.
## Sık kullanılan örnekler
Hastaya mesaj gönderme + medya iliştirme örneği.
Hastanın anında yanıt vermesini dinleyin.
## Sınırlamalar özet
* **Telefon bağlı olmalıdır.** Bağlantı WhatsApp Web üzerinden kurulur; telefon internete bağlı değilse mesaj gönderilemez.
* **Sesli aramalar** desteklenmez (yalnızca mesajlaşma).
* **Grup sohbetleri** desteklenmez.
* **Yayın listesi (broadcast) / toplu gönderim** — WhatsApp tarafında numaranın kısıtlanmaması için aşırı sayıda mesajdan kaçının. Agresif toplu gönderim WhatsApp'ın numarayı banlamasına yol açabilir.