Developers

SDKs

Dependency-free JavaScript and Python clients. There is a method for every endpoint; new endpoints are generated into the SDKs from the registry.

Installation

JavaScript: ESM, Node.js 18+ and modern browsers. Python: 3.9+, standard library only.

npm install @hiboty/sdk

Without a package manager

You can download the single-file client directly. Node.js loads the file as ESM through the .mjs extension; for TypeScript, save the types next to it as hiboty.d.mts.

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);

Configuration

Don't expose your API key in the browser; use the client server-side. A value that doesn't start with hb_live_ or hb_oat_ is rejected right away. Rate limit details from the last response go to rateLimit (Python: rate_limit).

import { Hiboty } from "@hiboty/sdk";

const hiboty = new Hiboty({
  apiKey: process.env.HIBOTY_API_KEY, // hb_live_… or hb_oat_…
  lang: "en", // error message language: "tr" (default) or "en"
  baseUrl: "https://hiboty.com",
});

const { data: bots } = await hiboty.listBots();
console.log(bots.length, hiboty.rateLimit); // { limit, remaining, reset }
OptionJavaScriptPythonDefault
KeyapiKeyapi_keyrequired
Error languagelanglangTurkish
Server addressbaseUrlbase_urlhttps://hiboty.com
Timeoutyourself, through fetchtimeout30 s (Python)
Custom fetchfetch—globalThis.fetch

Method names

  • JavaScript methods match the OpenAPI operationId: listBots.
  • Python methods are the snake_case form: list_bots. Joined names split the same way: list_whats_app_templates.
  • JavaScript: path parameters in order, the body as an object: updateBot(id, { name }). Methods with query parameters take one object: listKnowledgeSources({ id, limit }).
  • Python: path parameters in order, body fields as keywords: update_bot(id, name="x"). Reserved Python names get an underscore (from_); if a body field clashes, use govde={...}.
  • Methods that take an ID (uuid) reject an invalid ID with a TypeError before sending a request.

Bot setup example

The whole chain from the quickstart.

import { Hiboty } from "@hiboty/sdk";

const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });

const { data: bot } = await hiboty.createBot({
  name: "Store Assistant",
  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: "Shipping time",
  question: "When will my order arrive?",
  answer: "Orders ship within 1-3 business days.",
});

const { data: test } = await hiboty.testBotReply(bot.id, {
  messages: [{ role: "user", content: "When will my order arrive?" }],
});
console.log("ai", test.reply);

const { data: automation } = await hiboty.createAutomation({
  bot_id: bot.id,
  name: "Price question",
  trigger: "anahtar_kelime",
  trigger_config: { kelimeler: ["fiyat"], eslesme: "icerir", aiBastir: true, tekrarGun: 0 },
  steps: [{ tur: "mesaj", metin: "Our price list: 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: "Hello!" }, { idempotencyKey: `welcome-${to}` });
  console.log("message", id);
}

Error handling

Every non-2xx response is thrown as HibotyHatasi: status, code, message, retryAfter (Python: retry_after) and 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: "November", body: "Hello {{ad}}" });
} catch (err) {
  if (err instanceof HibotyHatasi) {
    console.error(err.status, err.code, err.message, err.retryAfter);
  } else {
    throw err;
  }
}

Pagination

paginate walks a paginated list to the end; it works on all 41 list endpoints. For a single page, call the method directly.

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

Pass idempotencyKey (Python: idempotency_key) to avoid duplicates on retries; methods that support it are marked in the reference.

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: "Hello!" },
  { idempotencyKey: "order-10482" },
);

Links

OpenAPI document: https://hiboty.com/api/v1/openapi.json

npm: @hiboty/sdk, PyPI: hiboty