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

# Engellenen kullanıcılar

> Kanal engel listesini ve izin listesini API ile yönetmeyi anlatır.

Engel kaydı, bir hastanın belirli bir kanaldan (örneğin bir WhatsApp numarası) size mesaj göndermesini durdurur. Kayıt bir hasta ile bir kanal çiftine aittir: aynı çift için tek kayıt bulunur. Engelli hastanın bu kanaldan gelen mesajları işlenmez. Panelde aynı liste **Engellenen Kullanıcılar** sayfasında görünür; ekranı için [Engellenen kullanıcılar](/panel/sohbetler/engellenen-kullanicilar) sayfasına bakın.

Bu sayfa `/v1/channel-blacklists` endpoint'lerini anlatır. Kanal ve hasta kimlikleri için [Kanallar](/api/kaynaklar/kanallar) ve [Hastalar](/api/kaynaklar/hastalar) sayfalarına bakın.

## Endpoint özeti

Tüm isteklerde `Authorization` ve `X-Tenant` başlıkları gerekir. Başlıklar için [İstek başlıkları](/api/istekler/basliklar) sayfasına bakın.

| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| `GET` | `/v1/channel-blacklists` | Engel kayıtlarını listeler. | `channel_blacklists:read` | `View:ChannelBlacklist` |
| `POST` | `/v1/channel-blacklists` | Bir hastayı bir kanalda engeller. | `channel_blacklists:write` | `Create:ChannelBlacklist` |
| `GET` | `/v1/channel-blacklists/{id}` | Tek bir engel kaydını getirir. | `channel_blacklists:read` | `View:ChannelBlacklist` |
| `PUT` | `/v1/channel-blacklists/{id}` | Sebebi, notu veya bitiş zamanını günceller. | `channel_blacklists:write` | `Update:ChannelBlacklist` |
| `DELETE` | `/v1/channel-blacklists/{id}` | Engeli kaldırır. | `channel_blacklists:write` | `Engeli Kaldır` (`Unblock:ChannelBlacklist`) |

İzin etiketleri rol editöründe **Engellenen Numaralar** grubunun altında görünür. Hangi kayıtları göreceğiniz izinlere bağlıdır; ayrıntı için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.

<Info>
  `ViewAllChannelBlacklists:ChannelBlacklist` (**Tümünü Görüntüle**) iznine sahip olmayan kullanıcı yalnızca kendisine atanmış lead'in hastasına ait kayıtları görür, günceller ve kaldırır. Diğer kayıtlar için `403` değil `404` döner.
</Info>

## Kayıt nesnesi

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | tamsayı | Kayıt kimliği. |
| `reason` | metin | Engel sebebi. Aşağıdaki değerlerden biri. |
| `reason_label` | metin | Sebebin Türkçe etiketi. |
| `note` | metin, boş olabilir | Serbest not. |
| `blocked_at` | tarih-saat | Engelin başladığı an. |
| `expires_at` | tarih-saat, boş olabilir | Bitiş zamanı. Boşsa engel süresizdir. |
| `is_active` | mantıksal | Engelin geçerli olup olmadığı. |
| `is_permanent` | mantıksal | `expires_at` boşsa `true`. |
| `is_expired` | mantıksal | Süre dolmuşsa `true`. |
| `remaining_time` | metin | Kalan süre. Süresiz kayıtlarda `Kalıcı`, süresi dolmuşlarda `Süresi Dolmuş`. |
| `metadata` | nesne | İsteğe bağlı ek veri. |
| `channel` | nesne | `id`, `name`, `type`, `address`. |
| `customer` | nesne | Engellenen hasta. |
| `tenant_id`, `created_at`, `updated_at`, `deleted_at` | | Kayıt bilgileri. |

Sebep değerleri:

| `reason` | `reason_label` |
| - | - |
| `rate_limit` | Hız Limiti |
| `llm_spam` | LLM Spam |
| `manual` | Manuel |
| `security_threat` | Güvenlik Tehdidi |
| `abusive_language` | Hakaret/Küfür |

Sistem, kısa sürede çok fazla mesaj gönderen numaraları `rate_limit` sebebiyle kendisi de engelleyebilir. Bu kayıtlar listede sizin açtığınız kayıtlarla birlikte görünür.

## Listeleme

`GET /v1/channel-blacklists` sayfalı döner ve kayıtlarda `channel` ile `customer` bilgisi bulunur. Sayfalama için [Sayfalama](/api/istekler/sayfalama), sıralama kuralları için [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama) sayfasına bakın.

| Parametre | Açıklama |
| - | - |
| `per_page` | Sayfa boyutu, 1–100. Varsayılan 15. |
| `page` | Sayfa numarası. |
| `channel_id` | Belirli bir kanalın kayıtları. |
| `customer_id` | Belirli bir hastanın kayıtları. |
| `is_active` | Yalnızca geçerli (`true`) veya kaldırılmış (`false`) kayıtlar. |
| `sort_by` | `blocked_at`, `expires_at`, `created_at`, `updated_at`. Varsayılan `created_at`. |
| `sort_order` | `asc` veya `desc`. Varsayılan `desc`. |

## Engelleme

`POST /v1/channel-blacklists` bir hastayı bir kanalda engeller. Başarılı istek `201` ile kayıt nesnesini döner.

<ParamField body="channel_id" type="integer" required>
  Klinik kanalının kimliği.
</ParamField>

<ParamField body="customer_id" type="integer" required>
  Hastanın kimliği.
</ParamField>

<ParamField body="reason" type="string" required>
  `rate_limit`, `llm_spam`, `manual`, `security_threat` veya `abusive_language`.
</ParamField>

<ParamField body="ttl_seconds" type="integer">
  Engelin süresi, saniye cinsinden (en az 1). Göndermezseniz veya `null` gönderirseniz engel süresiz olur.
</ParamField>

<ParamField body="note" type="string">
  En fazla 1000 karakter.
</ParamField>

<ParamField body="metadata" type="object">
  İsteğe bağlı ek veri.
</ParamField>

```bash curl theme={null}
curl -X POST "https://app.flextell.ai/api/v1/channel-blacklists" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 45,
    "customer_id": 123,
    "reason": "manual",
    "note": "Tekrarlayan reklam mesajları"
  }'
```

Yanıttan kısaltılmış bir örnek:

```json theme={null}
{
  "id": 7,
  "reason": "manual",
  "reason_label": "Manuel",
  "note": "Tekrarlayan reklam mesajları",
  "blocked_at": "2026-10-12T14:30:00+03:00",
  "expires_at": null,
  "is_active": true,
  "is_permanent": true,
  "is_expired": false,
  "remaining_time": "Kalıcı"
}
```

<Warning>
  Yeni bir engel açıldığında, engellenen hastaya **Engel Bilgilendirme (Genel)** şablonuyla bir bilgilendirme mesajı gönderilir. Mesaj, seçtiğiniz sebebin açıklamasını içerir. Hastaya haber vermek istemiyorsanız engeli açmadan önce bunu göz önünde bulundurun.
</Warning>

Engelleme bir upsert gibi çalışır: aynı kanal ve hasta çifti için tekrar `POST` gönderirseniz yeni kayıt oluşmaz, mevcut kaydın `id` değeri döner. Silinmiş veya kaldırılmış kayıt yeniden etkinleşir. Mevcut süresiz bir kayda `ttl_seconds` ile tekrar istek gönderirseniz kayıt süreli olur. Mevcut süreli bir kayda yeni süre gönderirseniz, daha geç olan bitiş zamanı korunur.

Yeni, yeniden etkinleşen veya daha önce kaldırılmış bir kayıt için ayrıca şunlar olur:

* Hastanın bekleyen AI asistan işleri silinir.
* `CustomerBlacklisted` olayı yayınlanır (bkz. [Kanallar ve olaylar](/api/gercek-zamanli/kanallar-ve-olaylar)).

## Süreli engel

Süreli engel için `POST` isteğinde `ttl_seconds` gönderin. Süre dolunca kayıt otomatik olarak `is_active=false` olur; sistem bunu düzenli aralıklarla temizler.

Panelin süre seçenekleri ile karşılıkları:

| Panel seçeneği | `ttl_seconds` |
| - | - |
| 1 saat | `3600` |
| 24 saat | `86400` |
| 7 gün | `604800` |
| 30 gün | `2592000` |
| Süresiz | alanı göndermeyin |

Mevcut bir kaydın süresini `PUT` ile de değiştirebilirsiniz:

| Alan | Kural |
| - | - |
| `expires_at` | Gelecekte bir tarih-saat olmalıdır. `null` gönderirseniz kayıt süresiz olur. |
| `reason` | Sebep değerlerinden biri. |
| `note` | En fazla 1000 karakter, `null` olabilir. |
| `metadata` | Mevcut veriyle birleştirilir; üzerine yazmaz. |
| `is_active` | Mantıksal. `false` göndermek engeli kaldırır (bkz. aşağısı). |

```bash curl theme={null}
curl -X PUT "https://app.flextell.ai/api/v1/channel-blacklists/7" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"expires_at": "2026-11-12T14:30:00+03:00"}'
```

`PUT` istekleri hastaya bilgilendirme mesajı göndermez.

## Engeli kaldırma

Engeli kaldırmanın iki yolu vardır:

<Steps>
  <Step title="DELETE ile">
    `DELETE /v1/channel-blacklists/{id}` çağrısı kaydı silmez, `is_active` değerini `false` yapar ve `CustomerUnblacklisted` olayını yayınlar. Yanıt: `{"message": "Kanal kara liste kaydı başarıyla devre dışı bırakıldı"}`.
  </Step>

  <Step title="PUT ile">
    `PUT` isteğinde `is_active: false` gönderin. Sonuç aynıdır: gerçek bir engel kaldırma çalışır ve `CustomerUnblacklisted` yayınlanır.
  </Step>
</Steps>

<Warning>
  Her iki yol da `Engeli Kaldır` (`Unblock:ChannelBlacklist`) iznini ister. `PUT` ile kaldırmak için ayrıca `Update:ChannelBlacklist` gerekir. Yalnızca `Sil` iznine sahip olmak yetmez.
</Warning>

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

Kaldırılmış kayıt listede `is_active=false` olarak kalır. Aynı hastayı aynı kanalda yeniden engellemek için `POST` göndermeniz yeterlidir; kayıt yeniden etkinleşir.

## İzin listesi

Engelin tersi olan bir izin listesi (whitelist) için API'de endpoint yoktur. Bu listeyi API ile okuyamaz, ekleyemez veya silemezsiniz; ilgili izinler de rollere atanamaz. Canlı kullanımda uygulanan bir izin listesi özelliği bulunmaz.

Bir numaranın mesajlarını yeniden almak istiyorsanız engel kaydını kaldırın.

## Hatalar

| Durum | Ne zaman |
| - | - |
| `403` | Gerekli izin veya scope eksik. |
| `404` | Kayıt yok ya da görme yetkiniz yok. Mesaj: `Kanal kara liste kaydı bulunamadı`. |
| `422` | Alan doğrulaması başarısız: geçersiz `reason`, 1'den küçük `ttl_seconds`, geçmiş bir `expires_at` veya geçersiz `sort_by`. |

Genel hata biçimi için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın.


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