API başvurusu

Topluluklar

Bu gruptaki 8 uç.

Telegram topluluklarını listeler

GET/api/v1/communities

Botun eklendiği gruplar ve kanallar, en yeni önce. Üye rolünde yalnız erişebildiği botların toplulukları döner. Kapsam: communities:read.

Kapsam
communities:read
SDK metodu
listCommunities · list_communities
MCP aracı
listCommunitiessalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
bot_idsorguuuidhayırYalnız bu bot
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 50); tam sayı değilse 400val 1–200, default 50
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/communities?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_name": "string",
      "bot_username": "string",
      "chat_id": "string",
      "type": "string",
      "title": "Örnek",
      "username": "ayse",
      "bot_status": "string",
      "member_count": 1,
      "last_activity_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Topluluk ayrıntısı

GET/api/v1/communities/{id}

Ayarlar, moderasyon kuralları, botun durumu ve izinleri, üye sayısı ve forum konuları. Bot jetonu dönmez. Kapsam: communities:read.

Kapsam
communities:read
SDK metodu
getCommunity · get_community
MCP aracı
getCommunitysalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_name": "string",
    "bot_username": "string",
    "chat_id": "string",
    "type": "string",
    "title": "Örnek",
    "username": "ayse",
    "bot_status": "string",
    "member_count": 1,
    "last_activity_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot_permissions": {
      "key": true
    },
    "welcome_enabled": true,
    "welcome_message": "string",
    "welcome_delete_after_sec": 1,
    "ai_enabled": true,
    "ai_hourly_limit": 1,
    "join_request_mode": "manual",
    "join_request_message": "string",
    "join_request_button": "string",
    "join_approved_message": "string",
    "rules": {
      "block_links": true,
      "block_forwards": true,
      "banned_words": [
        "string"
      ],
      "flood_count": 1,
      "flood_seconds": 1,
      "action": "delete",
      "exempt_admins": true
    },
    "forum_topics": [
      {
        "id": 1,
        "name": "Hiboty"
      }
    ],
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Topluluk ayarlarını günceller

PATCH/api/v1/communities/{id}

Yalnız gönderilen alanlar değişir; rules içinde de yalnız gönderilen kurallar değişir. Karşılama açıkken mesaj boş olamaz; verify modunda katılım mesajı ve butonu gerekir. Botta eksik yetki kaydı engellemez, warnings dizisinde bildirilir. Yönetici yetkisi gerekir. Kapsam: communities:write.

Kapsam
communities:write
SDK metodu
updateCommunity · update_community
MCP aracı
updateCommunity

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
welcome_enabledbooleanhayır
welcome_messagestringhayırlen ≤ 1000
welcome_delete_after_secenumhayır0 | 60 | 300 | 1800 | 3600
ai_enabledbooleanhayır
ai_hourly_limitintegerhayırval 1–500
join_request_modeenumhayırmanual | approve | verify
join_request_messagestringhayırlen ≤ 1000
join_request_buttonstringhayırlen ≤ 64
join_approved_messagestringhayırlen ≤ 1000
rulesobjecthayır
rules.block_linksbooleanhayır
rules.block_forwardsbooleanhayır
rules.banned_wordsstring[]hayırVirgül ya da satır sonu içeren öğe birden çok kelimeye bölünüritems ≤ 200
rules.flood_countintegerhayırval 0–50
rules.flood_secondsintegerhayırval 3–300
rules.actionenumhayırdelete | warn | mute
rules.exempt_adminsbooleanhayır

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome_enabled":true,"welcome_message":"Hoş geldin {{isim}}!","rules":{"block_links":true,"flood_count":5,"flood_seconds":10,"action":"warn"}}'

Örnek yanıt (200)

JSON
{
  "data": {
    "community": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_name": "string",
      "bot_username": "string",
      "chat_id": "string",
      "type": "string",
      "title": "Örnek",
      "username": "ayse",
      "bot_status": "string",
      "member_count": 1,
      "last_activity_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z",
      "bot_permissions": {
        "key": true
      },
      "welcome_enabled": true,
      "welcome_message": "string",
      "welcome_delete_after_sec": 1,
      "ai_enabled": true,
      "ai_hourly_limit": 1,
      "join_request_mode": "manual",
      "join_request_message": "string",
      "join_request_button": "string",
      "join_approved_message": "string",
      "rules": {
        "block_links": true,
        "block_forwards": true,
        "banned_words": [
          "string"
        ],
        "flood_count": 1,
        "flood_seconds": 1,
        "action": "delete",
        "exempt_admins": true
      },
      "forum_topics": [
        {
          "id": 1,
          "name": "Hiboty"
        }
      ],
      "updated_at": "2026-11-06T09:00:00.000Z"
    },
    "warnings": [
      {
        "code": "ornek",
        "message": "string"
      }
    ]
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Topluluğu kaldırır

DELETE/api/v1/communities/{id}

Topluluk kaydı, planlı gönderileri, davet bağlantıları ve istatistikleri silinir; bot Telegram grubundan çıkarılmaz. Yönetici yetkisi gerekir. Kapsam: communities:write.

Kapsam
communities:write
SDK metodu
removeCommunity · remove_community
MCP aracı
removeCommunitygeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Üye sayısını Telegram'dan yeniler

POST/api/v1/communities/{id}/refresh-members

Telegram'a istek gider. Üye rolü de çağırabilir, ama bota erişimi olmalıdır. Telegram hatası 502 channel_error döner; bot bağlı değilse 409 not_connected. Kapsam: communities:write.

Kapsam
communities:write
SDK metodu
refreshCommunityMembers · refresh_community_members
MCP aracı
refreshCommunityMembersdış etkili

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
Idempotency-Keybaşlıkstringhayırİsteğe bağlı, 1-255 görünür ASCII karakter. Aynı anahtar ve gövdeyle 24 saat içinde ilk yanıt aynen döner; farklı gövdede 409 idempotency_conflict.len 1–255

Örnek istek

curl -X POST "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/refresh-members" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "member_count": 1
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.not_connected
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.
  • 502Kanal ya da dış servis hatası (channel_error).channel_error