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

# Telegram

> Bir Telegram botunu bot token'ı ile API üzerinden Flextell kanalına bağlamayı anlatır.

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.

<Note>
  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](/panel/baglantilar/kanallar) sayfasına bakın.
</Note>

## Bot oluşturma

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

<Steps>
  <Step title="BotFather ile bot oluşturun">
    Telegram'da BotFather ile yeni bir bot oluşturun. Bot kullanıcı adını (`@botadi`) not edin.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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](/api/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

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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",
    }),
  });
  ```
</CodeGroup>

Başarılı yanıt `201` döner. Yanıt kısaltılmıştır; kanal nesnesinin tamamı [Kanallar](/api/kaynaklar/kanallar) sayfasındadır.

```json theme={null}
{
  "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:

1. Token'ı Telegram'a sorarak (`getMe`) doğrular.
2. Webhook'u Telegram'a kaydeder.
3. 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.

<Tip>
  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.
</Tip>

## 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

```bash theme={null}
curl https://app.flextell.ai/api/v1/channels/123/telegram \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"
```

```json theme={null}
{
  "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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Bota yazın">
    Telegram'dan, botla birebir sohbetten bir mesaj gönderin.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Hatalar

Hata yanıtlarının genel yapısı için [Hata kodları](/api/istekler/hata-kodlari) 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

Telegram kanalı, Flextell'in desteklediği diğer entegrasyonlarla birlikte [Entegrasyonlara genel bakış](/api/entegrasyonlar/genel-bakis) sayfasında anlatılır. Kanal nesnesinin tüm alanları ve diğer kanal endpoint'leri için [Kanallar](/api/kaynaklar/kanallar) sayfasına, gereken scope'lar için [Scope'lar](/api/kimlik-dogrulama/scopelar) sayfasına bakın.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.