Metadata-Version: 2.4
Name: hiboty
Version: 1.10.0
Summary: Official Python client for the Hiboty REST API: AI bots on Telegram and WhatsApp, contacts, conversations, campaigns, Mini Apps, automations and webhooks
Author-email: Hiboty <destek@hiboty.com>
License: MIT
Project-URL: Homepage, https://hiboty.com/en
Project-URL: Documentation, https://hiboty.com/en/gelistiriciler/sdk
Project-URL: API Reference, https://hiboty.com/en/gelistiriciler/api
Project-URL: Changelog, https://hiboty.com/en/gelistiriciler/degisiklik-gunlugu
Keywords: hiboty,telegram,whatsapp,chatbot,ai,bot,api,sdk,rest,messaging,automation,webhook
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hiboty

Official Python client for the [Hiboty](https://hiboty.com/en) 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](#türkçe)

## Installation

```bash
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.

```python
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.

```python
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`.

```python
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.

```python
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.

```python
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.

## Links

- Documentation: https://hiboty.com/en/gelistiriciler
- Quickstart: https://hiboty.com/en/gelistiriciler/hizli-baslangic
- API reference: https://hiboty.com/en/gelistiriciler/api
- Webhooks: https://hiboty.com/en/gelistiriciler/webhooklar
- MCP server: https://hiboty.com/en/gelistiriciler/mcp
- OpenAPI document: https://hiboty.com/api/v1/openapi.json
- Support: destek@hiboty.com

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

```python
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](./LICENSE) — see the `LICENSE` file in the package.
