> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mesaj Gönderme ve Alma

> Orbit API üzerinden ilk SMS veya WhatsApp mesajınızı gönderin ve kod içeren tek bir uçtan uca hızlı başlangıç yolculuğunda gelen yanıtları webhook ile alın.

# 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:**

1. [Mesaj gönderin](#1-mesaj-gönderin)
2. [Teslim durumunu izleyin](#2-teslim-durumunu-izleyin)
3. [Gelen mesajları alın](#3-gelen-mesajları-alın)
4. [Gelen bir mesaja yanıt verin](#4-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](/api-reference/numbers) 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](#3-gelen-mesajları-alın) 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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

### 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](/api-reference/endpoints/messaging) |
| WhatsApp | `POST /messages/whatsapp` | [WhatsApp kanalı](/channels/whatsapp)               |
| RCS      | `POST /messages/rcs`      | [RCS kanalı](/channels/rcs)                         |
| Viber    | `POST /messages/viber`    | [Viber kanalı](/channels/viber)                     |
| E-posta  | `POST /messages/email`    | [E-posta kanalı](/channels/email)                   |

## 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**:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/webhooks/security) 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:

```json theme={null}
{
  "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:

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

<Note>
  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.
</Note>

## 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:

```bash theme={null}
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ı](/reference/error-codes).

## Sonraki adımlar

* [Messaging API başvurusu](/api-reference/endpoints/messaging) — her mesaj uç noktası ve alan
* [Mesaj durumu yaşam döngüsü](/api-reference/messages-status-lifecycle) — kanal başına tam durum kümesi
* [Webhook'lara genel bakış](/webhooks/overview) — tekrar denemeler, teslim garantileri ve olay kataloğu
* [API Entegrasyonu](/guides/api-integration) — sandbox, idempotency, paginasyon ve tüm kanallarda SDK'lar
* [Hız Sınırları](/guides/rate-limits) — kanal başına sınırlar ve yeniden deneme başlıkları