Bir kişiye mesaj gönderir
POST/api/v1/messages
Kişi daha önce bota yazmış olmalıdır. message (serbest metin) ya da template (yalnız WhatsApp, onaylı Meta şablonu) alanlarından tam olarak biri gönderilir. Yeniden denemede çift mesajı önlemek için Idempotency-Key kullanın. Plan sınırını aşan bot gönderemez (403 bot_plan_restricted). Kapsam: messages:send.
- Kapsam
messages:send- SDK metodu
- sendMessage · send_message
- MCP aracı
sendMessagedış etkili
Parametreler
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
Idempotency-Keybaşlık | string | hayı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ı
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
bot_id | uuid | evet | |
to | string | evet | Telegram chat id ya da WhatsApp numarası (kişi daha önce bota yazmış olmalı)len 3–64 |
message | string | hayır | len 1–4000 |
template | object | hayır | |
template.name | string | evet | |
template.language | string | evet | |
template.params | string[] | hayır | {{isim}} ve {{özel_alan}} değişkenleri kişiye göre dolduruluritems ≤ 20 |
Örnek istek
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Merhaba!"}'Örnek yanıt (201)
{
"id": "string",
"status": "sent",
"bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"to": "string",
"template": "string"
}Olası hatalar
400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.bot_plan_restricted404Kayı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).