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

> Flextell'in Telegram Bot API entegrasyonu — API'den mesaj okumak, göndermek ve medya işlemek.

Flextell, Telegram kanallarını doğrudan [Telegram Bot API](https://core.telegram.org/bots/api) üzerinden yönetir. Her tenant kendi **bot token**'ını panelden girer; Flextell, botun webhook adresini otomatik olarak `POST /webhook/telegram/{channel}` endpoint'ine kurar.

<Note>
  Telegram üzerinden konuşmak için hastanın **Telegram'ı yüklemiş ve botunuzu başlatmış** olması gerekir (`/start`). Bot'u başlatmadan hastayla ilk mesajı **siz** atamazsınız — bu Telegram politikasıdır, Flextell'in kısıtı değildir.
</Note>

## Kanal verisi

Telegram kanalı `GET /v1/channels` yanıtında şu şekilde görünür:

```json theme={null}
{
  "id": 5,
  "tenant_id": 12,
  "name": "Destek Botu",
  "type": "telegram",
  "address": "@klinik_destek_bot",
  "status": "connected",
  "is_active": true
}
```

<ResponseField name="address" type="string">
  Botunuzun Telegram kullanıcı adı (`@` ile başlar). Hastanızın ulaşması için paylaşacağınız değer.
</ResponseField>

## Hastanın bot'u başlatması

1. Hasta Telegram'da botunuzu açar (örn. `t.me/klinik_destek_bot`).
2. **Start** butonuna tıklar.
3. Telegram, Flextell webhook'una `/start` mesajını gönderir.
4. Flextell, Telegram profil bilgisiyle yeni bir `customer` oluşturur (veya eşleşen varsa günceller) ve bir `conversation` açar.
5. `ChatLogCreated` event'i tetiklenir.

Bu andan itibaren API üzerinden hastaya mesaj göndermeye başlayabilirsiniz.

## Metin mesajı gönderme

Telegram konuşmasına metin göndermek WhatsApp ile aynı endpoint'i kullanır:

```bash theme={null}
curl --request POST \
  --url https://dev.flextell.ai/api/v1/conversations/77/messages \
  --header "Authorization: Bearer $TOKEN" \
  --header "X-Tenant: 12" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "Merhaba, Flextell destek ekibine hoş geldiniz."
  }'
```

Flextell, `conversation.channel_type` değerini görerek mesajı Telegram Bot API'ye iletir.

### Emoji ve biçimlendirme

* Düz metin göndermek varsayılan davranıştır.
* Telegram'ın `Markdown` / `HTML` biçimlendirmesi desteklenmez — `body` olduğu gibi iletilir. Kalın/italik metin için kullanıcıya okunabilir bir metin tercih edin.
* Emoji `body` içinde doğrudan kullanılabilir (`"Merhaba 👋"`).

## Medya gönderme

```bash theme={null}
curl --request POST \
  --url https://dev.flextell.ai/api/v1/conversations/77/messages/media \
  --header "Authorization: Bearer $TOKEN" \
  --header "X-Tenant: 12" \
  --form "file=@/path/to/bill.pdf" \
  --form "caption=Mart ayı faturanız"
```

### Desteklenen medya türleri

| Kategori  | Telegram sınıfı    | Maks. boyut (Telegram)                           |
| --------- | ------------------ | ------------------------------------------------ |
| Görsel    | `photo`            | 10 MB                                            |
| Belge     | `document`         | 50 MB (Telegram Bot API) / 2 GB (Premium botlar) |
| Ses       | `audio`            | 50 MB                                            |
| Video     | `video`            | 50 MB                                            |
| Sesli not | `voice` (OGG Opus) | 50 MB                                            |

<Note>
  Flextell'in kendi `/v1/files` yüklemesi 50 MB sınırındadır; Telegram tarafına bu boyuta kadar gönderim yapılabilir.
</Note>

## Gelen mesajlar

Hasta Telegram'dan metin yazdığında:

```json theme={null}
{
  "id": 2007,
  "conversation_id": 77,
  "sender_type": "customer",
  "sender_id": 421,
  "body": "Rapor için randevu alabilir miyim?",
  "media_type": null,
  "created_at": "2026-04-19T11:02:00+03:00"
}
```

Hasta ses kaydı gönderirse `media_type` `audio`, fotoğraf gönderirse `image` olur. Dosyayı Flextell, Telegram'dan indirip `/files/{id}` endpoint'ine ayna olarak kaydeder; istemciniz yine Flextell üzerinden `download_url` ile indirir — **doğrudan Telegram dosya ID'si ile çağrı yapmanıza gerek yoktur**.

## Okundu olarak işaretleme

```bash theme={null}
POST /v1/conversations/77/read
```

Telegram Bot API "okundu" sinyali özelliği sunmaz; dolayısıyla bu çağrı **yalnızca Flextell tarafında** badge'i düşürür ve [`ConversationRead`](/realtime/events#conversationread) event'i tetikler. Hasta uygulamasında "görüldü" bilgisi Telegram protokolü gereği görünmez.

## Bot token değişikliği

Tenant, bot token'ını panelde değiştirdiğinde Flextell webhook'u otomatik olarak yeniden kurar. Eski token geçersiz olduğundan süreç aşağıdaki gibi çalışır:

1. Panel'de yeni token girilir.
2. Flextell eski webhook'u siler.
3. Yeni token ile webhook `/webhook/telegram/{channel}`'a kurulur.
4. `status` değeri `connected` olur.

Bu süre içinde `status` geçici olarak `connecting` görünebilir.

## Sınırlamalar

* **İlk mesajı bot başlatmak zorundadır** — hasta en az bir kere `/start` yazmalıdır.
* **Grup sohbetleri** desteklenmez; yalnızca hasta ↔ bot birebir sohbetleri takip edilir.
* **Inline keyboard / callback button** özellikleri şu an API tarafından gönderim için desteklenmez.
* **Silme senkronizasyonu kısıtlı**: Telegram'da hastanın sildiği bir mesaj Flextell'de otomatik silinmez. Flextell tarafında silme yaparsanız (panel/API), Telegram mesajı botun o mesajına sahip olduğu sürece silinir.

## Sonraki adımlar

<CardGroup cols={2}>
  <Card title="Mesaj gönderme" icon="paper-plane" href="/guides/send-message">
    İlk Telegram mesajınızı göndermek için adım adım rehber.
  </Card>

  <Card title="Realtime events" icon="bolt" href="/realtime/events">
    Hastanın yanıtını anlık yakalayın.
  </Card>
</CardGroup>