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/sdk

Paket 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.

hiboty.mjs
// 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çenekJavaScriptPythonVarsayılan
AnahtarapiKeyapi_keyzorunlu
Hata dililanglangTürkçe
Sunucu adresibaseUrlbase_urlhttps://hiboty.com
Zaman aşımıfetch ile kendiniztimeout30 sn (Python)
Özel fetchfetch—globalThis.fetch

Metot adları

  • JavaScript metotları OpenAPI operationId değeriyle aynıdır: listBots.
  • Python metotları snake_case karşılığıdır: list_bots. whatsApp gibi 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ışırsa govde={...} kullanın.
  • Kimlik (uuid) alan metotlar geçersiz kimliği istek atmadan TypeError ile 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