Documentation Index
Fetch the complete documentation index at: https://docs.iletiniz.com/llms.txt
Use this file to discover all available pages before exploring further.
İletiniz aşağıdaki event tiplerini destekler:
| Event | Tetikleyici |
|---|
message.sent | Mesaj sağlayıcıya başarıyla iletildi. |
message.delivered | DLR ile teslim onaylandı. |
message.failed | Sağlayıcı/operatör reddetti, TTL doldu, kara liste veya unknown sonucu (kalıcı). |
contact.opt_out | Alıcı opt-out talebi gönderdi. (yol haritasında; şu an üretilmiyor) |
Ortak Zarf
Tüm event’ler aynı dış zarf ile gelir:
{
"id": "f9c8e7d6a5b4c3d2e1f0a9b8c7d6e5f4",
"event": "message.delivered",
"workspace_id": 42,
"occurred_at": "2026-05-13T20:14:04.512Z",
"data": { /* event'e özgü, aşağıda */ }
}
| Alan | Açıklama |
|---|
id | 32-karakter hex. Aynı (event, mesaj) çifti her zaman aynı id’yi taşır — idempotent tüketim için bu alanı kullanın. |
event | Yukarıdaki event tiplerinden biri. |
workspace_id | Workspace numeric ID’si. |
occurred_at | Event üretildiği an, ISO 8601 UTC. |
data | Event’e özgü payload (aşağıda her event için tam yapı). |
message.sent
Mesaj sağlayıcıya teslim edildiğinde fırlatılır. Bu, alıcının cihazına teslim olduğu anlamına gelmez — yalnızca aggregator/Bot API kabul etti.
Düz metin gönderim sonrası
{
"id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"event": "message.sent",
"workspace_id": 42,
"occurred_at": "2026-05-13T20:14:01.230Z",
"data": {
"message_id": 894521,
"job_id": "k7m4n2p9q8r5s1t6",
"to": "+905551234567",
"provider": "netgsm",
"segments": 1,
"sent_at": "2026-05-13T20:14:01.230Z"
}
}
Şablon ile gönderim sonrası
Şablonla gönderildiyse data içinde ek olarak template alanı bulunur:
{
"id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"event": "message.sent",
"workspace_id": 42,
"occurred_at": "2026-05-13T20:14:01.230Z",
"data": {
"message_id": 894522,
"job_id": "a3b6c9d2e5f8g1h4",
"to": "+905551112233",
"provider": "netgsm",
"segments": 1,
"sent_at": "2026-05-13T20:14:01.230Z",
"template": "siparis_kargoda"
}
}
data Alanları
| Alan | Tip | Açıklama |
|---|
message_id | number | Mesajın iletiniz tarafındaki sayısal kimliği. job_id ile birlikte audit/log eşleştirme için tutulabilir. |
job_id | string | POST /v1/messages yanıtındaki job_id. |
to | string | Normalize edilmiş alıcı. |
provider | string | Kullanılan sağlayıcı kodu. |
segments | number | SMS segment sayısı (Telegram/WhatsApp için 1). |
sent_at | string | Sağlayıcıya teslim edildiği an, ISO 8601 UTC. |
template | string? | Yalnızca şablonla gönderildiyse; şablonun key değeri. |
message.delivered
Sağlayıcıdan DLR ile teslim raporu alındığında fırlatılır. Yalnızca SMS ve WhatsApp kanallarında anlamlıdır; Telegram’da message.sent zaten teslim demektir, ayrıca delivered event’i üretilmez.
{
"id": "f9c8e7d6a5b4c3d2e1f0a9b8c7d6e5f4",
"event": "message.delivered",
"workspace_id": 42,
"occurred_at": "2026-05-13T20:14:04.512Z",
"data": {
"message_id": 894521,
"status": "delivered",
"error_code": null,
"error_message": null,
"finalized_at": "2026-05-13T20:14:04.512Z"
}
}
data Alanları
| Alan | Tip | Açıklama |
|---|
message_id | number | İlgili mesajın sayısal kimliği. message.sent event’inde gelen değerle eşleşir. |
status | enum | Her zaman delivered. |
error_code | string | null | Bu event’te daima null. |
error_message | string | null | Bu event’te daima null. |
finalized_at | string | Status’un finalize edildiği an, ISO 8601 UTC. |
job_id, to, provider gibi alanların bu event’in data payload’unda olmadığına dikkat edin. Bunlara ihtiyacınız varsa message_id üzerinden message.sent payload’unu kendi tarafınızda eşleştirin (önerilen) veya GET /v1/messages/{job_id} ile detayları çekin.
message.failed
Sağlayıcı/operatör reddetti, TTL doldu, alıcı kara liste, içerik filtresi, veya DLR sorgusu unknown ile finalize oldu. Bu event’in data.status alanı tam final durumu söyler.
{
"id": "0e1d2c3b4a596877665544332211ffee",
"event": "message.failed",
"workspace_id": 42,
"occurred_at": "2026-05-13T20:18:12.000Z",
"data": {
"message_id": 894699,
"status": "expired",
"error_code": "DELIVERY_TIMEOUT",
"error_message": "Sağlayıcı TTL içinde teslim raporu alamadı.",
"finalized_at": "2026-05-13T20:18:12.000Z"
}
}
data Alanları
| Alan | Tip | Açıklama |
|---|
message_id | number | İlgili mesajın sayısal kimliği. |
status | enum | Final durum: failed, expired, rejected veya unknown. |
error_code | string | null | Sağlayıcının dönen kodu veya iletiniz’in normalize ettiği sabit slug (örn. netgsm_40, verimor_INVALID_SOURCE_ADDRESS, DELIVERY_TIMEOUT). |
error_message | string | null | İnsan tarafından okunabilir hata mesajı. |
finalized_at | string | Final duruma geçildiği an, ISO 8601 UTC. |
Status Değerleri
data.status | Anlamı |
|---|
failed | Sağlayıcı/operatör gönderimi reddetti veya kalıcı hata aldı. |
expired | Sağlayıcı TTL içinde teslim edemedi (alıcı kapalı, sinyal yok). |
rejected | Alıcı kara liste, opt-out, içerik filtresi. |
unknown | DLR sorgusu sınırlı denemeden sonra kesin sonuç alamadı. |
Idempotency
Aynı id değerini ikinci kez gördüğünüzde işlemi tekrarlamayın. Sebepleri:
- Endpoint’iniz 5xx döndü → yeniden denemede aynı
id geliyor.
- Network bölünmesinde 2xx yanıtınız bize ulaşmadı → yeniden denenir.
Doğru pratik: id’yi tekil bir indekste tutun (örn. Redis SET-NX, veya kendi veritabanınızda unique constraint). Var ise no-op dönün, 200 ile bitirin.
Mesaj Sayısal Kimliği
Her event payload’unda görünen message_id alanı iletiniz tarafındaki sayısal kimliktir ve job_id ile bire-bir eşlenir. message.sent event’ini aldığınızda hem job_id’yi hem de message_id’yi kendi tarafınızda eşleştirip saklarsanız, sonraki message.delivered/message.failed event’lerinde (yalnızca message_id taşıyan) doğru mesajı bulabilirsiniz.
