API başvurusu

Mini App

Bu gruptaki 18 uç.

Mini App'leri listele

GET/api/v1/miniapps

Kapsam
read
SDK metodu
listMiniApps · list_mini_apps
MCP aracı
listMiniAppssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
bot_idsorguuuidhayırYalnız bu bot
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 100); tam sayı değilse 400val 1–200, default 100
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak; eski date-time imleçleri de kabul edilir)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/miniapps?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",
      "name": "Hiboty",
      "slug": "string",
      "template": "string",
      "status": "string",
      "url": "https://example.com/hook",
      "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.

Mini App oluşturur

POST/api/v1/miniapps

Şablonun hazır taslağıyla, yayınlanmamış başlar. Bot kanala bağlı olmalıdır (409 not_connected). form_preset yalnız form şablonunda kullanılır. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
createMiniApp · create_mini_app
MCP aracı
createMiniApp

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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

Gövde alanları

AdTürZorunluAçıklama
bot_iduuidevet
namestringevetlen 2–60
templateenumevetkatalog | form | baglanti
form_presetenumhayıriletisim | randevu | anket | basvuru | bos

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","name":"Randevu formu","template":"form","form_preset":"randevu"}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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).
  • 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.

Mini App gönderimleri ve siparişleri

GET/api/v1/miniapps/{id}/submissions

Kapsam
read
SDK metodu
listMiniAppSubmissions · list_mini_app_submissions
MCP aracı
listMiniAppSubmissionssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
idyoluuidevetMini App kimliği
kindsorguenumhayırTür süzgeci (randevu ve iptal_talebi AI talep araçlarından gelir)form | order | randevu | iptal_talebi
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; eski date-time imleçleri de kabul edilir)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/submissions?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "kind": "form",
      "status": "string",
      "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_name": "string",
      "data": {},
      "source": "string",
      "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.
  • 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.

Sipariş ayrıntısı

GET/api/v1/orders/{id}

Ödemenin teslimat içeriği ve Telegram tahsilat kimliği dönmez. Kapsam: miniapps:read.

Kapsam
miniapps:read
SDK metodu
getOrder · get_order
MCP aracı
getOrdersalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

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

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "mini_app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "mini_app_name": "string",
    "status": "yeni",
    "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_name": "string",
    "data": {},
    "source": "string",
    "payment": {
      "status": "pending",
      "method": "telegram_stars",
      "currency": "USD",
      "amount": 1,
      "amount_stars": 1
    },
    "status_updated_at": "2026-11-06T09:00:00.000Z",
    "created_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.

Sipariş durumunu değiştir

PATCH/api/v1/orders/{id}

notify true ise müşteriye bot üzerinden durum mesajı gider; bunun için messages:send kapsamı da gerekir. Durum değişip bildirim gidemezse yanıt yine 200'dür ve data.notification { sent: false, error } içerir. Kapsam: write.

Kapsam
write
SDK metodu
updateOrder · update_order
MCP aracı
updateOrderdış etkili

Parametreler

AdTürZorunluAçıklama
idyoluuidevetSipariş (gönderim) kimliği

Gövde alanları

AdTürZorunluAçıklama
statusenumevetyeni | hazirlaniyor | tamamlandi | iptal
notifybooleanhayırdefault false

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"hazirlaniyor","notify":true}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "string",
    "notification": {
      "sent": false,
      "error": "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.

Mini App ayrıntısı

GET/api/v1/miniapps/{id}

Taslak, yayındaki sürüm ve menü düğmesi durumuyla döner. Üye rolü yalnız erişebildiği botların uygulamalarını görür. Kapsam: miniapps:read.

Kapsam
miniapps:read
SDK metodu
getMiniApp · get_mini_app
MCP aracı
getMiniAppsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/miniapps/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",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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.

Taslağı günceller

PATCH/api/v1/miniapps/{id}

Yayındaki sürüm değişmez; değişiklik yayınlanınca görünür. config şablon şemasına uymalıdır, uymazsa 400 miniapp_invalid döner. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
updateMiniAppDraft · update_mini_app_draft
MCP aracı
updateMiniAppDraft

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
namestringhayırlen 2–60
configobjecthayır

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Menü","config":{"baslik":"Menü","urunler":[{"id":"urun1","ad":"Kahve","fiyat":"90 TL"}]}}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).miniapp_invalid
  • 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.

Mini App'i siler

DELETE/api/v1/miniapps/{id}

Uygulama, sürümleri ve gönderimleri geri alınamaz biçimde silinir; menü düğmesine bağlıysa Telegram menüsü varsayılana döner. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
deleteMiniApp · delete_mini_app
MCP aracı
deleteMiniAppdış etkiligeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/miniapps/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.

Taslağı yayınlar

POST/api/v1/miniapps/{id}/publish

Taslaktan yeni değişmez sürüm oluşur ve herkese açılır; yayın onayı açıksa sürüm onay bekler ve yayındaki sürüm değişmez. Plan Mini App içermiyorsa 403 plan_limit, taslak geçersizse 400 miniapp_invalid döner. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
publishMiniApp · publish_mini_app
MCP aracı
publishMiniAppdış 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/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/publish" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).miniapp_invalid
  • 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.plan_limit
  • 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.

Yayından kaldırır

POST/api/v1/miniapps/{id}/unpublish

Herkese açık sayfa kapanır; menü düğmesine bağlıysa Telegram menüsü varsayılana döner. Sürümler silinmez. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
unpublishMiniApp · unpublish_mini_app
MCP aracı
unpublishMiniAppdış 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/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/unpublish" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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.

Önceki sürüme döner

POST/api/v1/miniapps/{id}/rollback

Verilen sürüm yeniden yayına alınır, taslak değişmez. Plan Mini App içermiyorsa 403 plan_limit döner; sürüm bu uygulamanın değilse 404. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
rollbackMiniApp · rollback_mini_app
MCP aracı
rollbackMiniAppdış 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

Gövde alanları

AdTürZorunluAçıklama
version_iduuidevet

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/rollback" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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.plan_limit
  • 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.

Telegram menü düğmesini ayarlar

POST/api/v1/miniapps/{id}/menu-button

enabled true botun menü düğmesini bu uygulamaya bağlar (uygulama yayında olmalı), false varsayılana döndürür. Bir botun tek menü düğmesi olur. Yayında değilse ya da bot bağlı değilse 409, Telegram reddederse 502 döner. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
setMiniAppMenuButton · set_mini_app_menu_button
MCP aracı
setMiniAppMenuButtondış 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

Gövde alanları

AdTürZorunluAçıklama
enabledbooleanevet

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/menu-button" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.
  • 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).

Sürümleri listeler

GET/api/v1/miniapps/{id}/versions

Sürümler, en yeni önce. Yayın onayı bekleyen ve reddedilen sürümler status alanıyla ayrılır. Kapsam: miniapps:read.

Kapsam
miniapps:read
SDK metodu
listMiniAppVersions · list_mini_app_versions
MCP aracı
listMiniAppVersionssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
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/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "is_published": true,
      "created_at": "2026-11-06T09:00:00.000Z",
      "config_sha256": "string",
      "status": "published"
    }
  ],
  "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.
  • 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.

Taslak önizlemesi

GET/api/v1/miniapps/{id}/preview

Taslağı gösteren, 2 saat geçerli imzalı adres ve taslak yapılandırma döner. Adresi yalnız güvendiğiniz kişilerle paylaşın. Taslak geçersizse valid false olur ve errors doldurulur. Kapsam: miniapps:read.

Kapsam
miniapps:read
SDK metodu
getMiniAppPreview · get_mini_app_preview
MCP aracı
getMiniAppPreviewsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

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

Örnek yanıt (200)

JSON
{
  "data": {
    "url": "https://example.com/hook",
    "expires_at": "2026-11-06T09:00:00.000Z",
    "valid": true,
    "errors": [
      "string"
    ],
    "config": {}
  }
}

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.

Siparişleri listeler

GET/api/v1/orders

En yeni önce. Üye rolü yalnız erişebildiği botların siparişlerini görür. Telegram Stars iadesi API'de yoktur: geri alınamaz para hareketi olduğu için panelde yapılır. Kapsam: miniapps:read.

Kapsam
miniapps:read
SDK metodu
listOrders · list_orders
MCP aracı
listOrderssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
statussorguenumhayırSipariş durumuyeni | hazirlaniyor | tamamlandi | iptal
app_idsorguuuidhayırYalnız bu Mini App
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/orders?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "mini_app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "mini_app_name": "string",
      "status": "yeni",
      "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_name": "string",
      "data": {},
      "source": "string",
      "payment": {
        "status": "pending",
        "method": "telegram_stars",
        "currency": "USD",
        "amount": 1,
        "amount_stars": 1
      },
      "status_updated_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.

Ürün beslemesini kataloğa aktarır

POST/api/v1/miniapps/{id}/feed-import

Google Merchant XML/RSS, CSV ya da JSON beslemesini katalog şablonlu Mini App'in taslağına aktarır; yalnız url ya da content verilir. İlk 50 ürün alınır, fazlası warnings içinde bildirilir; aynı kimlikli ürünlerin yıldız fiyatı ve teslimat içeriği korunur. Yayındaki sürüm değişmez, yayın elle yapılır. dry_run true ise yalnız önizleme döner. auto_refresh true ise adres saklanır ve taslak günde bir yenilenir. ai_knowledge true ise katalog botun AI bilgi kaynağına da yazılır. Adres herkese açık olmalıdır; iç ağ adresleri 400 feed_invalid döner. Saatte en fazla 30 istek. Yönetici yetkisi gerekir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
importMiniAppFeed · import_mini_app_feed
MCP aracı
importMiniAppFeeddış etkiligeri alınamaz

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

Gövde alanları

AdTürZorunluAçıklama
urlstringhayırHerkese açık http/https besleme adresilen ≤ 2000
contentstringhayırBeslemenin kendisi (dosya içeriği)len ≤ 2000000
formatenumhayırVerilmezse içerikten tahmin edilirxml | csv | json
dry_runbooleanhayır
auto_refreshbooleanhayır
ai_knowledgebooleanhayır

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/feed-import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example.com/feeds/google.xml","dry_run":false,"auto_refresh":true,"ai_knowledge":true}'

Örnek yanıt (200)

JSON
{
  "data": {
    "saved": true,
    "format": "xml",
    "mapping": {
      "id": "string",
      "ad": "string",
      "aciklama": "string",
      "fiyat": "string",
      "gorsel": "string",
      "stok": "string"
    },
    "total": 1,
    "imported": 1,
    "warnings": [
      {
        "code": "kesildi",
        "count": 1,
        "message": "string"
      }
    ],
    "products": [
      {
        "id": "string",
        "name": "Hiboty",
        "price": "string",
        "image_url": "https://example.com/a.png"
      }
    ],
    "feed": {
      "url": "https://example.com/hook",
      "auto_refresh": true,
      "ai_knowledge": true,
      "synced_at": "2026-11-06T09:00:00.000Z",
      "checked_at": "2026-11-06T09:00:00.000Z",
      "error": "string"
    }
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).feed_invalid
  • 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.
  • 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.

Onay bekleyen Mini App sürümünü yayınlar

POST/api/v1/miniapps/{id}/versions/{version_id}/approve

İçerik özeti (config_sha256) doğrulanır ve sürüm yayına girer; özet tutmazsa 409 integrity döner. Plan Mini App içermiyorsa 403 plan_limit. Yönetici yetkisi gerekir. Dört göz açıkken değişikliği yapan kişi onaylayamaz (403 four_eyes); API anahtarıyla onay verilemez. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
approveMiniAppVersion · approve_mini_app_version
MCP aracı
approveMiniAppVersiondış etkili

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
version_idyoluuidevetversion_id kimliği

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/approve" \
  -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",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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.plan_limitfour_eyes
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.integrity
  • 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.

Onay bekleyen Mini App sürümünü reddeder

POST/api/v1/miniapps/{id}/versions/{version_id}/reject

Sürüm yayına girmez; yönetici ya da yayını isteyen kişi reddedebilir. Kapsam: miniapps:write.

Kapsam
miniapps:write
SDK metodu
rejectMiniAppVersion · reject_mini_app_version
MCP aracı
rejectMiniAppVersion

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
version_idyoluuidevetversion_id kimliği

Örnek istek

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/reject" \
  -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",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "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.