API başvurusu

Raporlar

Bu gruptaki 10 uç.

Genel rapor özeti

GET/api/v1/reports/overview

Bu ayın mesaj ve AI kullanımı (organizasyon geneli), kişi, izinli ve devredilen sohbet sayıları; seçili dönemin bot, saat ve gün dağılımı; kampanya özeti. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getReportOverview · get_report_overview
MCP aracı
getReportOverviewsalt okunur

Parametreler

AdTürZorunluAçıklama
dayssorguenumhayırDönem (gün): 7, 30 ya da 90; varsayılan 307 | 30 | 90, default 30

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/overview" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "days": 1,
    "usage": {
      "messages": {
        "used": 1,
        "limit": 1
      },
      "ai_replies": {
        "used": 1,
        "limit": 1,
        "effective_limit": 1,
        "own_key": true
      },
      "ai_tokens": 1
    },
    "contacts": {
      "total": 1,
      "opted_in": 1
    },
    "conversations": {
      "total": 1,
      "handoff": 1
    },
    "bots": [
      {
        "name": "Hiboty",
        "incoming": 1,
        "ai": 1,
        "agent": 1
      }
    ],
    "hourly": [
      1
    ],
    "daily": [
      {
        "date": "string",
        "ai": 1,
        "agent": 1
      }
    ],
    "campaigns": {
      "total": 1,
      "completed": 1,
      "delivered": 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.

Teslim telemetrisi

GET/api/v1/reports/delivery

Giden mesajların başarı oranı, kaynak bazında başarısızlar ve hata nedenleri. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getDeliveryTelemetry · get_delivery_telemetry
MCP aracı
getDeliveryTelemetrysalt okunur

Parametreler

AdTürZorunluAçıklama
dayssorguenumhayırDönem (gün): 7, 30 ya da 90; varsayılan 307 | 30 | 90, default 30

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/delivery" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "days": 1,
    "succeeded": 1,
    "failed": 1,
    "success_rate": 1,
    "recovered": 1,
    "sources": [
      {
        "sender": "string",
        "succeeded": 1,
        "failed": 1
      }
    ],
    "reasons": [
      {
        "reason": "string",
        "count": 1
      }
    ],
    "samples": [
      {
        "error": "string",
        "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.
  • 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.

Temsilci performansı

GET/api/v1/reports/agents

İlk yanıt ve çözüm süreleri, SLA uyumu, bekleyen sohbetler ve temsilci bazlı sayılar. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getAgentReport · get_agent_report
MCP aracı
getAgentReportsalt okunur

Parametreler

AdTürZorunluAçıklama
dayssorguenumhayırDönem (gün): 7, 30 ya da 90; varsayılan 307 | 30 | 90, default 30

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/agents" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "days": 1,
    "handoffs": 1,
    "resolved": 1,
    "first_reply_median_seconds": 1,
    "resolution_average_seconds": 1,
    "sla_target_minutes": 1,
    "sla_compliance": 1,
    "waiting": 1,
    "oldest_waiting_seconds": 1,
    "agents": [
      {
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "open": 1,
        "replies": 1,
        "first_reply_median_seconds": 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.

Memnuniyet raporu

GET/api/v1/reports/csat

Ortalama puan, memnun oranı, 1-5 dağılımı ve temsilci bazında ortalama. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getCsatReport · get_csat_report
MCP aracı
getCsatReportsalt okunur

Parametreler

AdTürZorunluAçıklama
dayssorguenumhayırDönem (gün): 7, 30 ya da 90; varsayılan 307 | 30 | 90, default 30

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/csat" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "days": 1,
    "enabled": true,
    "responses": 1,
    "average": 1,
    "satisfied_rate": 1,
    "distribution": [
      1
    ],
    "agents": [
      {
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "responses": 1,
        "average": 1,
        "satisfied_rate": 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.

AI kalite raporu

GET/api/v1/reports/ai-quality

Temsilcilerin AI yanıtlarına verdiği geri bildirimin özeti. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getAiQualityReport · get_ai_quality_report
MCP aracı
getAiQualityReportsalt okunur

Parametreler

AdTürZorunluAçıklama
dayssorguenumhayırDönem (gün): 7, 30 ya da 90; varsayılan 307 | 30 | 90, default 30

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/ai-quality" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "days": 1,
    "ai_replies": 1,
    "rated": 1,
    "liked": 1,
    "disliked": 1,
    "like_rate": 1,
    "coverage": 1,
    "attributed_replies": 1,
    "unsourced_replies": 1,
    "unsourced_rate": 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.

Kitle kohortları

GET/api/v1/reports/cohorts

Son 8 haftanın kişi kohortları ve sonraki haftalarda bota yeniden yazma oranı. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getCohortReport · get_cohort_report
MCP aracı
getCohortReportsalt okunur

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/cohorts" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "new_contacts": 1,
    "first_week_return_rate": 1,
    "cohorts": [
      {
        "week": "string",
        "size": 1,
        "rates": [
          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.

Gelir atfı ve ROI

GET/api/v1/reports/revenue

Kampanya, edinme bağlantısı ve tıkla-WhatsApp reklamlarına atfedilen gelir (Mini App ve mağaza siparişleri), maliyet ve ROI; bot sohbetiyle eşleşen mağaza siparişleri totals.store içindedir. from ve to birlikte verilir (YYYY-MM-DD, organizasyon günü); verilmezse son 30 gün. Aralık en çok 1 yıldır. Üye rolü yalnız erişebildiği botların verisini görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getRevenueReport · get_revenue_report
MCP aracı
getRevenueReportsalt okunur

Parametreler

AdTürZorunluAçıklama
fromsorgudatehayırBaşlangıç günü (YYYY-MM-DD)
tosorgudatehayırBitiş günü, dahil (YYYY-MM-DD)

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/revenue" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "from": "string",
    "to": "string",
    "range_clamped": true,
    "campaigns": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "bot_name": "string",
        "channel": "string",
        "summary": {
          "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
          }
        },
        "manual_cost": {
          "amount": 1,
          "currency": "USD"
        },
        "roi": {
          "value": 1,
          "reason": "string"
        }
      }
    ],
    "links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "bot_name": "string",
        "channel": "string",
        "summary": {
          "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
          }
        },
        "manual_cost": {
          "amount": 1,
          "currency": "USD"
        },
        "roi": {
          "value": 1,
          "reason": "string"
        },
        "code": "ornek",
        "new_contacts": 1,
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "string"
        }
      }
    ],
    "ads": [
      {
        "id": "string",
        "name": "Hiboty",
        "source_type": "string",
        "source_url": "https://example.com/a.png",
        "new_contacts": 1,
        "summary": {
          "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
          }
        },
        "roi": {
          "value": 1,
          "reason": "string"
        },
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "string"
        }
      }
    ],
    "totals": {
      "campaigns": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "links": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "store": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "ads": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      }
    },
    "conversions": {
      "campaigns": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "links": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "store": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "ads": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      }
    },
    "exchange_rate": {
      "usd_try": 1,
      "date": "string"
    },
    "out_of_scope": {
      "miniapp_orders": 1,
      "orders_without_contact": 1,
      "store_orders": 1,
      "store_unmatched": 1
    },
    "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.
  • 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.

Plan ve kullanım

GET/api/v1/reports/usage

Plan, limitler, bu ayın mesaj ve AI yanıt kullanımı, token toplamı, AI ve mesaj ek bakiyesi. Organizasyon genelidir. group_by=bot|channel verilirse breakdown alanında bu ayın giden mesaj, AI yanıtı, medya ve Meta tahmini bot ya da kanal başına döner; satırların toplamı genel toplamla eşleşir. Üye rolü kırılımda yalnız erişebildiği botları görür. Kapsam: reports:read.

Kapsam
reports:read
SDK metodu
getUsageReport · get_usage_report
MCP aracı
getUsageReportsalt okunur

Parametreler

AdTürZorunluAçıklama
group_bysorguenumhayırKullanım kırılımı: bot ya da channelbot | channel

Örnek istek

curl -X GET "https://hiboty.com/api/v1/reports/usage" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Örnek yanıt (200)

JSON
{
  "data": {
    "plan": "string",
    "limits": {
      "bots": 1,
      "seats": 1,
      "workspaces": 1,
      "monthly_messages": 1,
      "monthly_ai_replies": 1,
      "campaigns": true,
      "api": true,
      "miniapps": true
    },
    "messages": {
      "used": 1,
      "limit": 1,
      "extra_credits": 1
    },
    "ai_replies": {
      "used": 1,
      "limit": 1,
      "extra_credits": 1
    },
    "ai_tokens": {
      "input": 1,
      "output": 1,
      "total": 1
    },
    "breakdown": {
      "group_by": "bot",
      "rows": [
        {
          "key": "sehir",
          "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Hiboty",
          "channel": "telegram",
          "messages_out": 1,
          "ai_replies": 1,
          "media": 1,
          "meta_estimate_usd": 1
        }
      ],
      "totals": {
        "messages_out": 1,
        "ai_replies": 1,
        "media": 1,
        "meta_estimate_usd": 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.

Kampanya ya da bağlantı maliyetini yazar

PUT/api/v1/reports/costs/{kind}/{id}

ROI hesabının toplam maliyeti; amount null maliyeti siler. Değişiklik denetim kaydına eski ve yeni değerle yazılır. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
setReportCost · set_report_cost
MCP aracı
setReportCost

Parametreler

AdTürZorunluAçıklama
kindyolenumevetkind kimliğicampaign | link
idyoluuidevetid kimliği

Gövde alanları

AdTürZorunluAçıklama
amountnumber | nullevetval ≥ 0
currencyenumhayırTRY | USD | EUR

Örnek istek

curl -X PUT "https://hiboty.com/api/v1/reports/costs/campaign/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1250.5,"currency":"TRY"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "kind": "campaign",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "amount": 1,
    "currency": "USD"
  }
}

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.

Reklam maliyetlerini içe aktarır

POST/api/v1/reports/costs/import

Kampanya (kind campaign, ref kampanya kimliği), edinme bağlantısı (link, ref bağlantı kodu) ya da tıkla-WhatsApp reklamı (ad, ref Meta reklam kimliği source_id) için dönem maliyetlerini yazar. csv ya da rows verilir; CSV başlığı tur/kind, hedef/ref, tutar/amount, para_birimi/currency, baslangic/period_start, bitis/period_end sütunlarını taşır (ayraç virgül, noktalı virgül ya da sekme). Aynı hedef, dönem ve para birimi güncellenir. Hatalı satırlar errors içinde döner, diğerleri yazılır. Dönemi rapor aralığıyla kesişen maliyetler getRevenueReport ROI'sine eklenir. En fazla 1000 satır. Reklam API'sinden otomatik harcama çekilmez. Yönetici yetkisi gerekir. Kapsam: campaigns:write.

Kapsam
campaigns:write
SDK metodu
importReportCosts · import_report_costs
MCP aracı
importReportCosts

Gövde alanları

AdTürZorunluAçıklama
csvstringhayırCSV metni (ilk satır başlık)len ≤ 500000
rowsobject[]hayır
rows[].kindenumevetcampaign | link | ad
rows[].refstringevetlen ≤ 200
rows[].amountnumberevetval ≥ 0
rows[].currencyenumevetTRY | USD | EUR
rows[].period_startdateevet
rows[].period_enddateevet

Örnek istek

curl -X POST "https://hiboty.com/api/v1/reports/costs/import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv":"tur,hedef,tutar,para_birimi,baslangic,bitis\nad,120226305854810726,1250.50,TRY,2026-11-01,2026-11-30\nlink,INSTA-KASIM,800,TRY,2026-11-01,2026-11-30"}'

Örnek yanıt (200)

JSON
{
  "data": {
    "imported": 1,
    "updated": 1,
    "errors": [
      {
        "line": 1,
        "error": "tur"
      }
    ],
    "total": 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.