Apsilo Genel API

Tek bir REST API ile WhatsApp, Instagram, Messenger, X, TikTok ve e-posta üzerinden mesaj gönderin; kişileri, şablonları, kampanyaları ve sosyal medya gönderilerini yönetin; olayları webhook ile dinleyin.

API anahtarı oluştur İlk mesajı gönder Olayları dinle

Temel adres ve sürüm

Tüm uç noktalar https://app.apsilo.com/api/public/v1 altındadır. Sürüm yoldadır; kırıcı değişiklikler yeni sürümle yayınlanır, mevcut sürüm geriye dönük uyumlu kalır: yeni alan eklenebilir, var olan alan kaldırılmaz.


# Taban adres
https://app.apsilo.com/api/public/v1
 
# OpenAPI 3.1 belgesi (Postman/Insomnia'ya aktarın)
https://app.apsilo.com/api/public/v1/openapi.json

Yanıtlar her zaman zarflıdır — tekil kaynak { "data": … }, liste { "data": [...], "nextCursor": … }. Ayrıntı için İstek kuralları.

İlk istek

Anahtarınızı Apsilo panelinde Ayarlar → API ve Webhook’lar ekranından oluşturun; anahtar yalnızca bir kez gösterilir.

curl


curl -X POST https://app.apsilo.com/api/public/v1/messages \
  -H "Authorization: Bearer apsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-4821-kargo" \
  -d '{
    "channel": "whatsapp",
    "to": { "phone": "+905551112233" },
    "type": "template",
    "template": {
      "name": "siparis_kargoda",
      "language": "tr",
      "params": { "body.0": "Ayşe", "body.1": "TR123456789" }
    }
  }'

Node.js


const res = await fetch("https://app.apsilo.com/api/public/v1/messages", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.APSILO_API_KEY}`,
    "content-type": "application/json",
    "idempotency-key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    channel: "whatsapp",
    to: { phone: "+905551112233" },
    type: "text",
    text: "Merhaba! Siparişiniz hazırlanıyor.",
  }),
});
 
const { data, error } = await res.json();
if (error) throw new Error(`${error.code}: ${error.message}`);
console.log(data.id, data.status); // queued → accepted → sent → delivered

PHP


$ch = curl_init("https://app.apsilo.com/api/public/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("APSILO_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: " . bin2hex(random_bytes(8)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "channel" => "whatsapp",
        "to" => ["phone" => "+905551112233"],
        "type" => "text",
        "text" => "Merhaba! Siparişiniz hazırlanıyor.",
    ]),
]);
$body = json_decode(curl_exec($ch), true);

Yanıt


HTTP/1.1 202 Accepted
X-Request-Id: 01J9Z5K2F3R7QW8N
 
{
  "data": {
    "id": "3c9a7f42-6c7d-4a5e-9d11-0c2f4b8a77e1",
    "status": "queued",
    "channel": "whatsapp",
    "conversationId": "b71e…",
    "contactId": "4d20…"
  }
}

Alıcı bir nesnedir: phone, email, contactId, igsid, psid, xUserId veya tiktokUserId alanlarından en az biri yeterlidir. Telefon veya e-posta ile verilen alıcı kayıtlı değilse otomatik oluşturulur (createContact: false ile kapatılır); Instagram (igsid), Messenger (psid), X ve TikTok alıcıları önce işletmeye yazmış olmalıdır.

Uç nokta 202 döner: mesaj kuyruğa alınır. Teslim durumu GET /messages/{id} ile veya webhook olaylarıyla izlenir.

Serbest metin yalnızca mesajlaşma penceresi açıkken gönderilebilir. Pencere kapalıysa WhatsApp’ta onaylı şablon kullanın; API bu durumda MESSAGING_WINDOW_CLOSED döner.

Kanal kuralları

Mesaj gönderimi tek uç noktadan yapılır, fakat her kanalın kendi kuralları vardır. API bu kuralları sizin yerinize uygular ve ihlalde açık hata döner.

Kanal	Pencere	Pencere dışında	Notlar
WhatsApp	Son gelen mesajdan 24 saat	Yalnızca onaylı şablon	Şablonlar panelden oluşturulur, Meta onayından geçer
Instagram	Son gelen mesajdan 24 saat	Gönderilemez	Temsilci yanıtı insan etiketiyle 7 güne kadar uzayabilir
Messenger	Son gelen mesajdan 24 saat	Gönderilemez	Alıcı `to.psid`; Instagram ile aynı pencere ve 7 günlük temsilci yanıtı kuralı
X (DM)	Pencere yok	—	Yalnızca daha önce yazışılmış kişilere; günlük DM sınırı vardır
TikTok	Son gelen mesajdan 48 saat	Gönderilemez	Konuşmayı her zaman kullanıcı başlatır
E-posta	Pencere yok	—	Konu zinciri otomatik eşlenir; kampanyalarda abonelikten çıkma bağlantısı eklenir

Metin sınırı kanala göre değişir: WhatsApp 4096, Instagram 1000, Messenger 2000, X 10.000, TikTok 6000 karakter. Şablon gönderimi (type: "template") WhatsApp, Instagram, Messenger, X ve e-postada kullanılır; Messenger şablonları Instagram’daki gibi metin, medya ve kartlı türlerdedir ve onay gerektirmez, fakat pencere kuralını aşmaz.

Şikayetvar

Şikayetvar şikayetleri sohbet listelerinde görünür: GET /conversations yanıtında channel: "sikayetvar", kind: "complaint" (şikayet başına bir sohbet); aynı değerlerle filtreleyebilirsiniz. Genel API ile şikayete yanıt verilemez — POST /messages bu kanalı kabul etmez; yanıtlar Apsilo panelinden yazılır.

Apsilo AI analizi

Apsilo AI gelen mesajları, yorumları ve şikayetleri otomatik değerlendirir. Sonuç, mesaj nesnesinin analysis alanında döner (GET /messages/{id} ve mesaj listeleri); sohbet nesnesindeki analysis ise sohbetin son analiz edilen gelen mesajının özetidir.


{
  "id": "3c9a7f42-6c7d-4a5e-9d11-0c2f4b8a77e1",
  "direction": "in",
  "analysis": {
    "kind": "inbound",
    "sentiment": "negative",
    "sentimentConfidence": 0.94,
    "intent": "complaint",
    "intentConfidence": 0.88,
    "urgency": 4,
    "flags": ["churn_risk"],
    "categories": { "kargo_gecikmesi": "yes" },
    "autoHidden": false,
    "analyzedAt": "2026-09-17T09:15:02.000Z"
  }
}

Alan	Değerler
`sentiment`	`positive`, `neutral`, `negative` — emin olunamadıysa `null`
`intent`	`complaint`, `request`, `question`, `suggestion`, `thanks`, `purchase`, `cancellation`, `other` — emin olunamadıysa `null`
`urgency`	1 (acil değil) – 5 (çok acil)
`flags`	`profanity`, `spam`, `churn_risk`, `sales_opportunity`
`categories`	Panelde tanımladığınız kategoriler: anahtar → `yes` / `no` ya da seçenek anahtarı

Temsilci yanıtlarında kind: "reply" olur ve yalnızca quality (kibarlık 1–5, yanıtın müşterinin mesajını karşılama olasılığı 0–1) döner.

Analiz, mesaj kaydedildikten kısa süre sonra arka planda üretilir. Hazır olana kadar — ve analiz edilmeyen mesaj türlerinde ya da Apsilo AI firmanızda kapalıyken — analysis alanı null döner. Yoklamak yerine message.analyzed olayına abone olun.

Ücretlendirme

API gönderimleri firmanın cüzdanından düşer: şablon mesajları fiyat tablosundaki mesaj türü fiyatıyla, 24 saat penceresi içindeki serbest metin/medya mesajları ücretsizdir. Apsilo AI analizi için ücret alınmaz. Mesaj türü yanıttaki priceType alanında döner; Messenger şablonlarında msgr_text, msgr_media veya msgr_generic olur. Sağlayıcı isteği reddederse veya mesaj sonradan failed olursa tutar otomatik iade edilir; bakiye yetersizse istek INSUFFICIENT_BALANCE ile reddedilir.

Lisans ve yetki

Anahtarın yapabildikleri kapsamlar ∩ firmanın lisansı kesişimidir: lisansta kapalı bir kanal veya özellik, kapsam verilmiş olsa bile kullanılamaz ve FEATURE_NOT_LICENSED döner. Genel API için lisansta feature.api açık olmalıdır.

Panelde anahtar ekranı: app.apsilo.com/settings/integrations