Skip to main content

hiboty

Official Python client for the Hiboty REST API: build and manage AI bots on Telegram and WhatsApp, contacts, conversations, campaigns, Mini Apps, automations, webhooks and more.

  • No dependencies, standard library only, Python 3.9+
  • One method for every API endpoint; method names are the snake_case form of the OpenAPI operationId (listBots → list_bots)
  • Typed (py.typed)

Türkçe bölüm aşağıda

Installation

pip install hiboty

Quickstart

Create an API key in the dashboard under Settings → API (Pro plan and higher) and keep it in an environment variable.

import os
from hiboty import Hiboty

hiboty = Hiboty(os.environ["HIBOTY_API_KEY"])

page = hiboty.list_bots(limit=5)
print([b["name"] for b in page["data"]], page["next_cursor"])

Options: api_key (hb_live_… API key or hb_oat_… OAuth token, required), lang (error message language, "tr" by default or "en"), base_url, timeout (seconds, 30 by default). Details of the last response's rate limit are in hiboty.rate_limit.

Build a bot from scratch

Needs a key with the Full management access level and a Telegram token from BotFather.

import os
from hiboty import Hiboty

hiboty = Hiboty(os.environ["HIBOTY_API_KEY"])

# 1. Create the bot (starts as a draft)
bot = hiboty.create_bot(name="Store Assistant", channel="telegram", template="eticaret", language="en")["data"]

# 2. Connect the Telegram token; it's stored encrypted and never returned
hiboty.connect_bot(bot["id"], token=os.environ["TELEGRAM_BOT_TOKEN"])

# 3. Add a knowledge source
hiboty.create_knowledge_source(bot["id"], type="faq", title="Shipping time", question="When will my order arrive?", answer="Orders ship within 1-3 business days.")

# 4. Try an AI reply; nothing is sent to customers
test = hiboty.test_bot_reply(bot["id"], messages=[{"role": "user", "content": "When will my order arrive?"}])["data"]
print(test["reply"])

# 5. Add an automation and turn it on
automation = hiboty.create_automation(
    bot_id=bot["id"],
    name="Price question",
    trigger="anahtar_kelime",
    trigger_config={"kelimeler": ["price"], "eslesme": "icerir", "aiBastir": True, "tekrarGun": 0},
    steps=[{"tur": "mesaj", "metin": "Our price list: https://example.com/prices"}],
)["data"]
hiboty.update_automation(automation["id"], active=True)

# 6. Set up a webhook; the signing secret is returned only here
webhook = hiboty.create_webhook(url="https://example.com/hiboty-webhook", events=["message.received"])["data"]
print(webhook["secret"])

# 7. Send a message; the contact must have messaged the bot first
contacts = hiboty.list_contacts(bot_id=bot["id"], limit=1)["data"]
if contacts:
    hiboty.send_message(bot_id=bot["id"], to=contacts[0]["external_id"], message="Hello!")

Calling methods

Path parameters go in order and body fields are keywords: update_bot(id, name="x"). Reserved Python names get an underscore (from_); if a body field clashes with a parameter, pass govde={...}. Methods that take an ID reject an invalid ID with a TypeError before sending a request.

Pagination

paginate walks any paginated list to the end. For a single page, call the method and pass next_cursor back as cursor.

import os
from hiboty import Hiboty

hiboty = Hiboty(os.environ["HIBOTY_API_KEY"])

for contact in hiboty.paginate("list_contacts", limit=100):
    print(contact["name"], contact["consent"])

Errors

Every non-2xx response is raised as HibotyHatasi with status, code, message, retry_after and body. code doesn't depend on language.

import os
from hiboty import Hiboty, HibotyHatasi

hiboty = Hiboty(os.environ["HIBOTY_API_KEY"], lang="en")

try:
    hiboty.create_campaign(bot_id=os.environ["BOT_ID"], name="November", body="Hello {{ad}}")
except HibotyHatasi as err:
    print(err.status, err.code, err.message, err.retry_after)

A campaign created with the API waits for approval: sending only starts after an admin approves it in the dashboard.

Idempotency

Pass idempotency_key on supported methods. Within 24 hours the same key and body return the first response, so a retry can't send the message twice.

import os
from hiboty import Hiboty

hiboty = Hiboty(os.environ["HIBOTY_API_KEY"])

hiboty.send_message(bot_id=os.environ["BOT_ID"], to="123456789", message="Hello!", idempotency_key="order-10482")

Türkçe

Hiboty REST API için resmî Python istemcisi. Bağımlılığı yoktur; Python 3.9+ ile yalnız standart kitaplığı kullanır. API anahtarınızı panelde Ayarlar → API bölümünden oluşturun (Pro ve üzeri planlar) ve ortam değişkeninde tutun.

import os
from hiboty import Hiboty, HibotyHatasi

# hb_live_ API anahtarı ya da hb_oat_ OAuth erişim belirteci
hiboty = Hiboty(os.environ["HIBOTY_API_KEY"], lang="tr")

botlar = hiboty.list_bots()["data"]
# idempotency_key: zaman aşımında aynı anahtarla yeniden deneyin, mesaj ikinci kez gitmez (24 saat).
hiboty.send_message(bot_id=botlar[0]["id"], to="123456789", message="Merhaba!", idempotency_key="siparis-10482")

for kisi in hiboty.paginate("list_contacts", bot_id=botlar[0]["id"]):
    print(kisi["name"])

try:
    # Kampanya onay bekler: gönderim panelde yönetici onayıyla başlar.
    hiboty.create_campaign(bot_id=botlar[0]["id"], name="Kasım", body="Merhaba {{ad}}")
except HibotyHatasi as hata:
    print(hata.status, hata.code, hata.message, hata.retry_after)

print(hiboty.rate_limit)  # {"limit": ..., "remaining": ..., "reset": ...}

paginate bütün sayfalı listeleri dolaşır. Metot adları OpenAPI belgesindeki operationId değerlerinin snake_case karşılığıdır (listBots → list_bots). Belgeler: https://hiboty.com/gelistiriciler — Hızlı başlangıç: https://hiboty.com/gelistiriciler/hizli-baslangic — API başvurusu: https://hiboty.com/gelistiriciler/api

License

MIT — see the LICENSE file in the package.

Metadata

Release files for hiboty 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hiboty 1.4.0
File Size Uploaded Provenance Actions
hiboty-1.4.0.tar.gz 21.2 kB Without provenance Details for hiboty-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hiboty 1.4.0
File Interpreter ABI Platform Actions
hiboty-1.4.0-py3-none-any.whl Python 3 none any Details for hiboty-1.4.0-py3-none-any.whl

Total release size: 35.4 kB

Release files / hiboty-1.4.0.tar.gz

Download URL hiboty-1.4.0.tar.gz
Size 21.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c450b006cd9fc0403aeab62708aa961cf4ea09aa42c49941bc593fdf901f0409
BLAKE2b-256 checksum
How to use checksums
feb455c1b1c3609bb6a53c7552f28863d748d9453eb9ce54ce250cce29c8766f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / hiboty-1.4.0-py3-none-any.whl

Download URL hiboty-1.4.0-py3-none-any.whl
Size 14.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb6830cbfdb28a4e386dc335bfb7f50864986ff6b644e018eeb72b2cf7f74699
BLAKE2b-256 checksum
How to use checksums
04fcac1931c074f718e213a8d400a94f4ae3f2c494ad8ccbba6075ca46abae04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for hiboty 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page