Geliştiriciler
SDK'ler
Bağımlılıksız JavaScript ve Python istemcileri. Her uç için bir metot vardır; yeni uçlar SDK'ye kayıttan üretilir.
Kurulum
JavaScript: ESM, Node.js 18+ ve modern tarayıcılar. Python: 3.9+, yalnız standart kitaplık.
npm install @hiboty/sdkPaket yöneticisi olmadan
Tek dosyalık istemciyi doğrudan indirebilirsiniz. Node.js dosyayı .mjs uzantısıyla ESM olarak yükler; TypeScript için tipleri hiboty.d.mts adıyla yanına kaydedin.
// curl -o hiboty.mjs https://hiboty.com/sdk/hiboty.js
import { Hiboty, HibotyHatasi } from "./hiboty.mjs";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
console.log(typeof Hiboty, typeof HibotyHatasi, hiboty.rateLimit);Yapılandırma
API anahtarını tarayıcıda açığa çıkarmayın; istemciyi sunucu tarafında kullanın. hb_live_ ya da hb_oat_ ile başlamayan değer hemen reddedilir. Hız sınırı bilgisi son yanıttan rateLimit (Python: rate_limit) alanına yazılır.
import { Hiboty } from "@hiboty/sdk";
const hiboty = new Hiboty({
apiKey: process.env.HIBOTY_API_KEY, // hb_live_… ya da hb_oat_…
lang: "en", // hata mesajlarının dili: "tr" (varsayılan) ya da "en"
baseUrl: "https://hiboty.com",
});
const { data: bots } = await hiboty.listBots();
console.log(bots.length, hiboty.rateLimit); // { limit, remaining, reset }| Seçenek | JavaScript | Python | Varsayılan |
|---|---|---|---|
| Anahtar | apiKey | api_key | zorunlu |
| Hata dili | lang | lang | Türkçe |
| Sunucu adresi | baseUrl | base_url | https://hiboty.com |
| Zaman aşımı | fetch ile kendiniz | timeout | 30 sn (Python) |
| Özel fetch | fetch | — | globalThis.fetch |
Metot adları
- JavaScript metotları OpenAPI
operationIddeğeriyle aynıdır:listBots. - Python metotları snake_case karşılığıdır:
list_bots.whatsAppgibi bitişik adlar da böyle ayrılır:list_whats_app_templates. - JavaScript: yol parametreleri sırayla, gövde nesne olarak verilir:
updateBot(id, { name }). Sorgu parametresi olan metotlar tek nesne alır:listKnowledgeSources({ id, limit }). - Python: yol parametreleri sırayla, gövde alanları anahtar sözcükle verilir:
update_bot(id, name="x"). Python'da ayrılmış adlar alt çizgi alır (from_); gövde alanı çakışırsagovde={...}kullanın. - Kimlik (uuid) alan metotlar geçersiz kimliği istek atmadan
TypeErrorile reddeder.
Bot kurma örneği
Hızlı başlangıçtaki zincirin tamamı.
import { Hiboty } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
const { data: bot } = await hiboty.createBot({
name: "Mağaza Asistanı",
channel: "telegram",
template: "eticaret",
language: "tr",
});
console.log("bot", bot.id);
await hiboty.connectBot(bot.id, { token: process.env.TELEGRAM_BOT_TOKEN });
await hiboty.createKnowledgeSource(bot.id, {
type: "faq",
title: "Kargo süresi",
question: "Kargom ne zaman gelir?",
answer: "Siparişler 1-3 iş günü içinde kargoya verilir.",
});
const { data: test } = await hiboty.testBotReply(bot.id, {
messages: [{ role: "user", content: "Kargom ne zaman gelir?" }],
});
console.log("ai", test.reply);
const { data: automation } = await hiboty.createAutomation({
bot_id: bot.id,
name: "Fiyat sorusu",
trigger: "anahtar_kelime",
trigger_config: { kelimeler: ["fiyat"], eslesme: "icerir", aiBastir: true, tekrarGun: 0 },
steps: [{ tur: "mesaj", metin: "Fiyat listemiz: https://ornek.com/fiyat" }],
});
await hiboty.updateAutomation(automation.id, { active: true });
const { data: webhook } = await hiboty.createWebhook({
url: "https://ornek.com/hiboty-webhook",
events: ["message.received", "conversation.handoff"],
});
console.log("webhook secret", webhook.secret);
const { data: contacts } = await hiboty.listContacts({ bot_id: bot.id, limit: 1 });
if (contacts.length) {
const to = contacts[0].external_id;
const { id } = await hiboty.sendMessage({ bot_id: bot.id, to, message: "Merhaba!" }, { idempotencyKey: `welcome-${to}` });
console.log("message", id);
}
Hata yakalama
2xx dışı her yanıt HibotyHatasi olarak fırlatılır: status, code, message, retryAfter (Python: retry_after) ve body.
import { Hiboty, HibotyHatasi } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
try {
await hiboty.createCampaign({ bot_id: process.env.BOT_ID, name: "Kasım", body: "Merhaba {{ad}}" });
} catch (err) {
if (err instanceof HibotyHatasi) {
console.error(err.status, err.code, err.message, err.retryAfter);
} else {
throw err;
}
}Sayfalama
paginate sayfalı listeleri sonuna kadar dolaşır; 41 liste ucunun hepsinde çalışır. Tek sayfa için metodu doğrudan çağırın.
import { Hiboty } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
for await (const contact of hiboty.paginate("listContacts", { limit: 100 })) {
console.log(contact.name, contact.consent);
}
const firstPage = await hiboty.listContacts({ limit: 50 });
if (firstPage.next_cursor) {
const nextPage = await hiboty.listContacts({ limit: 50, cursor: firstPage.next_cursor });
console.log(nextPage.data.length);
}Idempotency
Yeniden denemede çift işlemi önlemek için idempotencyKey (Python: idempotency_key) verin; destekleyen metotlar başvuruda işaretlidir.
import { Hiboty } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
await hiboty.sendMessage(
{ bot_id: process.env.BOT_ID, to: "123456789", message: "Merhaba!" },
{ idempotencyKey: "order-10482" },
);Bağlantılar
OpenAPI belgesi: https://hiboty.com/api/v1/openapi.json
npm: @hiboty/sdk, PyPI: hiboty