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
revokeApiKeyile 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üzey | Kapsamlar |
|---|---|
| Tam erişim (okuma, yazma, mesaj gönderme) | read write messages:send |
| Salt okuma | read |
| Okuma + mesaj gönderme | read 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.
| Kapsam | Ne sağlar | Uç |
|---|---|---|
read | Temel okuma: bot listesi, kişi, sohbet, mesaj, kampanya, Mini App, otomasyon, webhook, şablon, kullanım | 14 |
write | Temel yazma: kişi, izin, sohbet durumu, kampanya oluşturma, sipariş, otomasyon açma/kapama, webhook | 10 |
messages:send | Müşteriye mesaj gönderme | 2 |
bots:read | Bot ayarları, bilgi kaynakları, araçlar, sürümler, değerlendirmeler, edinme bağlantıları | 24 |
bots:write | Bot oluşturma, güncelleme, kanala bağlama, silme ve AI bilgi yönetimi | 42 |
automations:read | Otomasyon ayrıntısı ve çalıştırma geçmişi | 2 |
miniapps:read | Mini App, sürüm, sipariş ve özel talepleri okuma | 7 |
contacts:read | Kişi dışa aktarma, etiketler, özel alanlar | 3 |
conversations:read | Sohbet ayrıntısı, dahili notlar, hazır yanıtlar | 4 |
campaigns:read | Kampanya sonuçları, kitle sayımı, en iyi gönderim saati | 6 |
communities:read | Topluluk, davet bağlantısı ve planlı gönderileri okuma | 6 |
reports:read | Genel bakış, teslimat, temsilci, memnuniyet, AI kalitesi, gelir ve kullanım raporları | 8 |
organization:read | Organizasyon ayarları, içerik politikası, AI ayarları, mağaza, medya, denetim, abonelik | 10 |
team:read | Ekip üyeleri ve bekleyen davetler | 2 |
webhooks:read | Webhook ayrıntısı ve teslim geçmişi | 2 |
api_keys:read | API anahtarları ve bağlı uygulamaları listeleme | 3 |
automations:write | Otomasyon oluşturma, kaydetme, silme | 3 |
miniapps:write | Mini App taslağı, yayın, geri alma ve özel talep işlemleri | 14 |
contacts:write | Kişi ekleme, silme, içe aktarma, toplu işlem, etiket ve özel alan yönetimi | 14 |
conversations:write | Atama, erteleme, okundu, dahili not, hazır yanıt ve mesaj yeniden deneme | 12 |
campaigns:write | Başlamamış kampanyayı güncelleme ve silme, kampanya maliyeti; onay bu kapsamda da verilemez | 9 |
communities:write | Topluluk, davet bağlantısı ve planlı gönderi yönetimi | 12 |
organization:write | Organizasyon, içerik politikası, AI, mağaza ve medya değişiklikleri | 11 |
team:write | Davet, rol, bot erişimi ve üye çıkarma | 4 |
webhooks:write | Webhook güncelleme ve test olayı gönderme | 2 |
api_keys:write | API anahtarını iptal etme, bağlı uygulamayı kaldırma | 2 |
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
404döner. - OAuth belirteci, yetkiyi veren kullanıcının güncel üyeliğiyle çalışır; kullanıcı ekipten çıkarsa
403 forbidden_roledöner.
| İşlem | Üye | Yönetici | Sahip |
|---|---|---|---|
| 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_iddö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).scopeboşsa yalnızreadverilir.
curl "https://hiboty.com/.well-known/oauth-authorization-server"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"]}'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=S256curl -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_VERIFIERcurl "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.