Metadata-Version: 2.4
Name: hiboty
Version: 1.4.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/temel-kurallar#surum-politikasi
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")
```

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

## License

[MIT](https://hiboty.com/en/gelistiriciler/sdk) — see the `LICENSE` file in the package.
