API başvurusu

Kampanyalar

Bu gruptaki 17 uç.

Kampanyaları listele

GET/api/v1/campaigns

Kapsam
read
SDK metodu
listCampaigns · list_campaigns
MCP aracı
listCampaignssalt okunur

Sayfalı

Parametreler

AdTürZorunluAçıklama
bot_idsorguuuidhayırYalnız bu bot
statussorguenumhayırDurum süzgeci; başka değer 400 dönerdraft | pending_approval | approved | sending | completed | failed | cancelled
limitsorguintegerhayırSayfa boyutu (1–200, varsayılan 100); tam sayı değilse 400val 1–200, default 100
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/campaigns?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",
      "name": "Hiboty",
      "status": "string",
      "body": "string",
      "template_name": "string",
      "topic": "string",
      "audience_count": 1,
      "sent_count": 1,
      "failed_count": 1,
      "scheduled_at": "2026-11-06T09:00:00.000Z",
      "started_at": "2026-11-06T09:00:00.000Z",
      "completed_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z",
      "best_time": true,
      "paused_at": "2026-11-06T09:00:00.000Z",
      "pause_reason": "hata_orani"
    }
  ],
  "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.

Kampanya oluştur (onay bekler)

POST/api/v1/campaigns

Kampanya "pending_approval" durumunda oluşur ve panelde yönetici onaylayana kadar gönderilmez; API gönderimi başlatamaz. Telegram botunda body (A/B için body_b), WhatsApp botunda onaylı template gerekir. Organizasyonun içerik politikası açıksa metin, şablon parametreleri ve görsel adresi denetlenir; engele takılan istek 422 content_policy döner. Yanlış segment alanı 400 döner; süzgece uyan kişi yoksa 409 empty_audience döner, kampanya tüm kitleye düşmez. Anahtarı oluşturan (OAuth'ta yetkiyi veren) kişinin e-postası doğrulanmamışsa 403 email_not_verified döner. Yeniden denemede çift kampanyayı önlemek için Idempotency-Key kullanın. Kapsam: write.

Kapsam
write
SDK metodu
createCampaign · create_campaign
MCP aracı
createCampaigndış 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
namestringevetlen 2–120
bodystringhayırTelegram metni; {{ad}}, {{tercihler}} değişkenleri kullanılabilirlen 5–4000
body_bstringhayırTelegram A/B testi için ikinci metinlen 5–4000
media_urlstringhayırTelegram görseli (https ya da yükleme adresi)len ≤ 500
templateobjecthayırWhatsApp onaylı şablonu; params_b ile A/B testi
template.namestringevet
template.languagestringevet
template.paramsstring[]hayır
template.params_bstring[]hayır
topicstringhayırKonu: duyuru, firsat, bilgilendirme, etkinlik, yeni_urun
scheduled_atdate-timehayırİleri tarihli gönderim
best_timebooleanhayırEn iyi saatte gönder: zaman botun geçmiş etkileşiminden, organizasyon saat dilimi, sessiz saat ve mesai kurallarıyla seçilir. scheduled_at ile birlikte verilemez; öneri yoksa 409 best_time_unavailable.
segmentobjecthayırKitle süzgeci; koşullar VE ile birleşir. Alan yoksa ya da {} ise botun tüm izinli kişileri seçilir. Bilinmeyen alan, geçersiz değer ya da içi boş süzgeç 400 döner; uyan kişi yoksa 409 empty_audience döner, kampanya tüm kitleye düşmez.
segment.include_tagsstring[]hayırBu etiketlere göre dahil et (büyük/küçük harf duyarsız)items ≤ 20
segment.exclude_tagsstring[]hayırBu etiketlerden biri olanı çıkaritems ≤ 20
segment.matchenumhayırinclude_tags: herhangi biri (any) ya da hepsi (all)any | all, default "any"
segment.last_seenobjecthayırTam olarak biri: within_days (son N gün içinde görülen) ya da older_than_days (N günden uzun süredir görülmeyen, hiç görülmemiş dahil)fields 1–1
segment.last_seen.within_daysintegerhayırval 1–3650
segment.last_seen.older_than_daysintegerhayırval 1–3650
segment.orderenumhayırMini App siparişi vermiş (placed) ya da vermemiş (none)placed | none
segment.sourcestring[]hayırEdinme kaynağı kodlarından herhangi biri; "-" bağlantısız gelenleri seçeritems ≤ 20
segment.fieldsobject[]hayırÖzel alan koşulları (hepsi sağlanmalı)items ≤ 5
segment.fields[].keystringevetÖzel alan anahtarı
segment.fields[].typeenumevettext | number | date | choice
segment.fields[].openumevetgt/lt yalnız number ve date, contains yalnız text ileexists | empty | eq | neq | gt | lt | contains
segment.fields[].valuestring | numberhayırexists ve empty dışında gerekli

Örnek istek

curl -X POST "https://hiboty.com/api/v1/campaigns" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","name":"Kasım indirimi","body":"Merhaba {{ad}}, kasım indirimimiz başladı!","segment":{"include_tags":["vip"]}}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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.email_not_verified
  • 404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.empty_audience
  • 422İçerik politikasına takıldı (content_policy).content_policy
  • 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).

Kampanya ve varyant sonuçları

GET/api/v1/campaigns/{id}

Kapsam
read
SDK metodu
getCampaign · get_campaign
MCP aracı
getCampaignsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKampanya kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/campaigns/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",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani",
    "results": [
      {
        "variant": "string",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 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.

Başlamamış kampanyayı günceller

PATCH/api/v1/campaigns/{id}

Yalnız draft ve pending_approval durumundaki kampanya değişir; başka durumda 409 campaign_locked döner. createCampaign ile aynı denetimler uygulanır: içerik politikası (422 content_policy), segment, boş kitle (409 empty_audience), WhatsApp'ta onaylı şablon. Değişen kampanya yeniden onay ister: durum pending_approval olur, onay bilgisi temizlenir, değişikliği yapan oluşturan sayılır (dört göz açıkken kendi yazdığını onaylayamaz; anahtarla yapılan değişiklik dört gözde panelden onaylanamaz). API gönderim başlatamaz: onay ucu yoktur, kampanya yalnız panelde dört göz onayıyla başlar. body_b, media_url, topic ve scheduled_at null ile temizlenir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
updateCampaign · update_campaign
MCP aracı
updateCampaign

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
namestringhayırlen 2–120
bodystringhayırlen 5–4000
body_bstring | nullhayırlen 5–4000
media_urlstring | nullhayırlen ≤ 500
templateobjecthayır
template.namestringevetlen 1–200
template.languagestringevetlen 1–20
template.paramsstring[]hayır
template.params_bstring[]hayır
topicstring | nullhayırlen ≤ 40
scheduled_atdate-time | nullhayır
segmentobjecthayırEtiket, son görülme, sipariş, kaynak, özel alan ve sıcaklık koşulları; createCampaign ile aynı biçim. Boş nesne: botun bütün izinli kişileri.

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Kasım indirimi","body":"Merhaba, kasım indirimimiz başladı!"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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.campaign_lockedempty_audience
  • 422İçerik politikasına takıldı (content_policy).content_policy
  • 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).

Gönderilmemiş kampanyayı siler

DELETE/api/v1/campaigns/{id}

Yalnız henüz gönderim yapılmamış draft, pending_approval ve cancelled kampanyalar silinir; başlamışsa 409 campaign_started döner. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
deleteCampaign · delete_campaign
MCP aracı
deleteCampaigngeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/campaigns/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).
  • 409İşlem bu durumda yapılamıyor; kod nedeni söyler.campaign_started
  • 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.

Bitmemiş kampanyayı iptal et

POST/api/v1/campaigns/{id}/cancel

Gönderim sürüyorsa kalan alıcılara gitmez; gönderilmiş mesajlar geri alınmaz. Kapsam: write.

Kapsam
write
SDK metodu
cancelCampaign · cancel_campaign
MCP aracı
cancelCampaigngeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetKampanya kimliği

Örnek istek

curl -X POST "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel" \
  -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",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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.

Varyant sonuçları ve A/B kararı

GET/api/v1/campaigns/{id}/results

Hedef, gönderilen, başarısız ve yanıt sayıları; otomatik kazananda A/B aşaması ve kararı. Yalnız okur: API gönderim başlatmaz ve onay vermez, kampanya panelde dört göz onayıyla başlar. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
getCampaignResults · get_campaign_results
MCP aracı
getCampaignResultssalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

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

Örnek yanıt (200)

JSON
{
  "data": {
    "campaign_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "replied_count": 1,
    "variants": [
      {
        "variant": "a",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 1
      }
    ],
    "remaining_variants": [
      {
        "variant": "a",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 1
      }
    ],
    "ab_stage": "test",
    "ab_test_percent": 1,
    "ab_wait_hours": 1,
    "ab_decide_at": "2026-11-06T09:00:00.000Z",
    "ab_winner": "a",
    "ab_decision": {
      "reason": "string",
      "metric": "string",
      "a": {
        "sent": 1,
        "replied": 1,
        "read": 1
      },
      "b": {
        "sent": 1,
        "replied": 1,
        "read": 1
      }
    },
    "ab_decided_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.

Segmentle eşleşen izinli kişileri sayar

POST/api/v1/campaigns/audience-count

Yan etkisizdir, hiçbir şey kaydetmez. Kitleyi yalnız izinli kişiler oluşturur; konu verilirse o konuyu kapatanlar çıkar. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
countCampaignAudience · count_campaign_audience
MCP aracı
countCampaignAudiencesalt okunur

Gövde alanları

AdTürZorunluAçıklama
bot_iduuidevet
segmentobjecthayırEtiket, son görülme, sipariş, kaynak, özel alan ve sıcaklık koşulları; createCampaign ile aynı biçim. Boş nesne: botun bütün izinli kişileri.
topicstringhayırlen ≤ 40

Örnek istek

curl -X POST "https://hiboty.com/api/v1/campaigns/audience-count" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","segment":{"include_tags":["vip"]},"topic":"firsat"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "audience_count": 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.

Önerilen gönderim saati

GET/api/v1/campaigns/best-time

Son 90 günün gelen mesajlarından, sessiz saat ve mesai kurallarına uyan en etkili gün ve saat; veri azsa öneri boş döner ve reason nedeni söyler. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
getCampaignBestTime · get_campaign_best_time
MCP aracı
getCampaignBestTimesalt okunur

Parametreler

AdTürZorunluAçıklama
bot_idsorguuuidevetBot kimliği

Örnek istek

curl -X GET "https://hiboty.com/api/v1/campaigns/best-time?bot_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "suggestion": {
      "weekday": 1,
      "hour": 1,
      "interactions": 1
    },
    "reason": "veri_az",
    "interactions": 1,
    "contacts": 1,
    "next_at": "2026-11-06T09:00:00.000Z",
    "timezone": "Europe/Istanbul"
  }
}

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.

Büyüme kampanyalarını listeler

GET/api/v1/growth-campaigns

Telegram büyüme kampanyaları (en yeni önce, en fazla 100); bağlı kaynak sayısı, dönemde kazanılan yeni kişi ve hedefe ilerleme ile. Bot kısıtlı üye yalnız erişebildiği botların bağlantılarını sayar. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
listGrowthCampaigns · list_growth_campaigns
MCP aracı
listGrowthCampaignssalt 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/growth-campaigns?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "goal_contacts": 1,
      "starts_on": "string",
      "ends_on": "string",
      "budget": {
        "amount": 1,
        "currency": "USD"
      },
      "status": "scheduled",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z",
      "acquisition_links": 1,
      "invite_links": 1,
      "new_contacts": 1,
      "progress_percent": 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.

Büyüme kampanyası oluşturur

POST/api/v1/growth-campaigns

Hedef kişi, dönem (organizasyon günü, bitiş dahil, en fazla 365 gün) ve isteğe bağlı bütçeyle kampanya açar. Kaynaklar addGrowthCampaignSource ile bağlanır. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
createGrowthCampaign · create_growth_campaign
MCP aracı
createGrowthCampaign

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
namestringevetlen 1–80
goal_contactsintegerevetval 1–10000000
starts_ondateevet
ends_ondateevet
budget_amountnumber | nullhayırval ≥ 0
budget_currencyenumhayırTRY | USD | EUR

Örnek istek

curl -X POST "https://hiboty.com/api/v1/growth-campaigns" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"Instagram launch","goal_contacts":500,"starts_on":"2026-11-01","ends_on":"2026-11-30","budget_amount":7500,"budget_currency":"TRY"}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.
  • 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.

Büyüme kampanyasını getirir

GET/api/v1/growth-campaigns/{id}

Kampanyanın ayarları. Huni ve kaynak karşılaştırması getGrowthCampaignReport ile alınır. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
getGrowthCampaign · get_growth_campaign
MCP aracı
getGrowthCampaignsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

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

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.

Büyüme kampanyasını günceller

PATCH/api/v1/growth-campaigns/{id}

Verilen alanlar değişir; sonuç oluşturma kurallarıyla doğrulanır. budget_amount null bütçeyi kaldırır. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
updateGrowthCampaign · update_growth_campaign
MCP aracı
updateGrowthCampaign

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
namestringhayırlen 1–80
goal_contactsintegerhayırval 1–10000000
starts_ondatehayır
ends_ondatehayır
budget_amountnumber | nullhayırval ≥ 0
budget_currencyenumhayırTRY | USD | EUR

Örnek istek

curl -X PATCH "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal_contacts":750,"ends_on":"2026-12-15"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.

Büyüme kampanyasını siler

DELETE/api/v1/growth-campaigns/{id}

Kampanya silinir; bağlı edinme ve davet bağlantıları, sayaçları ve kişilerin kaynak bilgisi kalır. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
deleteGrowthCampaign · delete_growth_campaign
MCP aracı
deleteGrowthCampaigngeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/growth-campaigns/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.

Büyüme kampanyası hunisi ve kaynak karşılaştırması

GET/api/v1/growth-campaigns/{id}/report

Huni: izlenen tıklama (Hiboty /g/<kod> düğmesi; Telegram bağlantı tıklaması vermez), başlatma, yeni kişi, sipariş veren kişi, sipariş, ödeme ve davet katılımı. Tıklama, başlatma ve katılım bağlantının toplam sayacıdır; yeni kişi dönemde, siparişler bu kişilerin kayıttan sonraki 30 günüdür (getRevenueReport ile aynı kural). Maliyet: bağlantılara elle girilen ve içe aktarılan (importReportCosts kind link) tutarlar; yoksa bütçe. Kaynak başına aynı ölçüler döner. Kapsam: campaigns:read.

Kapsam
campaigns:read
SDK metodu
getGrowthCampaignReport · get_growth_campaign_report
MCP aracı
getGrowthCampaignReportsalt okunur

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği

Örnek istek

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

Örnek yanıt (200)

JSON
{
  "data": {
    "campaign": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "goal_contacts": 1,
      "starts_on": "string",
      "ends_on": "string",
      "budget": {
        "amount": 1,
        "currency": "USD"
      },
      "status": "scheduled",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z",
      "acquisition_links": 1,
      "invite_links": 1,
      "new_contacts": 1,
      "progress_percent": 1
    },
    "range": {
      "from": "string",
      "to": "string"
    },
    "days_left": 1,
    "progress": {
      "new_contacts": 1,
      "goal_contacts": 1,
      "percent": 1,
      "remaining": 1
    },
    "funnel": {
      "clicks": 1,
      "starts": 1,
      "new_contacts": 1,
      "activated_contacts": 1,
      "orders": 1,
      "paid_orders": 1,
      "joins": 1,
      "leaves": 1
    },
    "rates": {
      "contacts_per_start": 1,
      "activation": 1,
      "paid_per_order": 1,
      "member_retention": 1
    },
    "revenue": {
      "orders": 1,
      "cancelled": 1,
      "refunded": 1,
      "gross": {
        "amounts": {
          "key": 1
        },
        "stars": 1
      },
      "net": {
        "amounts": {
          "key": 1
        },
        "stars": 1
      },
      "unpriced_items": 1
    },
    "spend": {
      "amount": 1,
      "currency": "USD",
      "mixed": {
        "key": 1
      }
    },
    "cost": {
      "amount": 1,
      "currency": "USD",
      "mixed": {
        "key": 1
      }
    },
    "cost_source": "spend",
    "budget_usage_percent": 1,
    "cost_per_contact": {
      "value": 1,
      "currency": "USD",
      "reason": "maliyet_yok"
    },
    "roi": {
      "value": 1,
      "reason": "maliyet_yok"
    },
    "acquisition_links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "kind": "acquisition_link",
        "name": "Hiboty",
        "code": "ornek",
        "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "bot_name": "string",
        "url": "https://example.com/hook",
        "clicks": 1,
        "starts": 1,
        "new_contacts": 1,
        "activated_contacts": 1,
        "paid_orders": 1,
        "revenue": {
          "orders": 1,
          "cancelled": 1,
          "refunded": 1,
          "gross": {
            "amounts": {},
            "stars": 1
          },
          "net": {
            "amounts": {},
            "stars": 1
          },
          "unpriced_items": 1
        },
        "cost": {
          "amount": 1,
          "currency": "USD",
          "mixed": {
            "key": 1
          }
        },
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "maliyet_yok"
        },
        "roi": {
          "value": 1,
          "reason": "maliyet_yok"
        }
      }
    ],
    "invite_links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "kind": "invite_link",
        "name": "Hiboty",
        "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "community_name": "string",
        "invite_link": "string",
        "joins": 1,
        "leaves": 1,
        "net_members": 1,
        "revoked": true,
        "expires_at": "2026-11-06T09:00:00.000Z"
      }
    ],
    "truncated": 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.

Kampanyaya kaynak bağlar ya da yeni bağlantı açar

POST/api/v1/growth-campaigns/{id}/sources

kind acquisition_link: source_id ile mevcut Telegram edinme bağlantısı bağlanır ya da bot_id + name (+ code) ile yeni start bağlantısı (t.me/<bot>?start=<kod>) açılır. kind invite_link: source_id ile mevcut davet bağlantısı ya da community_id + name (+ member_limit, expires_in_days, join_request) ile Telegram'da yeni davet bağlantısı açılır. Başka kampanyadaki bağlantı bu kampanyaya taşınır. Kampanya başına en fazla 50 kaynak. Telegram hatası 502 channel_error döner. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
addGrowthCampaignSource · add_growth_campaign_source
MCP aracı
addGrowthCampaignSourcedış 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

Gövde alanları

AdTürZorunluAçıklama
kindenumevetacquisition_link | invite_link
source_iduuidhayır
bot_iduuidhayır
community_iduuidhayır
namestringhayırlen ≤ 40
codestringhayırlen ≤ 32
member_limitinteger | nullhayırval 1–99999
expires_in_daysinteger | nullhayırval 1–365
join_requestbooleanhayır

Örnek istek

curl -X POST "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/sources" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"kind":"acquisition_link","bot_id":"00000000-0000-4000-8000-000000000001","name":"Instagram biyografi","code":"ig-bio"}'

Örnek yanıt (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "kind": "acquisition_link",
    "name": "Hiboty",
    "code": "ornek",
    "url": "https://example.com/hook"
  }
}

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.
  • 502Kanal ya da dış servis hatası (channel_error).channel_error

Kaynağı kampanyadan ayırır

DELETE/api/v1/growth-campaigns/{id}/sources/{source_id}

Bağlantı kampanyadan çıkar; bağlantının kendisi, Telegram'daki davet bağlantısı ve sayaçlar kalır. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
removeGrowthCampaignSource · remove_growth_campaign_source
MCP aracı
removeGrowthCampaignSourcegeri alınamaz

Parametreler

AdTürZorunluAçıklama
idyoluuidevetid kimliği
source_idyoluuidevetsource_id kimliği

Örnek istek

curl -X DELETE "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/sources/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.