API başvurusu

Kişiler

Bu gruptaki 22 uç.

Kişileri en yeniden eskiye listeler

GET/api/v1/contacts

Kapsam
read
SDK metodu
listContacts · list_contacts
MCP aracı
listContactssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
bot_idsorguuuidhayırYalnızca bu botun kişileri
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/contacts?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "channel": "telegram",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "phone": "905321234567",
      "consent": "opted_in",
      "acquisition_source": "string",
      "attributes": {
        "key": "sehir"
      },
      "last_seen_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "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.
  • 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.

Kişi ekler

POST/api/v1/contacts

İçe aktarmayla aynı kural geçerlidir: izin "unknown" başlar, kişi bota kendisi yazmadan kampanya almaz. Telegram botunda external_id (sayısal sohbet kimliği) gerekir; WhatsApp botunda external_id yoksa phone kullanılır. Aynı kanal kimliği varsa 409 contact_exists döner. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
createContact · create_contact
MCP aracı
createContact

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
bot_iduuidevet
external_idstringhayırlen ≤ 64
namestringhayırlen ≤ 120
usernamestringhayırlen ≤ 64
phonestringhayırlen ≤ 32
tagsstring[]hayıritems ≤ 20
notesstringhayırlen ≤ 4000
attributesobjecthayırÖzel alan anahtarı → değer (metin, sayı, YYYY-MM-DD tarih ya da seçenek)

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contacts" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","external_id":"123456789","name":"Ayşe Yılmaz","tags":["vip"]}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_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.contact_exists
  • 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.

Tek kişiyi döner (etiket, not ve özel alanlar dahil)

GET/api/v1/contacts/{id}

Kapsam
read
SDK metodu
getContact · get_contact
MCP aracı
getContactsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKişi kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_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).
  • 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.

Ad, not, etiket ve özel alanları günceller

PATCH/api/v1/contacts/{id}

tags tüm listeyi değiştirir; add_tags / remove_tags yalnızca ekler veya çıkarır. attributes yalnızca panelde tanımlı alanları kabul eder; null alanı temizler. Kapsam: write.

Kapsam
write
SDK metodu
updateContact · update_contact
MCP aracı
updateContact

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKişi kimliği

Gövde alanları

AdTürZorunluAçıklama
namestring | nullhayırlen ≤ 120
notesstring | nullhayırlen ≤ 4000
tagsstring[]hayıritems ≤ 20
add_tagsstring[]hayıritems ≤ 20
remove_tagsstring[]hayıritems ≤ 20
attributesobjecthayırfields ≤ 30

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ayşe Yılmaz","add_tags":["vip"],"notes":"Kurumsal teklif istedi"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_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).
  • 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.

Kişiyi kalıcı olarak siler (KVKK)

DELETE/api/v1/contacts/{id}

Kişi, sohbetleri, mesajları ve kişiye bağlı diğer kişisel veriler geri alınamaz biçimde silinir. Denetim kaydında kanal kimliğinin yalnız özeti kalır. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
deleteContact · delete_contact
MCP aracı
deleteContactgeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKişi kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": 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.
  • 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.

Güncel izin ve izin geçmişi (en yeni önce, en fazla 50)

GET/api/v1/contacts/{id}/consent

Kişiler STOP/DUR yazarak çıkar, BAŞLA/START ile yeniden katılır.

Kapsam
read
SDK metodu
getContactConsent · get_contact_consent
MCP aracı
getContactConsentsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKişi kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/consent" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consent": "opted_in",
    "source": "string",
    "history": [
      {
        "from": "string",
        "to": "string",
        "source": "string",
        "created_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).
  • 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.

İletişim iznini (ve isteğe bağlı etiketleri) günceller

POST/api/v1/contacts/{id}/consent

Değişiklik izin defterine "api" kaynağıyla yazılır. tags verilirse kişinin etiket listesinin tamamını değiştirir; yalnız eklemek için updateContact add_tags kullanın. Kapsam: write.

Kapsam
write
SDK metodu
updateContactConsent · update_contact_consent
MCP aracı
updateContactConsentgeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKişi kimliği

Gövde alanları

AdTürZorunluAçıklama
consentenumevetopted_in | opted_out
tagsstring[]hayıritems ≤ 20

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/consent" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"consent":"opted_in","tags":["bulten"]}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consent": "opted_in",
    "tags": [
      "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.

CSV metninden kişileri içe aktarır

POST/api/v1/contacts/import

En fazla 2 MB ve 5.000 satır; ayraç noktalı virgül, virgül ya da sekme olabilir. Yeni kişilerin izni "unknown" başlar; var olanın izni yalnız "izin yok" yönünde değişir, dolu bilgileri korunur, etiketleri birleşir. Özel alan sütunları anahtar ya da adla eşleşir. errors en fazla 20 satır döner. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
importContacts · import_contacts
MCP aracı
importContacts

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
bot_iduuidevet
csvstringevetlen ≤ 2097152

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contacts/import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","csv":"kanal_kimligi;ad;etiketler\n123456789;Ayşe Yılmaz;vip"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "added": 1,
    "updated": 1,
    "skipped": 1,
    "invalid_field_values": 1,
    "errors": [
      {
        "row": 1,
        "code": "missing_channel_id"
      }
    ]
  }
}

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.

Kişileri CSV parçaları hâlinde dışa aktarır

GET/api/v1/contacts/export

Her sayfa en fazla 1000 kişi taşır. Her satır CRLF ile biter; BOM ve başlık yalnız ilk sayfadadır, csv parçalarını sırayla uç uca ekleyince tek dosya olur. Formül enjeksiyonuna karşı = + - @ ile başlayan hücreler kaçışlanır. Her sayfa denetim kaydına yazılır. Yönetici yetkisi gerekir. Kapsam: contacts:read.

Kapsam
contacts:read
SDK metodu
exportContacts · export_contacts
MCP aracı
exportContactssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
consentsorguenumhayırİzin durumuopted_in | opted_out | unknown
tagsorgustringhayırBu etiketi taşıyanlar
qsorgustringhayırAd, kullanıcı adı, telefon ya da kanal kimliğinde arama
bot_idsorguuuidhayırYalnız bu bot
limitsorguintegerhayırSayfa boyutu (1–1000, varsayılan 1000); tam sayı değilse 400val 1–1000, default 1000
cursorsorgustringhayırÖnceki yanıttaki next_cursor (opak)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/contacts/export?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "csv": "string",
    "row_count": 1,
    "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.

Kişilere toplu işlem uygular

POST/api/v1/contacts/bulk

tag_add, tag_remove, opt_out ya da delete; tek seferde en fazla 200 kişi. delete geri alınamaz ve yönetici ister. Üye yalnız erişebildiği botların kişilerini işler; diğer kimlikler sessizce dışarıda kalır, affected gerçekten değişen sayıdır. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
bulkContacts · bulk_contacts
MCP aracı
bulkContactsgeri alınamaz

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
operationenumevettag_add | tag_remove | opt_out | delete
idsuuid[]evetitems 1–200
tagstringhayırtag_add ve tag_remove için gereklilen ≤ 32

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contacts/bulk" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"operation":"tag_add","ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"tag":"vip"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "operation": "string",
    "affected": 1
  }
}

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

Kişinin AI hafızasını temizler

POST/api/v1/contacts/{id}/clear-memory

Eski mesajlar yeniden özetlenmez. Kişinin botuna erişebilen her üye yapabilir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
clearContactMemory · clear_contact_memory
MCP aracı
clearContactMemorygeri alınamaz

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/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/clear-memory" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "memory_cleared": 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.
  • 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.

Kaydı başka bir kayıtla aynı müşteri profiline bağlar

POST/api/v1/contacts/{id}/profile-link

İki kaydın botuna da erişim gerekir; diğer kayıt erişilemiyorsa 404 döner. Bağlanamazsa 409 profile_link_failed, "profil" özelliği kapalıysa 409 feature_disabled döner. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
linkContactProfile · link_contact_profile
MCP aracı
linkContactProfile

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
other_contact_iduuidevet

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile-link" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"other_contact_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

Örnek yanıt (200)

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

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.profile_link_failedfeature_disabled
  • 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.

Kaydı müşteri profilinden ayırır

DELETE/api/v1/contacts/{id}/profile-link

Kayıt silinmez. Profilde değilse 409 not_linked, "profil" özelliği kapalıysa 409 feature_disabled döner. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
unlinkContactProfile · unlink_contact_profile
MCP aracı
unlinkContactProfilegeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile-link" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unlinked": 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.
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.not_linkedfeature_disabled
  • 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.

Etiketleri kullanım sayılarıyla listeler

GET/api/v1/contact-tags

Üye yalnız erişebildiği botların kişilerindeki etiketleri görür. En çok kullanılan önce gelir. Kapsam: contacts:read.

Kapsam
contacts:read
SDK metodu
listContactTags · list_contact_tags
MCP aracı
listContactTagssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
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)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/contact-tags?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "key": "sehir",
      "name": "Hiboty",
      "variants": [
        "string"
      ],
      "contact_count": 1,
      "automation_count": 1
    }
  ],
  "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.
  • 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.

Etiketi yeniden adlandırır

POST/api/v1/contact-tags/rename

Organizasyondaki bütün kişilere uygulanır; eşleşme harf farkı gözetmez. Otomasyon adımları ve kampanya segmentleri otomatik değişmez. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
renameContactTag · rename_contact_tag
MCP aracı
renameContactTaggeri alınamaz

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
tagstringevetlen 1–100
new_namestringevetlen 1–32

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contact-tags/rename" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tag":"vip","new_name":"VIP müşteri"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

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

Etiketleri tek etikette birleştirir

POST/api/v1/contact-tags/merge

Tek seferde en fazla 50 etiket. Organizasyondaki bütün kişilere uygulanır; otomasyon adımları ve kampanya segmentleri otomatik değişmez. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
mergeContactTags · merge_contact_tags
MCP aracı
mergeContactTagsgeri alınamaz

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
tagsstring[]evetitems 1–50
targetstringevetlen 1–32

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contact-tags/merge" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tags":["vip","premium"],"target":"VIP"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

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

Etiketleri bütün kişilerden kaldırır

POST/api/v1/contact-tags/delete

Tek seferde en fazla 50 etiket; kişiler silinmez. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
deleteContactTags · delete_contact_tags
MCP aracı
deleteContactTagsgeri alınamaz

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
tagsstring[]evetitems 1–50

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contact-tags/delete" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tags":["eski-kampanya"]}'

Örnek yanıt (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

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

Özel alan tanımlarını listeler

GET/api/v1/contact-fields

Panelde olduğu gibi üye rolü de okuyabilir. Kapsam: contacts:read.

Kapsam
contacts:read
SDK metodu
listContactFields · list_contact_fields
MCP aracı
listContactFieldssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
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)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/contact-fields?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "key": "sehir",
      "label": "Şehir",
      "type": "metin",
      "options": [
        "string"
      ],
      "ai_writable": true
    }
  ],
  "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.
  • 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.

Özel alan oluşturur

POST/api/v1/contact-fields

En fazla 30 alan (409 limit_reached); aynı anahtar 409 field_exists döner. key küçük harfle başlar, a–z, 0–9 ve _ içerir; ad, telefon gibi sistem anahtarları kullanılamaz. options yalnız secim türünde gerekir. AI yazma izni kapalı başlar. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
createContactField · create_contact_field
MCP aracı
createContactField

Idempotency-Key destekli

Parametreler

AdTürZorunluAçıklama
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
keystringevetlen 2–32
labelstringevetlen 1–50
typeenumevetmetin | sayi | tarih | secim
optionsstring[]hayıritems ≤ 30

Örnek istek

curl -X POST "https://hiboty.com/api/v1/contact-fields" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"key":"sehir","label":"Şehir","type":"secim","options":["İstanbul","Ankara"]}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key": "sehir",
    "label": "Şehir",
    "type": "metin",
    "options": [
      "string"
    ],
    "ai_writable": 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.
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.limit_reachedfield_exists
  • 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.

Özel alanı günceller

PATCH/api/v1/contact-fields/{id}

Anahtar ve tür değişmez; options yalnız secim türünde geçerlidir. Listeden çıkan seçeneği taşıyan kişilerin değeri silinir (cleared_contacts). ai_writable, AI kayıt aracının bu alana yazmasına izin verir. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
updateContactField · update_contact_field
MCP aracı
updateContactFieldgeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
labelstringhayırlen 1–50
optionsstring[]hayıritems ≤ 30
ai_writablebooleanhayır

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/contact-fields/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Yaşadığı şehir","ai_writable":true}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key": "sehir",
    "label": "Şehir",
    "type": "metin",
    "options": [
      "string"
    ],
    "ai_writable": true,
    "cleared_contacts": 1
  }
}

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.

Özel alanı siler

DELETE/api/v1/contact-fields/{id}

Alanın değeri bütün kişilerden geri alınamaz biçimde kaldırılır. Yönetici yetkisi gerekir. Kapsam: contacts:write.

Kapsam
contacts:write
SDK metodu
deleteContactField · delete_contact_field
MCP aracı
deleteContactFieldgeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/contact-fields/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

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

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.