Mesaj gönder


POST https://app.apsilo.com/api/public/v1/messages

Mesajı kuyruğa alır ve 202 döner; teslim durumu message.sent / message.delivered / message.read / message.failed webhook olaylarıyla veya GET /messages/{id} ile izlenir.

WhatsApp: kişinin son mesajından 24 saat sonra yalnızca onaylı şablon gönderilebilir (422 MESSAGING_WINDOW_CLOSED).
Instagram: son gelen DM’den sonraki pencere içinde; şablonlar da pencereye tabidir.
X: kişiyle önceden DM yazışması gerekir; hesap başına günlük DM sınırı vardır.
TikTok: konuşmayı kullanıcı başlatır; son gelen DM’den 48 saat içinde yanıt verilebilir. Ücretsizdir.
Telegram: kişi önce bota yazmış olmalıdır (bot konuşma başlatamaz); mesajlaşma penceresi yoktur. Serbest metin/medya ücretsizdir, şablonlar tg_text / tg_media fiyatından ücretlendirilir. Kişi botu engellediyse message.failed (USER_BLOCKED) döner ve kişinin Telegram izni kaldırılır.
E-posta: pencere yoktur; type=email veya e-posta şablonu.

Şablon mesajları kanalın mesaj türü fiyatından ücretlendirilir; X DM x_dm_campaign, e-posta email_campaign; pencere içindeki WhatsApp/Instagram serbest metin/medya ücretsizdir. Bakiye yetersizse 402 INSUFFICIENT_BALANCE.

Gerekli kapsam: messages:send

Parametreler

Parametre	Yer	Tip	Gereklilik	Açıklama
`Idempotency-Key`	başlık	string	isteğe bağlı	İsteğe özgü benzersiz değer (1–255 yazdırılabilir ASCII; ör. UUID). Aynı anahtar + aynı yol ve gövde 24 saat içinde kaydedilmiş yanıtı döner (`Idempotent-Replayed: true`); farklı gövde veya işlenmekte olan istek `409 IDEMPOTENCY_CONFLICT`. Hata yanıtları saklanmaz.
`X-Request-Id`	başlık	string	isteğe bağlı	İsteğe bağlı istek kimliğiniz (8–100 karakter: harf, rakam, `._:-`); yanıtta aynen döner ve kayıtlara işlenir.

İstek gövdesi

Alan	Tip	Gereklilik	Açıklama
`channel`	`whatsapp` · `instagram` · `messenger` · `x` · `tiktok` · `telegram` · `email`	zorunlu	Gönderim kanalı
`channelAccountId`	string (uuid)	isteğe bağlı	Gönderici hesap (`GET /channels`). E-postada firmada birden fazla hesap varsa zorunlu; diğer kanallarda yalnızca varsayılan hesap.
`to`	object	zorunlu	Alıcı — alanlardan en az biri. `contactId` verilirse kişinin o kanaldaki kimliği kullanılır.
`type`	`text` · `media` · `template` · `email`	zorunlu	`text` / `media` pencere içi serbest mesaj; `template` onaylı şablon; `email` yalnızca `channel=email`
`text`	string	isteğe bağlı	`type=text` metni (WhatsApp 4096, Instagram 1000, Messenger 2000, X 10.000, TikTok 6000, Telegram 4096 karakter)
`media`	object	isteğe bağlı	`type=media` içeriği — `mediaId` (`POST /media`) veya herkese açık `url` (yalnızca biri)
`template`	object	isteğe bağlı	`type=template` içeriği — `templateId` veya `name` (+ aynı adlı birden fazla dilde şablon varsa `language`)
`email`	object	isteğe bağlı	`type=email` içeriği — `html` veya `text` gerekli
`createContact`	boolean	isteğe bağlı	Alıcı kişi bulunamazsa telefon (WhatsApp) veya e-posta ile kişi oluştur Varsayılan: `true`.
`metadata`	object	isteğe bağlı	Kendi anahtar/değerleriniz (≤20 anahtar, anahtar ≤40, değer ≤500 karakter); mesajda saklanır, `GET /messages/{id}` ve webhook olaylarında döner


{
  "channel": "whatsapp",
  "to": {
    "phone": "+905321234567"
  },
  "type": "template",
  "template": {
    "name": "siparis_kargoda",
    "language": "tr",
    "params": {
      "body.0": "Ayşe",
      "body.1": "SP-2026-10482",
      "button.0.0": "SP-2026-10482"
    }
  },
  "metadata": {
    "orderId": "SP-2026-10482"
  }
}

Yanıtlar

Durum	Açıklama
`202`	Mesaj kuyruğa alındı
`401`	Kimlik doğrulanamadı. Olası kodlar: `API_KEY_INVALID`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`.
`402`	Bakiye yetersiz. Olası kodlar: `INSUFFICIENT_BALANCE`.
`403`	Erişim reddedildi. Olası kodlar: `FEATURE_NOT_LICENSED`, `API_SCOPE_MISSING`, `IP_NOT_ALLOWED`, `LICENSE_EXPIRED`, `LICENSE_NOT_FOUND`, `FORBIDDEN`.
`404`	Bulunamadı. Olası kodlar: `NOT_FOUND`.
`409`	Çakışma. Olası kodlar: `CONFLICT`, `IDEMPOTENCY_CONFLICT`, `MEDIA_IN_USE`, `SOCIAL_APPROVAL_REQUIRED`, `SOCIAL_POST_NOT_EDITABLE`.
`422`	İşlenemeyen istek. Olası kodlar: `VALIDATION_FAILED`, `MESSAGING_WINDOW_CLOSED`, `CHANNEL_ACCOUNT_MISSING`, `CONTACT_BLOCKED`, `STORAGE_LIMIT_REACHED`, `SOCIAL_POST_INVALID`, `SOCIAL_PLATFORM_UNAVAILABLE`.
`429`	Hız sınırı aşıldı. Olası kodlar: `RATE_LIMITED`.
`500`	Sunucu hatası. Olası kodlar: `INTERNAL`.
`502`	Sağlayıcı hatası. Olası kodlar: `PROVIDER_ERROR`.

Örnek yanıt (202)


{
  "data": {
    "id": "0b9e4c1a-6f2d-4a7b-9c3e-000000000050",
    "status": "queued",
    "conversationId": "0b9e4c1a-6f2d-4a7b-9c3e-000000000060",
    "contactId": "0b9e4c1a-6f2d-4a7b-9c3e-000000000021",
    "channel": "whatsapp",
    "priceType": "wa_template_text",
    "unitPrice": "0.045000",
    "charged": true,
    "metadata": {
      "orderId": "SP-2026-10482"
    }
  }
}