> ## 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.
# Kanallar
> Kanalları listelemeyi, oluşturmayı, güncellemeyi, silmeyi ve WhatsApp, Telegram ve web sitesi kanallarına özel uçları anlatır.
Kanal, kliniğin Flextell'e bağladığı bir mesajlaşma hattıdır: bir WhatsApp numarası, bir Telegram botu, bir web sitesi sohbet widget'ı veya bir Instagram kaydı. Sohbetler ve mesajlar her zaman bir kanal üzerinden akar. Bu sayfa `/channels` kaynağını ve kanal türüne özel alt uçları anlatır.
Kanal uçlarının çoğu `X-Tenant` başlığı ister ([Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant)). Tek istisna `GET /channels/capabilities` ucudur. Başka bir kliniğin kanal kimliği `404 RESOURCE_NOT_FOUND` döner.
## Endpoint özeti
Taban adres `https://app.flextell.ai/api/v1`. Her uç için scope ve izin birlikte gerekir ([İzinler ve görünürlük](/api/izinler-ve-gorunurluk)).
| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| GET | `/channels` | Kliniğin tüm kanallarını listeler | `conversations:read` veya `channels:read` | `View:Conversation` veya `View:Channel` |
| POST | `/channels` | Kanal oluşturur | `channels:write` | `Create:Channel` |
| GET | `/channels/{id}` | Tek kanalı getirir | `channels:read` | `View:Channel` |
| PUT | `/channels/{id}` | Kanalı kısmen günceller | `channels:write` | `Update:Channel` |
| DELETE | `/channels/{id}` | Kanalı siler | `channels:write` | `Delete:Channel` |
| GET | `/channels/{id}/deletion-relations` | Silmenin etkileyeceği kayıtları önizler | `channels:read` | `Delete:Channel` |
| GET | `/channels/capabilities` | Kanal türlerinin yeteneklerini listeler | `conversations:read` | Ek izin gerekmez |
| POST | `/channels/{id}/whatsapp/connect` | WhatsApp bağlantısını başlatır, QR kod döner | `channels:write` | `Update:Channel` |
| GET | `/channels/{id}/whatsapp/connection-state` | WhatsApp bağlantı durumunu sorgular | `channels:read` | `QueryStatus:Channel` veya `Update:Channel` |
| GET | `/channels/{id}/whatsapp/webhook` | WhatsApp webhook ayarlarını getirir | `channels:read` | `View:Channel` |
| PUT | `/channels/{id}/whatsapp/webhook` | WhatsApp webhook ayarlarını günceller | `channels:write` | `Update:Channel` |
| GET | `/channels/{id}/telegram` | Telegram bot bağlantısını getirir | `channels:read` | `View:Channel` |
| GET | `/channels/{id}/widget` | Widget yapılandırmasını getirir | `channels:read` | `View:Channel` |
| PUT | `/channels/{id}/widget` | Widget yapılandırmasını günceller | `channels:write` | `Update:Channel` |
| GET | `/channels/{id}/widget/embed-snippet` | Gömme kodunu getirir | `channels:read` | `CopyLink:Channel` |
| POST | `/channels/{id}/widget/rotate-token` | Gömme token'ını yeniler | `channels:write` | `GenerateLink:Channel` |
`GET /channels` sayfalama ve filtre kabul etmez. Aktif ve pasif tüm kanalları tek yanıtta döner.
## Kanal nesnesi
| Alan | Tür | Açıklama |
| - | - | - |
| `id` | integer | Kanal kimliği. |
| `tenant_id` | integer | Kanalın ait olduğu klinik. |
| `name` | string | Kanal adı. Klinik içinde benzersizdir. Büyük harfe çevrilerek saklanır: `klinik sitesi` değeri `KLINIK SITESI` olur. |
| `type` | string | `whatsapp`, `instagram`, `website` veya `telegram`. Oluşturulduktan sonra değişmez. |
| `provider` | string, null | Kanal sağlayıcısı. |
| `address` | string | WhatsApp için numara, Telegram için bot adı, web sitesi için alan adı. |
| `website_domain` | string, null | Yalnızca web sitesi kanalında dolu. |
| `status` | string | Bağlantı durumu. Aşağıdaki tabloya bakın. |
| `is_active` | boolean | Kanalın açık olup olmadığı. Varsayılan `true`. |
| `ai_reply_mode` | string, null | `auto`, `semi_auto` veya `closed`. `null` ise kliniğin çalışma saati ayarı geçerlidir. |
| `connection_error` | object, null | Bağlantı hatası varsa `code`, `expected_address`, `connected_address`, `message` ve `detected_at` alanlarını taşır. |
| `created_at`, `updated_at` | string | ISO 8601 zaman damgası. |
Gömme token'ı, bot token'ı ve sağlayıcıya ait bağlantı bilgileri yanıtta hiçbir zaman yer almaz.
```json theme={null}
{
"id": 123,
"tenant_id": 45,
"name": "KLINIK WHATSAPP",
"type": "whatsapp",
"provider": "evolution_api",
"address": "905xxxxxxxxx",
"website_domain": null,
"status": "waiting",
"is_active": true,
"ai_reply_mode": null,
"connection_error": null,
"created_at": "2026-10-12T14:30:00+03:00",
"updated_at": "2026-10-12T14:30:00+03:00"
}
```
## Kanal türleri ve durumlar
| `type` | Arayüz adı | Davranış |
| - | - | - |
| `whatsapp` | WhatsApp | Oluşturulunca `closed` başlar. QR kodla eşleştirilince `open` olur. |
| `telegram` | Telegram | Bot token ile oluşturulursa `open` başlar. Token'sız oluşturulursa yalnızca kayıttır ve `closed` kalır. |
| `website` | Website | Oluşturulunca hemen `open` olur ve gömme token'ı üretilir. |
| `instagram` | Instagram | Yalnızca kayıt oluşturur. Bağlantı sağlayan bir sürücü yoktur. |
| `status` | Arayüz etiketi | Anlamı |
| - | - | - |
| `closed` | Kapalı | Bağlı değil. |
| `waiting` | Bağlanıyor | Eşleştirme sürüyor veya henüz doğrulanmadı. |
| `open` | Aktif | Bağlı. |
`GET /channels/capabilities` her kanal türü ve sağlayıcı için `can_send_media`, `can_send_audio`, `can_send_location`, `can_start_conversation`, `uses_phone_number`, `supported_media_types`, `supported_reactions` gibi yetenek bayraklarını listeler. Hangi kanalda ne gönderebileceğinizi buradan öğrenin.
## Oluşturma ve güncelleme
`POST /channels` gövdesi:
| Alan | Zorunlu | Açıklama |
| - | - | - |
| `name` | Evet | En çok 255 karakter. |
| `type` | Evet | `whatsapp`, `instagram`, `website` veya `telegram`. |
| `address` | Koşullu | Web sitesi dışında zorunlu. Bot token gönderilen Telegram kanalında zorunlu değil. WhatsApp numarası rakamlara indirgenir: `+90 (5xx) xxx xx xx` ve `05xxxxxxxxx` aynı kayda dönüşür. |
| `website_domain` | Koşullu | Web sitesi kanalında zorunlu. Şemasız alan adı olmalı (`klinik.example.com`), isteğe bağlı port alabilir. Bu değer `address` alanına da yazılır. |
| `integration_id` | Hayır | Mevcut bir entegrasyonun kimliği. |
| `is_active` | Hayır | Varsayılan `true`. |
| `ai_reply_mode` | Hayır | `auto`, `semi_auto`, `closed` veya `null`. Web sitesi kanalında göndermezseniz `auto` olur. |
| `bot_token` | Hayır | Yalnızca Telegram. BotFather'ın verdiği `123456789:ABC...` biçiminde olmalı. |
| `webhook_enabled` | Hayır | Yalnızca Telegram. Varsayılan `true`. `false` bot webhook'unu kaldırır. |
| `webhook_base_url` | Hayır | Yalnızca Telegram. HTTPS olmalı. Canlı ortamda yok sayılır. |
Kanal kaydedildikten sonra WhatsApp hattı hazırlanır. Hazırlık başarısız olsa bile istek `201` döner. Bu yanıtta QR kod yoktur. QR kodu almak için `POST /channels/{id}/whatsapp/connect` çağırın.
`bot_token` gönderirseniz Flextell token'ı Telegram'a doğrular ve webhook'u kaydeder. Bunlardan biri başarısız olursa kanal oluşmaz. Kanal `open` döner ve `address` boşsa `@` olur.
Kanal `open` oluşur ve bir gömme token'ı üretilir. Gömme kodunu `embed-snippet` ucundan alın.
`PUT /channels/{id}` kısmi güncellemedir; yalnızca gönderdiğiniz alanlar değişir.
* `type` gönderirseniz hata almazsınız, değer sessizce yok sayılır.
* `name` büyük harfe çevrilir ve klinik içinde benzersiz olmalıdır; çakışmada `422` döner. WhatsApp kanalını yeniden adlandırmak bağlantıyı etkilemez.
* WhatsApp `address` değeri yeniden rakamlara indirgenir.
* Web sitesi kanalında `website_domain` güncellemesi `address` alanını da günceller.
* `ai_reply_mode: null` göndermek yapay zeka modu sabitlemesini kaldırır.
* Telegram kanalında `bot_token`, `webhook_enabled` veya `webhook_base_url` göndermek botu yeniden bağlar. Telegram isteği reddederse isteğin hiçbir alanı kaydedilmez.
```bash theme={null}
curl -X POST https://app.flextell.ai/api/v1/channels \
-H "Authorization: Bearer " \
-H "X-Tenant: " \
-H "Content-Type: application/json" \
-d '{
"name": "Klinik web sitesi",
"type": "website",
"website_domain": "klinik.example.com"
}'
```
### Hata kodları
| Kod | HTTP | Ne zaman |
| - | - | - |
| `VALIDATION_FAILED` | 422 | Alan doğrulaması başarısız (ör. aynı ada sahip kanal). |
| `CHANNEL_NOT_WEBSITE` | 422 | Web sitesi olmayan kanalda `website_domain` göndermek veya widget uçlarını çağırmak. |
| `CHANNEL_NOT_TELEGRAM` | 422 | Telegram olmayan kanalda Telegram alanları göndermek veya `/telegram` ucunu çağırmak. |
| `CHANNEL_TELEGRAM_TOKEN_INVALID` | 422 | Telegram bot token'ı reddetti. `errors.bot_token` alanında döner. |
| `CHANNEL_TELEGRAM_TOKEN_MISSING` | 422 | Kayıtlı ya da gönderilmiş token olmadan Telegram webhook alanlarıyla yeniden bağlama. |
| `CHANNEL_TELEGRAM_WEBHOOK_REJECTED` | 422 | Telegram webhook adresini reddetti. |
| `CHANNEL_PROVIDER_UNAVAILABLE` | 502 | WhatsApp veya Telegram tarafına ulaşılamadı. Sonra yeniden deneyin. |
## Silme ve şifre onayı
Silmeden önce `GET /channels/{id}/deletion-relations` ile etkilenecek kayıtları görün. Yanıt, sayısı sıfırdan büyük ilişkileri `relation`, `label`, `count` ve `deleted` alanlarıyla listeler. Etiketler `Accept-Language` başlığına göre Türkçe (`Sohbetler`, `Kara liste kayıtları`) veya İngilizce döner.
`DELETE /channels/{id}` isteği gövdede `current_password` ister. Bu, isteği yapan kullanıcının kendi hesabının şifresidir. Şifre yanlışsa veya yoksa `422 VALIDATION_FAILED` döner ve `errors.current_password` alanı hatayı taşır.
```bash theme={null}
curl -X DELETE https://app.flextell.ai/api/v1/channels/123 \
-H "Authorization: Bearer " \
-H "X-Tenant: " \
-H "Content-Type: application/json" \
-d '{ "current_password": "" }'
```
Başarılı yanıt `Kanal başarıyla silindi` mesajını taşır.
Kanal kalıcı olarak silinir ve bu işlemin kanal kaydı için geri dönüşü yoktur. Flextell önce WhatsApp hattını ve Telegram webhook'unu kapatmayı dener. Sonra kanala bağlı sohbetleri ve kara liste kayıtlarını siler. Önce `deletion-relations` ucunu çağırın.
## Kanala özel uçlar
### WhatsApp
Bu uçlar yalnızca WhatsApp kanallarında çalışır. Başka türde `CHANNEL_NOT_WHATSAPP` (422), desteklenmeyen sağlayıcıda `CHANNEL_PROVIDER_UNSUPPORTED` (422), sağlayıcıya ulaşılamazsa `CHANNEL_PROVIDER_UNAVAILABLE` (502) döner.
`POST /channels/{id}/whatsapp/connect` çağırın. Yanıt `channel`, `qr_code` (`data:image/png;base64,...` biçiminde) ve `pairing_code` alanlarını taşır. Kanal `waiting` durumuna geçer ve önceki `connection_error` temizlenir.
Kanalın `address` alanındaki numaranın telefonuyla QR kodu okutun.
`GET /channels/{id}/whatsapp/connection-state` çağırın. Yanıt `state` alanında `open`, `connecting`, `close` veya `refused` döner. `connecting` iken güncel QR ve eşleştirme kodu da gelir; QR yaklaşık 45 saniyede bir yenilenir.
QR kod, kanalın `address` alanındaki numaradan farklı bir telefonla okutulursa bağlantı kapatılır. Kanal `closed` olur, `connection_error` dolar ve durum sorgusu `state: close` döner. QR kodu doğru telefonla yeniden okutun ya da numara değiştiyse önce kanalın numarasını güncelleyin.
Webhook ayarları: `GET /channels/{id}/whatsapp/webhook` yanıtı `url`, `enabled` ve `events` alanlarıdır. `PUT` aynı üç alanı ister: `url` (http veya https, en çok 2048 karakter), `enabled` (boolean) ve `events` (benzersiz metinlerden oluşan dizi, her biri en çok 64 karakter). Flextell adresin sonuna `/webhook/whatsapp` ekler. WhatsApp entegrasyonunun tamamı için [WhatsApp](/api/entegrasyonlar/whatsapp) sayfasına bakın.
### Telegram
`GET /channels/{id}/telegram` bağlantı özetini döner: `has_bot_token`, `bot_id`, `bot_username` ve `webhook_enabled`. Bot token ve webhook gizli anahtarı hiçbir zaman döndürülmez. Botu bağlamak ve yenilemek için `POST` ve `PUT /channels` uçlarındaki `bot_token` alanını kullanın. Ayrıntılar için [Telegram](/api/entegrasyonlar/telegram) sayfasına bakın.
### Web sitesi widget'ı
Bu uçlar yalnızca web sitesi kanallarında çalışır; başka türde `CHANNEL_NOT_WEBSITE` (422) döner.
| Uç | Açıklama |
| - | - |
| `GET /channels/{id}/widget` | `channel_id`, `widget_config` (varsayılanlar uygulanmış), `font_google` ve `font_css` döner. `title` varsayılan olarak kanal adıdır. |
| `PUT /channels/{id}/widget` | Kısmi birleştirme yapar; yalnızca gönderdiğiniz anahtarlar değişir. Renkler `#4F46E5` gibi hex değer olmalıdır. |
| `GET /channels/{id}/widget/embed-snippet` | `embed_token`, `embed_url` ve `snippet` döner. Kanalın token'ı yoksa `CHANNEL_EMBED_TOKEN_MISSING` (422) döner. |
| `POST /channels/{id}/widget/rotate-token` | Yeni token üretir ve aynı biçimde yanıt verir. |
`snippet` değerini sitenizin `` etiketinden hemen önüne yapıştırın.