Geliştiriciler

Kimlik doğrulama ve kapsamlar

API anahtarı ya da OAuth erişim belirteciyle bağlanın; ne yapabileceğinizi kapsam ve anahtarı oluşturanın rolü birlikte belirler.

API anahtarı

Her istek Authorization: Bearer <api_key> başlığı taşır. Anahtarlar hb_live_ ön ekiyle başlar, panelde Ayarlar → API bölümünde oluşturulur, yalnız oluşturulduğu anda gösterilir ve sunucuda özetlenerek saklanır. Eksik ya da iptal edilmiş anahtar 401 unauthorized döner.

  • Anahtarı istemci tarafı koduna, tarayıcıya ya da depoya koymayın; sunucuda ortam değişkeninde tutun.
  • Sızdığını düşündüğünüz anahtarı panelden ya da revokeApiKey ile iptal edin; hemen çalışmaz olur.
  • Yeni anahtar yalnız panelde ve e-postası doğrulanmış kullanıcıyla üretilir: bir anahtarın kendinden geniş anahtar üretmesi güvenlik açığı olurdu.

Müşteriye mesaj gönderebilen anahtarı ya da izni verirken dikkatli olun. Örneklerdeki hb_live_YOUR_API_KEY gibi değerler yer tutucudur.

Erişim düzeyleri

Panelde anahtar oluştururken bir düzey seçersiniz; düzey aşağıdaki kapsam listesine karşılık gelir. Entegrasyonun ihtiyacı kadarını verin.

DüzeyKapsamlar
Tam erişim (okuma, yazma, mesaj gönderme)read write messages:send
Salt okumaread
Okuma + mesaj göndermeread messages:send
Tam erişim + bot yönetimi (bots:read, bots:write)read write messages:send bots:read bots:write
Salt okuma + bot ayarlarını okuma (bots:read)read bots:read
Tam yönetim (bütün kapsamlar: otomasyon, Mini App, kişi, sohbet, kampanya, topluluk, rapor, organizasyon, ekip, webhook, anahtar)Bütün kapsamlar (26)
Tam okuma (bütün kaynakları okuma, yazma yok)read bots:read automations:read miniapps:read contacts:read conversations:read campaigns:read communities:read reports:read organization:read team:read webhooks:read api_keys:read

Bütün kapsamlar

Kapsamı olmayan istek 403 scope döner. read ve write eski anahtarlarda da bulunur; kaynak kapsamları (contacts:read gibi) ayrıdır, böylece eski anahtarların yetkisi kendiliğinden genişlemez. Her ucun kapsamı API başvurusunda yazar.

KapsamNe sağlarUç
readTemel okuma: bot listesi, kişi, sohbet, mesaj, kampanya, Mini App, otomasyon, webhook, şablon, kullanım14
writeTemel yazma: kişi, izin, sohbet durumu, kampanya oluşturma, sipariş, otomasyon açma/kapama, webhook10
messages:sendMüşteriye mesaj gönderme2
bots:readBot ayarları, bilgi kaynakları, araçlar, sürümler, değerlendirmeler, edinme bağlantıları24
bots:writeBot oluşturma, güncelleme, kanala bağlama, silme ve AI bilgi yönetimi42
automations:readOtomasyon ayrıntısı ve çalıştırma geçmişi2
miniapps:readMini App, sürüm, sipariş ve özel talepleri okuma7
contacts:readKişi dışa aktarma, etiketler, özel alanlar3
conversations:readSohbet ayrıntısı, dahili notlar, hazır yanıtlar4
campaigns:readKampanya sonuçları, kitle sayımı, en iyi gönderim saati6
communities:readTopluluk, davet bağlantısı ve planlı gönderileri okuma6
reports:readGenel bakış, teslimat, temsilci, memnuniyet, AI kalitesi, gelir ve kullanım raporları8
organization:readOrganizasyon ayarları, içerik politikası, AI ayarları, mağaza, medya, denetim, abonelik10
team:readEkip üyeleri ve bekleyen davetler2
webhooks:readWebhook ayrıntısı ve teslim geçmişi2
api_keys:readAPI anahtarları ve bağlı uygulamaları listeleme3
automations:writeOtomasyon oluşturma, kaydetme, silme3
miniapps:writeMini App taslağı, yayın, geri alma ve özel talep işlemleri14
contacts:writeKişi ekleme, silme, içe aktarma, toplu işlem, etiket ve özel alan yönetimi14
conversations:writeAtama, erteleme, okundu, dahili not, hazır yanıt ve mesaj yeniden deneme12
campaigns:writeBaşlamamış kampanyayı güncelleme ve silme, kampanya maliyeti; onay bu kapsamda da verilemez9
communities:writeTopluluk, davet bağlantısı ve planlı gönderi yönetimi12
organization:writeOrganizasyon, içerik politikası, AI, mağaza ve medya değişiklikleri11
team:writeDavet, rol, bot erişimi ve üye çıkarma4
webhooks:writeWebhook güncelleme ve test olayı gönderme2
api_keys:writeAPI anahtarını iptal etme, bağlı uygulamayı kaldırma2

Rol davranışı

Kapsam yeterli olsa da işlem panelde hangi rolü istiyorsa API'de de onu ister; yetmezse 403 forbidden_role döner.

  • API anahtarı, anahtarı oluşturan kişinin güncel rolüyle çalışır: kişinin rolü değişirse anahtarın yetkisi de değişir.
  • Oluşturan kişi ekipten ayrıldıysa anahtar yönetici gibi çalışır; sahibe özel işlemler kapalı kalır. Bu anahtarı iptal edip yenisini üretmeniz önerilir.
  • Üye rolü yalnız erişebildiği botların verisini görür; erişemediği kayıt 404 döner.
  • OAuth belirteci, yetkiyi veren kullanıcının güncel üyeliğiyle çalışır; kullanıcı ekipten çıkarsa 403 forbidden_role döner.
İşlemÜyeYöneticiSahip
Okuma, mesaj ve sohbet işlemleri (erişebildiği botlarda)✓✓✓
Bot ayarları, kişi yönetimi, kampanya, otomasyon, Mini App, webhook—✓✓
Üye rolü değiştirme——✓
Bot silme (deleteBot)——✓

Her ucun rol şartı başvurudaki açıklamasında yazar. Kesin kural uçtaki denetimdir.

OAuth 2.1

Kullanıcının kendi hesabıyla yetki verdiği uygulamalar ve MCP istemcileri için. Yetkilendirme kodu akışı ve PKCE (S256) kullanılır; istemci kaydı dinamiktir ve istemci sırrı yoktur.

  • Sunucu bilgisini okuyun.
  • İstemcinizi kaydedin (/oauth/register); client_id döner. Yönlendirme adresi https ya da yerel http olmalıdır.
  • Kullanıcıyı PKCE ile yetki sayfasına yönlendirin. Kullanıcı giriş yapar, organizasyon seçer ve izin verir.
  • Dönen kodu belirteçle değiştirin (/oauth/token). scope boşsa yalnız read verilir.
Sunucu bilgisi
curl "https://hiboty.com/.well-known/oauth-authorization-server"
İstemci kaydı
curl -X POST "https://hiboty.com/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My App","redirect_uris":["https://ornek.com/oauth/callback"]}'
Yetki adresi
https://hiboty.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fornek.com%2Foauth%2Fcallback&scope=read%20messages%3Asend&state=RANDOM_STATE&code_challenge=PKCE_S256_CHALLENGE&code_challenge_method=S256
Kodu belirteçle değiştirme
curl -X POST "https://hiboty.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d client_id=CLIENT_ID \
  -d redirect_uri=https://ornek.com/oauth/callback \
  -d code_verifier=PKCE_VERIFIER
Belirteci kullanma
curl "https://hiboty.com/api/v1/bots" -H "Authorization: Bearer hb_oat_YOUR_ACCESS_TOKEN"

Erişim belirteci hb_oat_ ile başlar, 60 dakika geçerlidir ve API anahtarıyla aynı başlıkla kullanılır. Yenileme belirteci hb_ort_ ile başlar, 90 gün geçerlidir; grant_type=refresh_token ile yenilenir. Belirteçleri /oauth/revoke ile iptal edebilirsiniz; bağlı uygulamalar panelde Ayarlar → API bölümünde ve listConnectedApps ile görünür.