Telegram

Telegram botuna yazılan mesajları Flextell’de Sohbetler altında karşılamak ve bot üzerinden yanıtlamak için bir Telegram kanalı oluşturursunuz. Bot bağlantısını yalnızca API ile kurabilirsiniz: bot token’ını POST /api/v1/channels çağrısına vermeniz yeterlidir. Flextell token’ı doğrular, webhook’u kendisi kaydeder ve kanalı açar.

Yeni panelde Telegram kanalı oluşturma ekranı yalnızca kanal kaydını açar ve bot bağlantısını kurmaz. Ekranda şu uyarı görünür: “Bu işlem yalnızca kanal kaydını oluşturur. Bot bağlantısının ayrıca kurulması gerekir; bu ekranda henüz bot bağlantısı kurulamıyor.” Bağlantıyı bu sayfadaki API çağrılarıyla kurun. Panelde kanalların nasıl göründüğü için Kanallar sayfasına bakın.

Bot oluşturma

Bot token’ını Telegram’ın BotFather botundan alırsınız. Bu adım Flextell dışındadır.

BotFather ile bot oluşturun

Telegram’da BotFather ile yeni bir bot oluşturun. Bot kullanıcı adını (@botadi) not edin.

Token'ı kaydedin

BotFather’ın verdiği token’ı güvenli bir yerde saklayın. Biçimi 123456789:ABC... şeklindedir: rakamlar, iki nokta, ardından harf, rakam, _ veya - karakterleri.

Yetkileri kontrol edin

Çağrıyı yapan kullanıcının klinikte Create:Channel izni olmalı ve uygulamanızın token’ı channels:write scope’unu taşımalıdır.

Bot token’ı bir paroladır. Flextell onu şifreli saklar ve hiçbir yanıtta geri döndürmez. Siz de günlüklerinize, sürüm kontrolüne veya istemci tarafı koduna yazmayın.

Kanalı bot token’ı ile oluşturma

Aşağıdaki endpoint’ler Telegram kanalıyla çalışır. Hepsi Authorization ve X-Tenant başlıklarını ister; bkz. Klinikler ve X-Tenant.

Metot	Endpoint	Açıklama	Scope	İzin
`POST`	`/api/v1/channels`	Telegram kanalı oluşturur ve botu bağlar.	`channels:write`	`Create:Channel`
`PUT`	`/api/v1/channels/{id}`	Botu değiştirir veya webhook ayarını günceller.	`channels:write`	`Update:Channel`
`GET`	`/api/v1/channels/{id}/telegram`	Kanalın bot bağlantısını gösterir.	`channels:read`	`View:Channel`

İstek alanları

Alan	Zorunlu	Açıklama
`type`	Evet	`telegram`. Kanal türü oluşturulduktan sonra değişmez.
`name`	Evet	En fazla 255 karakter. Flextell adı büyük harfe çevirerek kaydeder.
`bot_token`	Hayır	Yalnızca Telegram kanalında gönderilebilir. Biçimi `^\d+:[A-Za-z0-9_-]+$`. Biçim yanlışsa Telegram’a hiç gidilmeden `Bot token, BotFather'ın verdiği 123456789:ABC... biçiminde olmalı.` hatası döner.
`address`	`bot_token` yoksa evet	Göndermezseniz `@<bot kullanıcı adı>` (bulunamazsa bot kimliği) atanır.
`webhook_enabled`	Hayır	Varsayılan `true`. `false` gönderirseniz webhook kaydedilmez veya kaldırılır.
`webhook_base_url`	Hayır	`https` ile başlayan adres. Üretim ortamında yok sayılır; yalnızca test ortamlarında tünel adresi vermek içindir.
`is_active`	Hayır	Varsayılan `true`.
`ai_reply_mode`	Hayır	`auto`, `semi_auto`, `closed` veya `null`.

Örnek

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 '{
    "type": "telegram",
    "name": "Telegram Destek",
    "bot_token": "123456789:ABC-DEF_ornek"
  }'

const res = await fetch("https://app.flextell.ai/api/v1/channels", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "X-Tenant": "<tenant_id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "telegram",
    name: "Telegram Destek",
    bot_token: "123456789:ABC-DEF_ornek",
  }),
});

Başarılı yanıt 201 döner. Yanıt kısaltılmıştır; kanal nesnesinin tamamı Kanallar sayfasındadır.

{
  "success": true,
  "data": {
    "id": 123,
    "name": "TELEGRAM DESTEK",
    "type": "telegram",
    "provider": "telegram_bot_api",
    "address": "@botadi",
    "status": "open",
    "is_active": true
  }
}

Flextell sırasıyla şunları yapar ve hepsi tek işlemdir:

Token’ı Telegram’a sorarak (getMe) doğrular.
Webhook’u Telegram’a kaydeder.
Token’ı şifreleyerek kaydeder ve kanalı open yapar.

Adımlardan biri reddedilirse hiçbir şey oluşmaz; yarım kanal kalmaz.

Botu değiştirme

Aynı kanalın botunu değiştirmek için PUT /api/v1/channels/{id} ile yeni bot_token gönderin. bot_token, webhook_enabled ve webhook_base_url alanlarından herhangi biri botu aynı işlem içinde yeniden bağlar. Telegram isteği reddederse PUT isteğindeki hiçbir alan kaydedilmez.

Farklı bir bota geçerseniz eski botun webhook’u bırakılır.
Aynı botun token’ını yeniden ürettiyseniz webhook kaldırılmaz.
Webhook kaydı reddedilirse Flextell önceki webhook’u geri yüklemeyi dener.
Kanalda hiç token yoksa ve PUT isteği de token göndermiyorsa yeniden bağlanma CHANNEL_TELEGRAM_TOKEN_MISSING ile reddedilir.

Webhook

Telegram mesajları Flextell’e webhook ile iletir; başka bir alma yöntemi yoktur. Webhook’u siz kaydetmezsiniz: bot bağlandığında Flextell onu kendisi kurar.

Özellik	Değer
Adres	Flextell’in herkese açık HTTPS adresi altında `/webhook/telegram/{kanal_id}`
Doğrulama	Her kanal için Flextell’in ürettiği gizli anahtar; Telegram bunu `X-Telegram-Bot-Api-Secret-Token` başlığıyla gönderir. Yanlış anahtar `403` alır.
İletilen güncellemeler	`message`, `edited_message`, `message_reaction`
Pasif kanal	`404`

Bu adres Telegram’ın Flextell’i çağırması içindir. Uygulamanız bu adrese istek göndermez.

Mesaj akışını geçici olarak durdurmak için kanalı silmeyin. PUT /api/v1/channels/{id} ile "webhook_enabled": false gönderin. Webhook silinir, kanal open kalır ama mesaj almaz. Akışı yeniden başlatmak için "webhook_enabled": true gönderin.

Bağlantıyı doğrulama

Önce bağlantı durumunu API’den okuyun, ardından gerçek bir mesajla sınayın.

Bot bağlantısını okuma

curl https://app.flextell.ai/api/v1/channels/123/telegram \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

{
  "success": true,
  "data": {
    "has_bot_token": true,
    "bot_id": 123456789,
    "bot_username": "botadi",
    "webhook_enabled": true
  }
}

Alan	Tür	Açıklama
`has_bot_token`	boolean	Kanalda kayıtlı bir token olup olmadığı. Token’ın kendisi hiçbir zaman döndürülmez.
`bot_id`	integer \| null	Bağlı botun Telegram kimliği.
`bot_username`	string \| null	Bağlı botun kullanıcı adı.
`webhook_enabled`	boolean	Webhook’un açık olup olmadığı.

Telegram dışındaki bir kanal için bu endpoint 422 CHANNEL_NOT_TELEGRAM döner.

Mesajla sınama

Kanal durumunu kontrol edin

GET /api/v1/channels/{id} yanıtında status değeri open, is_active değeri true olmalıdır. Panelde durum Bağlı olarak görünür.

Bota yazın

Telegram’dan, botla birebir sohbetten bir mesaj gönderin.

Sohbeti bulun

Mesaj Flextell’de yeni bir sohbet olarak açılır. Kişi, Telegram sohbet kimliğiyle (Telegram chat ID) tanınır; adı ve soyadı Telegram profilinden alınır. Kliniğin etkin bir pipeline’ı varsa kişi için bir Lead de açılır.

Hatalar

Hata yanıtlarının genel yapısı için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`CHANNEL_TELEGRAM_TOKEN_INVALID`	422	Telegram token’ı reddetti. Hata `bot_token` alanındadır. BotFather’dan aldığınız token’ı kontrol edin.
`CHANNEL_TELEGRAM_WEBHOOK_REJECTED`	422	Telegram webhook adresini reddetti; adres herkese açık bir HTTPS URL olmalıdır. Test ortamlarında hata `webhook_base_url` alanındadır.
`CHANNEL_TELEGRAM_TOKEN_MISSING`	422	Token’ı olmayan kanalı token göndermeden yeniden bağlamaya çalıştınız. Hata `bot_token` alanındadır.
`CHANNEL_NOT_TELEGRAM`	422	`GET .../telegram` veya Telegram alanları Telegram olmayan bir kanala gönderildi.
`CHANNEL_PROVIDER_UNAVAILABLE`	502	Telegram yanıt vermedi, hız sınırı verdi (429) veya sunucu hatası döndü. Bir süre sonra yeniden deneyin.
`VALIDATION_FAILED`	422	Alanlar geçersiz: örneğin token biçimi, aynı ada sahip başka bir kanal (güncellemede) veya `address` eksik.

Kısıtlar

Yalnızca özel sohbetler

Flextell yalnızca botla birebir yapılan sohbetleri işler. Grup, süpergrup ve kanal güncellemeleri yok sayılır. Gelen içerik olarak metin, konum, kişi, fotoğraf, video, ses ve sesli mesaj, belge, mesaj düzenleme ve tepki (reaction) işlenir.

Sohbeti kullanıcı başlatır

Flextell Telegram’da kendisi sohbet başlatamaz. Hasta bota en az bir kez yazmalıdır; ondan sonra sohbet otomatik kaydedilir. Kullanıcı adıyla (@ad) mesaj gönderilemez, sayısal sohbet kimliği gerekir.

Mesaj ve dosya sınırları

Bir mesajın metni en fazla 4096 karakter olabilir. Desteklenen medya türleri JPEG, PNG, GIF, MP4, MPEG ve MP4 ses, OGG ve PDF’dir. Kendi gönderdiğiniz mesajı en fazla 48 saat içinde düzenleyebilir veya silebilirsiniz. Telegram’da okundu bilgisi yoktur.

Token olmadan oluşturulan kanal

bot_token göndermeden type: "telegram" ile kanal oluşturursanız yalnızca bir kayıt açılır. Bu kanal closed kalır ve mesaj almaz. address bu durumda zorunludur. Botu sonradan PUT ile bot_token göndererek bağlayabilirsiniz.

Kanal türü değişmez

Kanal oluşturulduktan sonra type değiştirilemez. PUT isteğindeki type değeri sessizce yok sayılır.

Kanalı silme

DELETE /api/v1/channels/{id} isteği gövdede kullanıcının current_password değerini ister; eksikse 422 VALIDATION_FAILED döner. Silme sırasında Telegram webhook’u da kaldırılır; bu adım en iyi çaba esaslıdır.

Telegram kanalı, Flextell’in desteklediği diğer entegrasyonlarla birlikte Entegrasyonlara genel bakış sayfasında anlatılır. Kanal nesnesinin tüm alanları ve diğer kanal endpoint’leri için Kanallar sayfasına, gereken scope’lar için Scope’lar sayfasına bakın.

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

Bot oluşturma

Kanalı bot token’ı ile oluşturma

İstek alanları

Örnek

Botu değiştirme

Webhook

Bağlantıyı doğrulama

Bot bağlantısını okuma

Mesajla sınama

Hatalar

Kısıtlar

​Bot oluşturma

​Kanalı bot token’ı ile oluşturma

​İstek alanları

​Örnek

​Botu değiştirme

​Webhook

​Bağlantıyı doğrulama

​Bot bağlantısını okuma

​Mesajla sınama

​Hatalar

​Kısıtlar

Bot oluşturma

Kanalı bot token’ı ile oluşturma

İstek alanları

Örnek

Botu değiştirme

Webhook

Bağlantıyı doğrulama

Bot bağlantısını okuma

Mesajla sınama

Hatalar

Kısıtlar