API başvurusu

Mesajlar

Bu gruptaki 4 uç.

Bir kişiye mesaj gönderir

POST/api/v1/messages

Kişi daha önce bota yazmış olmalıdır. message (serbest metin) ya da template (yalnız WhatsApp, onaylı Meta şablonu) alanlarından tam olarak biri gönderilir. Yeniden denemede çift mesajı önlemek için Idempotency-Key kullanın. Plan sınırını aşan bot gönderemez (403 bot_plan_restricted). Kapsam: messages:send.

Kapsam
messages:send
SDK metodu
sendMessage · send_message
MCP aracı
sendMessagedış etkili

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
Idempotency-Keybaşlıkstringhayırİsteğe bağlı, 1-255 görünür ASCII karakter. Organizasyon + uç + anahtar başına 24 saat geçerlidir: aynı anahtar ve aynı gövdeyle ilk yanıt aynen döner (Idempotency-Replayed: true), işlem tekrarlanmaz. Farklı gövdede 409 idempotency_conflict; ilk istek sürerken 409 idempotency_in_progress ve Retry-After. 5xx ve 429 yanıtları saklanmaz, aynı anahtarla yeniden denenebilir.len 1–255

Gövde alanları

AdTürZorunluAçıklama
bot_iduuidevet
tostringevetTelegram chat id ya da WhatsApp numarası (kişi daha önce bota yazmış olmalı)len 3–64
messagestringhayırlen 1–4000
templateobjecthayır
template.namestringevet
template.languagestringevet
template.paramsstring[]hayır{{isim}} ve {{özel_alan}} değişkenleri kişiye göre dolduruluritems ≤ 20

Örnek istek

curl -X POST "https://hiboty.com/api/v1/messages" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Merhaba!"}'

Örnek yanıt (201)

JSON
{
  "id": "string",
  "status": "sent",
  "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "to": "string",
  "template": "string"
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.bot_plan_restricted
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.
  • 502Kanal ya da dış servis hatası (channel_error).

Bir sohbetin mesajlarını yeniden eskiye listeler

GET/api/v1/messages/list

Kapsam
read
SDK metodu
listMessages · list_messages
MCP aracı
listMessagessalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
conversation_idsorguuuidevet
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 50); tam sayı değilse 400val 1–200, default 50
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak; eski date-time imleçleri de kabul edilir)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/messages/list?conversation_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "direction": "in",
      "sender": "string",
      "body": "string",
      "status": "string",
      "external_id": "123456789",
      "created_at": "2026-11-06T09:00:00.000Z",
      "ai_sources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "title": "Örnek",
          "chunk": 1,
          "url": "https://example.com/hook"
        }
      ]
    }
  ],
  "next_cursor": "string"
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.

Başarısız mesajı yeniden dener

POST/api/v1/messages/{id}/retry

Yalnız başarısız giden mesajlar, en fazla 5 kez (aksi 409 message_not_retryable). Müşteriye gerçek mesaj gider. İzni geri çekilmiş kişiye otomasyon mesajı gitmez (403 opted_out). Boş AI yanıtı yeniden üretilir ve yeni kayıt olarak yazılır. messages:send kapsamı da gerekir; plan sınırını aşan bot gönderemez (403 bot_plan_restricted), aylık mesaj kotası uygulanır (429 message_quota_exceeded). Kanal hatası 502 channel_error döner. Kapsam: conversations:write.

Kapsam
conversations:write
SDK metodu
retryMessage · retry_message
MCP aracı
retryMessagedış etkili

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
Idempotency-Keybaşlıkstringhayırİsteğe bağlı, 1-255 görünür ASCII karakter. Aynı anahtar ve gövdeyle 24 saat içinde ilk yanıt aynen döner; farklı gövdede 409 idempotency_conflict.len 1–255

Örnek istek

curl -X POST "https://hiboty.com/api/v1/messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/retry" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "retried": true
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.opted_outbot_plan_restricted
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.message_not_retryable
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.message_quota_exceeded
  • 502Kanal ya da dış servis hatası (channel_error).channel_error

AI yanıtını değerlendirir

POST/api/v1/messages/{id}/feedback

value: up, down ya da null (kaldırır). note yalnız down için saklanır. Yalnız AI yanıtları değerlendirilir; başka mesaj 404 döner. Kapsam: conversations:write.

Kapsam
conversations:write
SDK metodu
rateAiReply · rate_ai_reply
MCP aracı
rateAiReply

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
Idempotency-Keybaşlıkstringhayırİsteğe bağlı, 1-255 görünür ASCII karakter. Aynı anahtar ve gövdeyle 24 saat içinde ilk yanıt aynen döner; farklı gövdede 409 idempotency_conflict.len 1–255

Gövde alanları

AdTürZorunluAçıklama
valueenumevetup | down | null
notestringhayırlen ≤ 500

Örnek istek

curl -X POST "https://hiboty.com/api/v1/messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/feedback" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"value":"down","note":"Kargo süresini yanlış söyledi"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "value": "up",
    "note": "string",
    "rated_at": "2026-11-06T09:00:00.000Z"
  }
}

Olası hatalar

  • 400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
  • 401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
  • 403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.
  • 429Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun.