Geliştiriciler

Hiboty REST API

Bot ve mesajlaşma özelliklerini kendi uygulamanıza entegre edin. API anahtarları panelde Ayarlar → API bölümünden oluşturulur (Pro ve üzeri planlar).

Kimlik doğrulama

Her istek Authorization: Bearer <api_key> başlığı taşır. Anahtarlar hb_live_ ön ekiyle başlar, yalnızca oluşturulduğu anda gösterilir ve sunucuda özetlenerek saklanır.

cURL

curl -X POST https://hiboty.com/api/v1/messages \
  -H "Authorization: Bearer hb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"<BOT_ID>","to":"123456789","message":"Merhaba! 👋"}'

JavaScript

const res = await fetch("https://hiboty.com/api/v1/messages", {
  method: "POST",
  headers: { Authorization: "Bearer hb_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ bot_id: "<BOT_ID>", to: "123456789", message: "Merhaba! 👋" }),
});
const data = await res.json(); // { id, status: "sent" }

Python

import requests
r = requests.post(
    "https://hiboty.com/api/v1/messages",
    headers={"Authorization": "Bearer hb_live_..."},
    json={"bot_id": "<BOT_ID>", "to": "123456789", "message": "Merhaba! 👋"},
)
print(r.json())

Uç noktalar

Metot	Yol	Açıklama
POST	/api/v1/messages	Bir kişiye mesaj gönderir. Gövde: bot_id, to (Telegram chat id veya WhatsApp numarası), message. Kişi daha önce bota yazmış olmalıdır.
GET	/api/v1/bots	Organizasyonun botlarını listeler (id, name, channel, status).
GET	/api/v1/contacts?bot_id=	Botun kişilerini listeler (external_id, name, consent, last_seen_at). Sayfalama: limit, cursor.
GET	/api/v1/conversations?bot_id=	Sohbetleri son mesaja göre listeler; status ile filtrelenir.
GET	/api/v1/messages/list?conversation_id=	Bir sohbetin mesajlarını yeniden eskiye listeler. Sayfalama: limit, cursor.
POST	/api/v1/contacts/{id}/consent	Kişinin iletişim iznini (opted_in/opted_out) ve isteğe bağlı etiketlerini günceller.
GET	/api/health	Servis sağlık kontrolü (kimlik gerekmez).

Hata biçimi

Hatalar JSON döner; HTTP durumu 400 (doğrulama), 401 (kimlik), 403 (plan/kapsam), 404, 429 (hız limiti), 502 (kanal hatası).

{ "error": { "code": "validation_error", "message": "to alanı gerekli" } }

Gelen webhook’lar

Telegram ve WhatsApp webhook’ları Hiboty tarafından otomatik kurulur. Kendi sisteminize olay iletimi (giden webhook) bir sonraki sürümde eklenecektir; o zamana kadar sohbetleri API ile sorgulayabilirsiniz.

Hız limiti: anahtar başına dakikada 120 istek; aşımda 429 ve Retry-After başlığı.

Giden webhook'lar

Ayarlar → Webhook'lar bölümünden HTTPS uç noktanızı kaydedin; seçtiğiniz olaylar JSON olarak POST edilir. Her webhook'un kendi imza anahtarı (whsec_…) vardır.

Olaylar

message.received Müşteriden mesaj geldi
message.sent AI/temsilci/kampanya/API mesaj gönderdi
conversation.handoff Sohbet temsilciye devredildi
contact.created Bota ilk kez yazan kişi kaydedildi
campaign.completed Kampanya gönderimi bitti

Başlıklar: X-Hiboty-Event, X-Hiboty-Delivery, X-Hiboty-Timestamp, X-Hiboty-Signature. 2xx dışı yanıtlar 1 dk, 5 dk, 30 dk, 2 sa, 12 sa sonra yeniden denenir.

Örnek yük

{
  "id": "5b1c…",
  "event": "message.received",
  "created_at": "2026-10-23T09:00:00.000Z",
  "organization_id": "…",
  "data": {
    "message": { "id": "…", "body": "Merhaba, fiyat?", "created_at": "…" },
    "conversation": { "id": "…", "status": "open" },
    "contact": { "id": "…", "channel": "telegram", "external_id": "123456789", "name": "Ayşe" },
    "bot": { "id": "…", "name": "Satış Asistanı", "channel": "telegram" }
  }
}

İmza doğrulama (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

export function hibotyImzaDogrula(req, rawBody, secret) {
  const ts = req.headers["x-hiboty-timestamp"];
  const imza = req.headers["x-hiboty-signature"]; // "sha256=…"
  // 5 dakikadan eski istekleri reddedin (tekrar saldırısı)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const beklenen = "sha256=" + createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");
  return beklenen.length === imza.length &&
    timingSafeEqual(Buffer.from(beklenen), Buffer.from(imza));
}

Gövdeyi ham (parse edilmemiş) haliyle imzalayın; JSON yeniden serileştirilirse imza tutmaz. Uç noktanız 10 saniye içinde 2xx döndürmeli; ağır işleri kuyruğa atın.

Servis durumu

Canlı sağlık ucu: /api/health. Ayrıntılı durum sayfası ve geçmiş kesinti kayıtları yakında yayınlanacaktır; ölçülmemiş erişilebilirlik oranı iddia edilmez.

/api/health