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

Compatibility

Python Status Last local matrix run (SDK 1.6.0, 2026-11-17)
3.13 Supported Passed (3.13.5)
3.12 Supported Passed (3.12.8)
3.11 Supported Passed (3.11.9)
3.10 Supported Passed (3.10.6)
3.9 Allowed by requires-python (>=3.9), end of life upstream Not run: no Python 3.9 on the test machine

The matrix builds the wheel, installs it into a fresh virtual environment for each Python version and runs an end-to-end chain against a local Hiboty server (AI test reply, contacts, orders, conversations and messages, campaigns, webhook delivery and signature, pagination, idempotency, rate-limit info, errors) plus every README example.

Note: the matrix found that SDK releases up to and including 1.6.0 as published used an f-string form that only Python 3.12+ accepts, so import hiboty failed on Python 3.9–3.11. The fix ships with 1.7.0.

Versioning policy. The SDK follows semantic versioning together with the REST API (/api/v1). Minor versions only add methods and optional parameters; a method is never removed or renamed and a parameter never becomes required within a major version. Every release is checked against the API surface of SDK 1.4.1, so code written for an older 1.x SDK keeps working against the current API. Support for a Python version that has reached end of life upstream may be dropped only in a new major version.

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

Uyumluluk ve sürüm politikası

Python Durum Son yerel matris (SDK 1.6.0, 17.11.2026)
3.13 Destekleniyor Geçti (3.13.5)
3.12 Destekleniyor Geçti (3.12.8)
3.11 Destekleniyor Geçti (3.11.9)
3.10 Destekleniyor Geçti (3.10.6)
3.9 requires-python (>=3.9) izin verir, ömrü bitti Koşulmadı: deneme makinesinde Python 3.9 yok

Matris wheel'i üretir, her Python sürümü için temiz bir sanal ortama kurar ve yerel bir Hiboty sunucusuna karşı uçtan uca zinciri ve bu dosyadaki bütün örnekleri çalıştırır.

Not: Matris, 1.6.0 dahil yayımlanmış sürümlerin yalnız Python 3.12+ ile çalışan bir f-string biçimi kullandığını buldu; bu sürümlerde Python 3.9–3.11'de import hiboty hata veriyordu. Düzeltme 1.7.0 ile gelir.

SDK, REST API (/api/v1) ile birlikte semantik sürümleme izler. Ara sürümler yalnız metot ve isteğe bağlı parametre ekler; bir ana sürüm içinde metot kaldırılmaz, adı değişmez, parametre zorunlu hâle gelmez. Her sürüm SDK 1.4.1'in API yüzeyine karşı denetlenir; eski 1.x SDK ile yazılmış kod güncel API'de çalışmayı sürdürür. Ömrü biten bir Python sürümünün desteği ancak yeni bir ana sürümde kaldırılabilir.

License

MIT — see the LICENSE file in the package.

Metadata

Release files for hiboty 1.10.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.10.0
File Size Uploaded Provenance Actions
hiboty-1.10.0.tar.gz 24.8 kB Without provenance Details for hiboty-1.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 41.3 kB

Release files / hiboty-1.10.0.tar.gz

Download URL hiboty-1.10.0.tar.gz
Size 24.8 kB
Tags Source
SHA-256 checksum
How to use checksums
4509501cc50360c2e3d9c73afec1e8721bb3ebcf59f7df5d5dc7214b8521a571
BLAKE2b-256 checksum
How to use checksums
347d49fe7332a3d1bacf57fbd9884a6fa8e02d3f3f782d3fc2ddbd12a43442af
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.10.0-py3-none-any.whl

Download URL hiboty-1.10.0-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a11f29964fe4fdc47a36c479da769e0cb7ae5f28f919446515b7010bc01c574
BLAKE2b-256 checksum
How to use checksums
69cacc8f0961cf0d2bc5687905ce81f2028ecb5e6d464c9f3a695c1507f17940
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.10.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.10.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