Mesaj Gönderme ve Alma

Bu rehber sizi bir API anahtarından çalışan iki yönlü bir mesaj akışına götürür: giden bir mesaj gönderin, teslim durumunu izleyin ve yanıtı kendi sunucunuzda alın. Örnek olarak SMS kullanılır — aynı üç adımlı desen (gönder → izle → al) WhatsApp, RCS, Viber ve E-posta için de geçerlidir; her biri kendi uç noktasında çalışır. Yapacaklarınız:

Mesaj gönderin
Teslim durumunu izleyin
Gelen mesajları alın
Gelen bir mesaja yanıt verin

Ön koşullar

Ayarlar → API Anahtarları altından bir API anahtarı. İnşa ederken bir sandbox anahtarı (dv_test_sk_…) kullanın — sandbox gönderimleri ücretsiz ve simüledir; hem başarı hem de hata yollarını denemeniz için belirli (deterministik) teslim fişleri döndürür. Üretime geçerken canlı bir anahtar (dv_live_sk_…) kullanırsınız.
Kullandığınız kanaldan gönderim yapabilen bir gönderici numarası. SMS için bu, sahibi olduğunuz SMS uyumlu bir numaradır (Numbers API veya Dashboard → Numbers üzerinden arayıp satın alabilirsiniz). from alanını boş bırakırsanız Orbit hedef için uygun bir gönderici seçer.
Alma adımı için herkese açık bir HTTPS URL. Geliştirme sırasında herhangi bir tünl aracı (tunneling tool) iş görür.

Tüm istekler tek bir base URL’ye gider — sandbox aynı host’tur; domain değil, anahtarınızla seçilir:

https://api.orbit.devotel.io/api/v1

Her istek, anahtarınızı X-API-Key başlığında taşıyor olur.

1. Mesaj gönderin

POST /messages/sms ile bir SMS gönderin. Yalnızca to ve body zorunludur; from isteğe bağlıdır.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Your order #1234 has shipped. Reply STATUS for tracking."
  }'

Yanıt 202 Accepted’dır — mesaj kalıcı olarak kaydedilir ve teslim için kuyruğa alınır; henüz operatöre teslim edilmemiştir. Alanlar data altında yaşar; meta, destek için loglamanız gereken request_id’yi taşır.

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "direction": "outbound",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-07-20T00:00:00Z"
  }
}

id (msg_ ve ardından 32 onaltılı karakter) takip eden tüm çağrılar için tutamaçtır — durum sorguları, teslim webhook’ları ve mesaj izleme hep bu anahtarla çalışır. Sandbox yanıtları meta’ya "test_mode": true ekler.

Gönderimlerde her zaman bir Idempotency-Key gönderin. Aynı anahtarı ve gövdeyi 24 saat içinde tekrarlarsanız, kopya gönderim yerine özgün yanıt döner; farklı bir gövdeyle tekrarlamak 409 IDEMPOTENCY_KEY_REUSED döndürür.

Diğer kanallar

Her kanalın, o kanala uyan bir gövde biçimiyle /messages öneki altında kendi uç noktası vardır. Tek bir kanal-çokbiçimli (polymorphic) rota yoktur — kanalınıza uyan uç noktayı seçin:

Kanal	Uç nokta	Başvuru
SMS	`POST /messages/sms`	Messaging API
WhatsApp	`POST /messages/whatsapp`	WhatsApp kanalı
RCS	`POST /messages/rcs`	RCS kanalı
Viber	`POST /messages/viber`	Viber kanalı
E-posta	`POST /messages/email`	E-posta kanalı

2. Teslim durumunu izleyin

Kuyruktaki bir mesaj, alıcıya ulaşmadan önce bir durum yaşam döngüsü boyunca ilerler:

queued → sending → sent → delivered   (veya failed / undelivered)

İzlemenin iki yolu vardır: Mesajı id ile sorgulayın:

curl https://api.orbit.devotel.io/api/v1/messages/msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Webhook’lara abone olun (önerilir — sorgulama yok). Her durum geçişinde bir olay ateşlenir ve her biri mesaj id’si ile yeni status’u taşır:

message.sent — operatör tarafından kabul edildi
message.delivered — telefona teslim edildiği onaylandı
message.failed — kesin hata (payload status’u failed, undelivered, expired ve submitted_no_receipt’i ayırt eder; varsa error_code / error_message sağlayıcı nedenini taşır)

Bir webhook uç noktası bir kez kaydedilir, ardından olaylar akar:

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.sent", "message.delivered", "message.failed", "message.received"],
    "secret": "whsec_your_signing_secret"
  }'

Bir teslim olayı şöyle görünür:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-07-20T12:00:00Z",
  "data": {
    "message_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "channel": "sms",
    "status": "delivered",
    "is_terminal": true,
    "timestamp": "2026-07-20T12:00:00Z"
  }
}

Herhangi bir payload’u kabul etmeden önce X-Orbit-Signature başlığını doğrulayın ve olay id’sine göre tekrarları ayıklayın — teslim en az bir kez (at-least-once) yapılır. Doğrulama kod parçası için Webhook güvenliği bölümüne bakın.

3. Gelen mesajları alın

Biri numaranıza yanıt verdiğinde (veya önce ona mesaj attığında), Orbit bir gelen mesaj kaydeder ve — yukarıdaki adımda message.received aboneliğiniz varsa — bunu webhook URL’nize POST eder:

{
  "id": "evt_def456",
  "type": "message.received",
  "created_at": "2026-07-20T12:01:00Z",
  "data": {
    "message_id": "msg_inb_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "STATUS"
  }
}

Gelen mesaj ayrıca sorgulanabilir — direction=inbound filtresiyle aldığınız her şeyi listeleyin:

curl "https://api.orbit.devotel.io/api/v1/messages?direction=inbound&channel=sms" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Gelen yönlendirme, Orbit’te sahibi olduğunuz numaralar için otomatiktir — gönderici numaralarınızın birine yapılan bir yanıt yakalanır ve bir message.received aboneliğiyle webhook’unuza teslim edilir. Numara başına gelen URL kablolamak gerekmez.

4. Gelen bir mesaja yanıt verin

Yanıt vermek, gelen from adresine geri çekilmiş bir başka gönderimdir. to ile from’u değiştirin ve POST /messages/sms’i yeniden çağırın:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Order #1234 is out for delivery, arriving today by 5pm."
  }'

Her iki mesaj da bir konuşma paylaşır; iş parçacığı (thread) oluştuğunda, tam karşılıklı sohbet’i GET /messages üzerindeki conversation_id filtresiyle çekebilirsiniz.

Sık görülen hatalar

Her hata aynı biçimi kullanır — error.code’u (BÜYÜK HARF sabiti) eşleştirin ve meta.request_id’yi loglayın:

Kod	HTTP	Anlamı	Çözüm
`INVALID_API_KEY`	401	Anahtar iptal edilmiş, yanlış ortam veya yazım hatası	Ayarlar → API Anahtarları’nı denetleyin
`INVALID_PHONE_NUMBER`	422	`to` geçerli E.164 değil veya ulaşılabilir değil	Gönderimden önce numarayı doğrulayın
`NOT_SMS_CAPABLE`	422	Gönderici SMS uyumlu değil (ör. 10DLC’siz toll-free)	Numarayı kayıt edin veya değiştirin
`INSUFFICIENT_BALANCE`	402	Cüzdan kanal asgariasının altında	Cüzdanınızı doldurun
`RATE_LIMITED`	429	Çok fazla gönderim	`details.retry_after`’ı (saniye) dikkate alın
`VALIDATION_ERROR`	422	Gövde biçimi yanlış	Her alan için `details.issues`’i okuyun

Tam liste: Hata Kodları.

Sonraki adımlar

Messaging API başvurusu — her mesaj uç noktası ve alan
Mesaj durumu yaşam döngüsü — kanal başına tam durum kümesi
Webhook’lara genel bakış — tekrar denemeler, teslim garantileri ve olay kataloğu
API Entegrasyonu — sandbox, idempotency, paginasyon ve tüm kanallarda SDK’lar
Hız Sınırları — kanal başına sınırlar ve yeniden deneme başlıkları

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Mesaj Gönderme ve Alma

Mesaj Gönderme ve Alma

Ön koşullar

1. Mesaj gönderin

Diğer kanallar

2. Teslim durumunu izleyin

3. Gelen mesajları alın

4. Gelen bir mesaja yanıt verin

Sık görülen hatalar

Sonraki adımlar

​Mesaj Gönderme ve Alma

​Ön koşullar

​1. Mesaj gönderin

​Diğer kanallar

​2. Teslim durumunu izleyin

​3. Gelen mesajları alın

​4. Gelen bir mesaja yanıt verin

​Sık görülen hatalar

​Sonraki adımlar

Mesaj Gönderme ve Alma

Ön koşullar

1. Mesaj gönderin

Diğer kanallar

2. Teslim durumunu izleyin

3. Gelen mesajları alın

4. Gelen bir mesaja yanıt verin

Sık görülen hatalar

Sonraki adımlar