> ## 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.
# Entegrasyonlar — Genel Bakış
> Flextell panelinde kurulan WhatsApp / Telegram / e-Fatura entegrasyonlarını API ve realtime üzerinden nasıl kullanacağınız.
Flextell, iki ana entegrasyon ailesi sunar:
* **Kanal entegrasyonları** — WhatsApp ve Telegram gibi hasta iletişim kanalları. Gelen ve giden mesajlar tek bir `conversation` nesnesi üzerinde birleşir.
* **E-Fatura entegrasyonları** — Nilvera ve NES üzerinden Türkiye'de e-Fatura / e-Arşiv / e-SMM kesimi. Detay için [E-Fatura](/integrations/einvoice) sayfasına bakın.
Bu sayfa, **kanal entegrasyonlarının** API ve realtime üzerinden nasıl tüketildiğini anlatır.
**Kanal kurulumu** (QR okutma, bot token girme, webhook tanımlama) panel üzerinden yapılır — API üzerinden yeni kanal oluşturulamaz. Bu sayfa, **hâlihazırda kurulmuş** bir kanalı API'den nasıl tükettiğinizi anlatır.
## Mimari
```mermaid theme={null}
flowchart LR
WA[WhatsApp
Hasta]
TG[Telegram
Hasta]
FL((Flextell))
API[Panel / API
İstemciniz]
WA <-->|Mesaj| FL
TG <-->|Mesaj| FL
FL <-->|REST + WebSocket| API
```
* **WhatsApp**: Hasta mesaj attığında Flextell webhook üzerinden alır, `chat_log` oluşturur ve `ChatLogCreated` event'ini yayar.
* **Telegram**: Flextell, tenant'ın bot'una webhook kurar. Gelen mesajlar aynı şekilde `chat_log`'a dönüşür.
Her iki yolda da **sizin için değişmez** olan şey, çıktıyı tek bir yerden tüketmenizdir: `GET /v1/conversations` + `chat-log.{tenantId}` kanalı.
## Desteklenen kanal türleri
Flextell dahili olarak dört kanal türü tanımlar:
| Tür | `type` değeri | Durum |
| --------- | ------------- | ------------------------------------------------------------------ |
| WhatsApp | `whatsapp` | Stabil |
| Telegram | `telegram` | Stabil |
| Instagram | `instagram` | Yakında (şu an yalnızca enum olarak mevcut, sürücü aktif değildir) |
| Website | `website` | Form tabanlı giriş (aşağıya bakın) |
API'den kanal türü filtresi yaparken yalnızca **aktif** olanları beklemek iyi bir pratiktir. `channel_type=instagram` yanıtı şu anda tipik olarak boş döner.
## Kanalları listeleme — `GET /v1/channels`
Bir tenant'a bağlı kurulu kanalları çekin:
```bash theme={null}
curl --request GET \
--url https://dev.flextell.ai/api/v1/channels \
--header "Authorization: Bearer $TOKEN" \
--header "X-Tenant: 12"
```
### Yanıt
```json theme={null}
{
"success": true,
"data": [
{
"id": 4,
"tenant_id": 12,
"name": "Klinik Ana Numara",
"type": "whatsapp",
"address": "+90 555 123 4567",
"status": "connected",
"metadata": { "instance_name": "tenant-12-main" },
"is_active": true,
"created_at": "2026-01-05T09:00:00+03:00",
"updated_at": "2026-04-01T12:00:00+03:00"
},
{
"id": 5,
"tenant_id": 12,
"name": "Destek Botu",
"type": "telegram",
"address": "@klinik_destek_bot",
"status": "connected",
"metadata": null,
"is_active": true,
"created_at": "2026-02-01T10:00:00+03:00",
"updated_at": "2026-04-01T12:00:00+03:00"
}
]
}
```
Kanalın bağlantı durumu. Tipik değerler: `connected`, `disconnected`, `connecting`, `error`. `disconnected` ise mesaj gönderme uçları hata döndürebilir.
WhatsApp için telefon numarası; Telegram için bot kullanıcı adı. Hastaya paylaştığınız dış kimlik.
Kanal türüne özel ek alanlar. Bu alanın içeriği zamanla değişebilir; güçlü bağımlılık kurmayın.
Gerekli scope: `channels:read`.
## Görüşme akışı — birleşik bakış
Hangi kanaldan gelirse gelsin bir görüşme şu nesnelerden oluşur:
1. **Conversation** — Hasta ile bir kanal arasındaki uzun soluklu ilişki.
2. **ChatLog** — Görüşmedeki tek bir mesaj (metin, medya, sistem mesajı).
3. **Channel** — Hangi kanaldan geldi.
4. **Customer** — Mesajı gönderen/alıcı hasta.
```bash theme={null}
# Tüm görüşmeleri listele (WhatsApp + Telegram karışık)
GET /v1/conversations
# Belli bir kanalı filtrele
GET /v1/conversations?channel_type=whatsapp
# Metinle arama
GET /v1/conversations?search=Ayşe
```
Her `conversation` nesnesinde **`unread_count`** alanı döner; istemci tarafında `unread_count > 0` olanları filtreleyerek okunmamış görüşmeleri gösterebilirsiniz.
Bir mesaj göndermek:
```bash theme={null}
# Metin
POST /v1/conversations/{id}/messages
{
"body": "Merhaba, randevunuz yarın saat 14:00'te."
}
# Medya
POST /v1/conversations/{id}/messages/media
# (multipart — bkz. /requests/file-uploads)
```
Flextell, `conversation.channel_type` değerine bakarak doğru sürücüyü (WhatsApp/Telegram) otomatik seçer; istemcinizin kanal türünü ayrıca göndermesine gerek yoktur.
## AI asistanı ve kanallar
Her görüşme için Flextell'in AI asistanı açık/kapalı olabilir. API üzerinden:
```bash theme={null}
GET /v1/conversations/{id}/agent # durumu oku
POST /v1/conversations/{id}/agent/enable # aç
POST /v1/conversations/{id}/agent/disable # kapat (insan devralır)
```
Asistan açıkken gelen mesaja Flextell otomatik yanıt verir (ve `ChatLogCreated` yine tetiklenir — yanıt da bir `chat_log`'tur). Bu durum [AI Asistan Kontrolü](/guides/ai-agent-control) rehberinde detaylandırılır.
## Kanal ekleme
API'den yeni bir kanal eklenemez. Kullanıcılarınız kanal eklemek istediğinde onları panelde şu yollara yönlendirin:
* **WhatsApp:** `Entegrasyonlar → WhatsApp → Yeni Kanal` ve QR kod okutma.
* **Telegram:** `Entegrasyonlar → Telegram → Yeni Kanal` ve bot token girme.
Kurulumdan sonra kanal otomatik olarak `GET /v1/channels` yanıtına düşer.
## Sonraki adımlar
WhatsApp kanalı nasıl çalışır, medya tipleri, sınırlamalar.
Telegram botunuzdan gelen mesajları API'den izleme.
Nilvera ve NES entegratörleri üzerinden e-Fatura / e-Arşiv / e-SMM kesimi.