Message Limit

---

Otantikasyon

Bu başlığı her istekte gönderiniz.

{
  "Authorization": "Bearer ${token}"
}

🔒 Mesaj Limiti

Bu uç nokta, hesabınızın mesaj gönderim haklarını ve bakiyesini tek bir yanıtta döner. Yanıtta üç farklı bilgi yer alır:

Konu	Ne anlatır?	İlgili bölüm
Servis mesajı hakkı	Müşteri size yazdıktan sonra ücretsiz gönderebileceğiniz yanıt sayısı	Servis mesajı
Mesaj şablonu hakkı	Paketinize dahil olan aylık şablon gönderim hakkı	Mesaj şablonu
Kredi	Ücretli gönderimler için hesabınıza yüklediğiniz bakiye	Kredi

İstek herhangi bir gövde ya da parametre gerektirmez. Kimlik doğrulaması yapılmış olması yeterlidir.

GET

https://backend.helorobo.com/agent-app/message-limit

Response

{
  "trace_id": "<trace_id>",
  "data": {
    "monthly_conversation_limit": 2003,
    "limit_type": "COUNT",
    "monthly_credit_limit": 0,
    "free_service_message_limit": 15,
    "free_service_message_usage": 30,
    "free_service_message_channels": [
      {
        "channel_id": "<channel_id>",
        "name": "Mağaza Hattı",
        "phone_number": "905551112233",
        "waba_id": "<waba_id_1>",
        "usage": 9
      },
      {
        "channel_id": "<channel_id>",
        "name": "Destek Hattı",
        "phone_number": "905554445566",
        "waba_id": "<waba_id_2>",
        "usage": 4
      },
      {
        "channel_id": "<channel_id>",
        "name": "Satış Hattı",
        "phone_number": "905557778899",
        "waba_id": "<waba_id_2>",
        "usage": 17
      }
    ],
    "package_price": 4999,
    "package_currency": "TRY",
    "message_count": 13,
    "free_message_count": 0,
    "total_cost": 17.621594995278564,
    "country_conversation_limits": [
      {
        "country": "TR",
        "limit": 2000,
        "message_count": 13,
        "remaining_conversation": 1987
      },
      {
        "country": "CA",
        "limit": 1,
        "message_count": 0,
        "remaining_conversation": 1
      }
    ],
    "billtekrom": {
      "total_payment_cost": 100,
      "currency_code": "USD"
    }
  }
}

Alanlar

Alan	Tip	Açıklama
limit_type	string	Şablon hakkınızın neye göre takip edildiğini belirtir. COUNT ise adet, CREDIT ise tutar üzerinden takip edilir.
monthly_conversation_limit	number	Aylık toplam şablon gönderim hakkınız (adet). limit_type değeri COUNT olduğunda kullanılır.
monthly_credit_limit	number	Aylık toplam şablon gönderim hakkınız (tutar). limit_type değeri CREDIT olduğunda kullanılır.
message_count	number	Bu ay gönderdiğiniz şablon mesajı sayısı.
total_cost	number	Bu ay yapılan ücretli gönderimlerin toplam tutarı. Değer yuvarlanmadan döner.
country_conversation_limits	array	Paketinizde ülke bazlı haklar varsa her ülkenin hakkı ve kullanımı.
free_service_message_limit	number	Bir telefon numarasının aylık ücretsiz servis mesajı hakkı.
free_service_message_usage	number	Tüm numaralarınızın bu ay gönderdiği toplam servis mesajı sayısı.
free_service_message_channels	array	Her telefon numarasının servis mesajı kullanımı.
package_price	number	Paketinizin ücreti.
package_currency	string	Paket ücretinin para birimi.
billtekrom / shopify	object	Kredi bakiyenizin bilgisi. Hesabınızın faturalandırıldığı yere göre bu iki nesneden yalnızca biri döner. Alanları aynıdır.

Servis mesajı

Servis mesajı nedir?

Bir müşteri size WhatsApp üzerinden yazdığında, o andan itibaren 24 saat boyunca müşteriye şablon kullanmadan serbest metinle yanıt verebilirsiniz. Bu 24 saat içinde gönderdiğiniz yanıtlara servis mesajı denir.

Kampanya, sipariş bildirimi ve doğrulama mesajları servis mesajı sayılmaz. Bunlar şablon mesajıdır ve Mesaj şablonu bölümündeki hakkınızdan düşer.

Hak nasıl dağıtılır?

Ücretsiz servis mesajı hakkı hesabınıza toplu olarak değil, her telefon numarasına ayrı ayrı verilir. Bunu bir numaraya ait kota gibi düşünebilirsiniz:

• free_service_message_limit, tek bir numaranın kotasıdır. Hesabınızda üç numara varsa her birinin ayrı bir kotası olur.
• Farklı numaralar aynı WABA (WhatsApp Business hesabı) altında olsa bile kotaları birbirinden ayrıdır.
• Bir numaranın kullanmadığı hak başka bir numaraya aktarılmaz. Bir numaranın kotası dolduğunda, diğer numaralarda hak kalmış olsa bile o numaradan giden mesajlar ücretli olur.

Kalan hakkı hesaplama

Haklar numaralar arasında paylaşılmadığı için kalan hakkı her numara için ayrı ayrı hesaplamanız gerekir. Toplam hakkı toplam kullanımdan çıkarmak yanlış sonuç verebilir.

Örnekte numara başına hak 15'tir. Her numaranın kullanımı free_service_message_channels listesindeki usage alanından okunur:

	Nasıl hesaplanır?	Mağaza Hattı	Destek Hattı	Satış Hattı
Hak	free_service_message_limit	15	15	15
Kullanım	usage	9	4	17
Kalan	Hak − kullanım (sonuç eksiyse 0)	6	11	0
Aşım	Kullanım − hak (sonuç eksiyse 0)	0	0	2

Hesap genelindeki tabloyu bu numara bazlı sonuçlardan oluşturursunuz:

	Nasıl hesaplanır?	Örnek
Toplam hak	free_service_message_limit × numara sayısı	15 × 3 = 45
Kullanım	free_service_message_usage	30
Kalan	Numaraların kalan haklarının toplamı	6 + 11 + 0 = 17
Aşım	Numaraların aşımlarının toplamı	0 + 0 + 2 = 2

Dikkat

Bu örnekte toplam haktan toplam kullanımı çıkarırsanız (45 − 30) kalanı 15 bulursunuz. Doğru sonuç 17'dir. Aradaki fark, Satış Hattı'nın kendi kotasını 2 mesaj aşmasından kaynaklanır: bu 2 mesaj diğer numaraların hakkından düşülmez, krediden ücretlendirilir.

Mesaj şablonu

Mesaj şablonu nedir?

Mesaj şablonları, Meta tarafından önceden onaylanmış hazır mesajlardır. Müşteriye 24 saatlik pencere dışında mesaj göndermek istediğinizde şablon kullanmanız gerekir. Kampanya duyuruları, sipariş bildirimleri ve doğrulama kodları bu gruba girer.

Şablon hakkınız paketinize göre iki şekilde takip edilir. Hangisinin geçerli olduğunu limit_type alanından anlarsınız.

Adet ile takip (COUNT)

limit_type değeri COUNT ise paketiniz size aylık belirli sayıda şablon gönderim hakkı verir.

	Alan	Örnek
Toplam hak	monthly_conversation_limit	2003
Kullanım	message_count	13
Kalan	Toplam hak − kullanım	1990

Kullanım toplam hakkı geçerse aradaki fark aşım adedini verir. Örnekteki hesapta aşım yoktur.

Ülke bazlı haklar

Bazı paketlerde şablon hakkı ülkelere göre ayrılır. Örneğin Türkiye'deki numaralara gönderim için ayrı, Kanada'daki numaralara gönderim için ayrı bir hak tanımlanabilir. Paketinizde böyle bir ayrım varsa her ülkenin hakkı country_conversation_limits listesinde ayrı olarak döner. country alanı iki harfli ülke kodudur.

	Alan	Türkiye (TR)	Kanada (CA)
Toplam hak	limit	2000	1
Kullanım	message_count	13	0
Kalan	remaining_conversation	1987	1

Ülke bazlı kalan hak yanıtta hazır olarak döner (remaining_conversation), ayrıca hesaplamanıza gerek yoktur.

Tutar ile takip (CREDIT)

limit_type değeri CREDIT ise paketiniz size adet yerine aylık bir harcama tutarı tanır. Her şablon gönderiminin ücreti bu tutardan düşer.

	Alan
Toplam hak	monthly_credit_limit
Kullanım	total_cost
Kalan	Toplam hak − kullanım

Bu durumda da gönderdiğiniz şablon sayısını message_count alanından görebilirsiniz.

Kredi

Kredi nedir?

Kredi, ücretli WhatsApp gönderimleri için hesabınıza yüklediğiniz bakiyedir. Paket hakkınızı aşan gönderimler ve ücretsiz hakkı dolan numaralardan giden servis mesajları bu bakiyeden ücretlendirilir.

Kredi bilgisi, hesabınızın faturalandırıldığı yere göre farklı bir nesnede döner:

• Billtekrom üzerinden faturalandırılan hesaplarda billtekrom nesnesinde,
• Shopify üzerinden faturalandırılan hesaplarda shopify nesnesinde.

İki nesnenin alanları aynıdır, hesaplama da aynı şekilde yapılır.

Kalan krediyi hesaplama

	Alan	Örnek
Yüklenen kredi	total_payment_cost	100 USD
Harcanan	all_total_cost (bu alan yoksa total_cost)	17,62 USD
Kalan	Yüklenen − harcanan	82,38 USD

Para birimi currency_code alanında belirtilir.

total_cost değeri yuvarlanmadan döner (örnekte 17.621594995278564). Kullanıcıya gösterirken iki ondalık basamağa yuvarlamanızı öneririz.

Paket ücreti

package_price ve package_currency alanları, kullandığınız paketin ücretini ve para birimini gösterir. Örnekteki paketin ücreti 4999 TRY'dir.