Kanallar

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

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.

{
  "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.

WhatsApp
Telegram
Web sitesi

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 @<bot_kullanıcı_adı> 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.

curl -X POST https://app.flextell.ai/api/v1/channels \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -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.

curl -X DELETE https://app.flextell.ai/api/v1/channels/123 \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "current_password": "<hesap_şifresi>" }'

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

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.

Bağlantıyı başlatın

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.

QR kodu telefonda okutun

Kanalın address alanındaki numaranın telefonuyla QR kodu okutun.

Durumu yoklayın

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 sayfasına bakın.

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 sayfasına bakın. 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 </body> etiketinden hemen önüne yapıştırın.

Token yenilenince açık ziyaretçi oturumları sona erer ve sitenizdeki eski gömme kodu çalışmayı bırakır. Yeni kodu sitenize yerleştirin. Widget’ın ziyaretçi tarafındaki uçları için Web sitesi widget’ı sayfasına bakın.

İlgili sayfalar

Sohbetler

Kanallar üzerinden akan sohbetleri listeleyin.

Engellenen kullanıcılar

Bir kanalda engellenen numaraları yönetin.

Hatalar

Tüm hata kodlarının listesi.

İzinler ve görünürlük

İzin ve scope ilişkisi.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

Endpoint özeti

Kanal nesnesi

Kanal türleri ve durumlar

Oluşturma ve güncelleme

Hata kodları

Silme ve şifre onayı

Kanala özel uçlar

WhatsApp

Telegram

Web sitesi widget’ı

İlgili sayfalar

Sohbetler

Engellenen kullanıcılar

Hatalar

İzinler ve görünürlük

​Endpoint özeti

​Kanal nesnesi

​Kanal türleri ve durumlar

​Oluşturma ve güncelleme

​Hata kodları

​Silme ve şifre onayı

​Kanala özel uçlar

​WhatsApp

​Telegram

​Web sitesi widget’ı

​İlgili sayfalar

Sohbetler

Engellenen kullanıcılar

Hatalar

İzinler ve görünürlük

Endpoint özeti

Kanal nesnesi

Kanal türleri ve durumlar

Oluşturma ve güncelleme

Hata kodları

Silme ve şifre onayı

Kanala özel uçlar

WhatsApp

Telegram

Web sitesi widget’ı

İlgili sayfalar