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ı) ve message ya da template (yalnız WhatsApp; aşağıya bakın). 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, acquisition_source, attributes, 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; değişiklik izin defterine "api" kaynağıyla yazılır.
GET	/api/v1/contacts/{id}/consent	Kişinin güncel iznini, son değişiklik kaynağını ve izin geçmişini döner. Kişiler STOP/DUR yazarak çıkar, BAŞLA/START ile yeniden katılır.
GET	/api/v1/contacts/{id}	Tek kişiyi döner (ad, kullanıcı adı, telefon, izin, etiketler, not, özel alanlar (attributes), son görülme).
PATCH	/api/v1/contacts/{id}	Kişinin adını, notunu, etiketlerini ve özel alanlarını günceller. tags tüm listeyi değiştirir; add_tags / remove_tags yalnızca ekler veya çıkarır (en fazla 20 etiket). attributes: {anahtar: değer} — yalnızca panelde tanımlı alanlar; null alanı temizler.
POST	/api/v1/conversations/{id}/status	Sohbet durumunu değiştirir: open (AI yeniden yanıtlar), handoff (temsilciye devreder, AI susar), closed (kapatır; memnuniyet anketi açıksa kişiye gider).
GET	/api/health	Servis sağlık kontrolü (kimlik gerekmez).

WhatsApp şablon mesajı

WhatsApp'ta kişinin son mesajından 24 saat geçtiyse serbest metin gönderilemez; sipariş, kargo veya randevu gibi işlemsel bildirimler için Meta onaylı bir şablon kullanın. Yalnız iletişim izni veren (opted_in) kişiye gönderilir. params sırasıyla başlık ve gövdedeki {{1}}, {{2}}… yerlerini doldurur; sayısı şablonla eşleşmelidir. Değerlerde {{isim}} ve özel alan anahtarları ({{sehir}} gibi) kişiye göre doldurulur.

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":"905321234567","template":{"name":"siparis_kargoda","language":"tr","params":["{{isim}}","HB-10482"]}}'
# → { "id": "…", "status": "sent", "template": "siparis_kargoda" }

Olası hatalar: template_unsupported (bot WhatsApp değil), consent_required (izin yok), template_not_found (onaylı şablon yok), template_params (parametre sayısı uymuyor).

Kişi ve sohbet yönetimi

CRM'inizden kişiyi etiketleyin, ardından sohbeti temsilciye devredin.

curl -X PATCH https://hiboty.com/api/v1/contacts/<CONTACT_ID> \
  -H "Authorization: Bearer hb_live_..." -H "Content-Type: application/json" \
  -d '{"name":"Ayşe Yılmaz","add_tags":["vip"],"notes":"Kurumsal teklif istedi","attributes":{"sehir":"İzmir","butce":1500}}'

curl -X POST https://hiboty.com/api/v1/conversations/<CONVERSATION_ID>/status \
  -H "Authorization: Bearer hb_live_..." -H "Content-Type: application/json" \
  -d '{"status":"handoff"}'
# → { "data": { "id": "…", "status": "handoff", "previous_status": "open", … } }

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

Kanal webhook’ları ve hız limiti

Telegram ve WhatsApp webhook’ları Hiboty tarafından otomatik kurulur ve imzayla doğrulanır. Olayları kendi sisteminize iletmek için aşağıdaki giden webhook’ları kullanın.

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
contact.consent_changed Kampanya gönderimi bitti
campaign.completed İçerik takvimindeki gönderi yayınlandı
post.published Mini App formu veya sipariş talebi gönderildi
miniapp.submission
miniapp.order_updated

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 verifyHibotySignature(req, rawBody, secret) {
  const ts = req.headers["x-hiboty-timestamp"];
  const signature = 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 expected = "sha256=" + createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");
  return expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

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. Son 90 günlük erişilebilirlik ve olay geçmişi durum sayfasında yayınlanır.

Durum sayfası /api/health