Müşteri iletişiminizi kendi sistemlerinize entegre edin

Hızlı başlangıç

1. Panel › Ayarlar › Geliştirici (API) sayfasından API Anahtarı Üret. Anahtar bir kez gösterilir (msj_live_…).
2. Bağlantıyı doğrulayın:

curl https://all.mesajilet.com/api/v1/me \
  -H "Authorization: Bearer msj_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. İlk mesajınızı gönderin (müşteri size son 24 saatte yazdıysa serbest metin; yazmadıysa şablon):

curl -X POST https://all.mesajilet.com/api/v1/messages/template \
  -H "Authorization: Bearer msj_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-18421-confirm" \
  -d '{
    "channel": "whatsapp",
    "to": "905321234567",
    "name": "siparis_onay",
    "variables": ["Ayşe", "18421", "3 Eylül"]
  }'

$res = Http::withToken('msj_live_…')
    ->withHeaders(['Idempotency-Key' => 'order-18421-confirm'])
    ->post('https://all.mesajilet.com/api/v1/messages/template', [
        'channel'   => 'whatsapp',
        'to'        => '905321234567',
        'name'      => 'siparis_onay',
        'variables' => ['Ayşe', '18421', '3 Eylül'],
    ]);

if (!$res->json('success')) {
    $e = $res->json('error');
    // $e['code'], $e['message'], $e['reason'], $e['fix'], $e['request_id']
}
$messageId = $res->json('data.id');   // msg_…

const res = await fetch('https://all.mesajilet.com/api/v1/messages/template', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer msj_live_…',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-18421-confirm',
  },
  body: JSON.stringify({
    channel: 'whatsapp', to: '905321234567',
    name: 'siparis_onay',
    variables: ['Ayşe', '18421', '3 Eylül'],
  }),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.error.code}: ${body.error.message} — ${body.error.fix}`);
console.log(body.data.id); // msg_…

import requests

r = requests.post("https://all.mesajilet.com/api/v1/messages/template",
    headers={"Authorization": "Bearer msj_live_…", "Idempotency-Key": "order-18421-confirm"},
    json={"channel": "whatsapp", "to": "905321234567", "name": "siparis_onay",
          "variables": ["Ayşe", "18421", "3 Eylül"]})
body = r.json()
if not body["success"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} — {body["error"]["fix"]}')
print(body["data"]["id"])

Yanıt 202 Accepted — mesaj kuyruğa alındı; teslim ilerlemesini webhook ile ya da GET /messages/{id} ile izleyin.

Kimlik doğrulama

Her istekte Authorization: Bearer <anahtar> başlığı. Anahtarlar firma bazlıdır; isteğe bağlı IP kısıtı ve kapsam (scope) ile daraltılabilir. Anahtar sunucuda yalnız hash olarak saklanır — kaybolursa yenisi üretilir.

Kapsamlar

Kanallar

İsteklerde channel alanı kanalı seçer (varsayılan whatsapp). Birden fazla hat/sayfa bağlıysa connection_id ile seçin (GET /channels).

Kurallar

Yanıt zarfı

// Başarı
{ "success": true, "data": { … }, "request_id": "req_01j…" }

// Hata
{
  "success": false,
  "error": {
    "code": "WINDOW_CLOSED",
    "http": 409,
    "message": "Müşteri hizmet penceresi kapalı (24 saat). Serbest mesaj gönderilemez.",
    "reason": "Kanal kuralı: müşterinin son mesajından 24 saat geçtikten sonra yalnız onaylı şablon gönderilebilir. Son müşteri mesajı: 2026-08-21T14:02:11+03:00.",
    "fix": "POST /v1/messages/template ile onaylı bir şablon gönderin; müşteri cevap verince pencere yeniden açılır.",
    "param": "to",
    "docs": "https://all.mesajilet.com/developers#err-WINDOW_CLOSED",
    "request_id": "req_01j…"
  }
}

request_id her yanıtta (başlıkta da X-Request-Id) bulunur; destek talebinde bu kimliği iletin — isteğinizi saniyesine kadar buluruz.

Idempotency

Yazma isteklerine Idempotency-Key başlığı ekleyin (ör. sipariş no + olay). Aynı anahtar + aynı gövde 24 saat içinde tekrar gelirse mesaj yeniden gönderilmez, ilk yanıt aynen döner (Idempotent-Replayed: true). Aynı anahtar farklı gövdeyle gelirse IDEMPOTENCY_CONFLICT.

Hız sınırı

Varsayılan 1800 istek/dakika (anahtar başına; panelden değiştirilebilir) ve saniyelik patlama (burst) sınırı dakikalık ortalamanın 2 katı, en az 10/sn (1800/dk için 60/sn). Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Burst; aşımda 429 RATE_LIMITED + Retry-After. WhatsApp'ın numara başına saniyelik gönderim tavanı ayrıca sunucu tarafında otomatik uygulanır — kampanya trafiği API trafiğinizi yavaşlatmaz (öncelikli kuyruk).

Test modu (sandbox)

Panelden test anahtarı (msj_test_…) üretin. Test anahtarıyla yapılan isteklerde tüm doğrulamalar (alıcı, şablon, değişken, medya) gerçek çalışır; ancak mesaj sağlayıcıya gönderilmez, sohbet kutusuna düşmez ve hizmet penceresi kontrolü atlanır. Yanıt status: "sent" ve test: true döner; tanımlı webhook'a sent → delivered → read olayları "test": true işaretiyle simüle edilir. Yanıt başlığı: X-Mesajilet-Mode: test. Canlıya geçerken yalnız anahtarı değiştirmeniz yeterlidir.

Mesaj durumları

queued → sent → delivered → read · failed (sebep error alanında: sağlayıcı kodu + Türkçe açıklama).

Uçlar

GET /me

Anahtar, hesap, modüller, lisans ve bağlı kanallar. Entegrasyonun ilk sağlık kontrolü için kullanın.

GET /channels

Her kanal için yetenekler (capabilities), pencere süresi ve bağlantılar (connection_id değerleri: wa_15, ig_3, fb_7, web_2).

POST /messages

Serbest (oturum) mesajı. Müşterinin size yazmış olması gerekir (pencere). Alanlar:

// Görsel + açıklama (WhatsApp)
{ "to": "905321234567", "type": "image", "media": { "url": "https://cdn.site.com/u/fatura.jpg" }, "caption": "Faturanız ektedir." }

// Instagram DM'e hızlı yanıt butonları
{ "channel": "instagram", "to": "17841400000000000", "type": "interactive",
  "interactive": { "kind": "button", "text": "Siparişiniz hazır. Teslimat tercihiniz?", "buttons": [ {"id":"kargo","title":"Kargo"}, {"id":"magaza","title":"Mağazadan al"} ] } }

POST /messages/template

Onaylı WhatsApp şablonu. Pencere gerekmez; konuşmayı başlatmanın tek yolu budur. Değişkenler şablonla birebir doğrulanır — eksik/fazla değişken anında açıklayıcı hata döner (Meta'nın belirsiz 131008'ini beklemezsiniz).

GET /messages/template

Aynı gönderimin tek URL'lik hâli. Başlık ya da JSON gövdesi kuramayan çağırıcılar için: e-ticaret panelinin "sipariş durumu değişince şu adresi çağır" alanı, otomasyon araçları, hızlı deneme.

Anahtarı adresin içine koyabilirsiniz — tek parça URL, başlık gerekmez:

https://all.mesajilet.com/api/v1/messages/template/msj_live_…?to=905321234567&name=kargo_cikti

Başlık kurabiliyorsanız tercih edin; o zaman anahtar adreste görünmez:

https://all.mesajilet.com/api/v1/messages/template?to=905321234567&name=kargo_cikti
Authorization: Bearer msj_live_…

GET /messages/{id}

Gönderim yanıtındaki id (msg_…) ile durum, external_id (wamid/mid) ve varsa hata detayı.

GET /templates

Filtreler: status, language, category. Her şablonda parameter_format, variables.names, header.format, dinamik butonlar ve örnek değerler döner — istek gövdenizi buna göre kurun.

POST /media

multipart/form-data, alan adı file. Dönen id 30 gün geçerlidir; aynı dosyayı binlerce alıcıya gönderirken URL yerine id kullanın (hız + Meta 131053 hatası yok). Sınırlar: görsel 5 MB, ses/video 16 MB, belge 100 MB.

curl -X POST https://all.mesajilet.com/api/v1/media -H "Authorization: Bearer msj_live_…" -F "[email protected]"

GET /contacts/{id}/window?channel=whatsapp

window_open, last_inbound_at, closes_at ve can_send.session_message / template. Göndermeden önce hangi yolu kullanacağınıza karar verin.

POST /webhooks/test

Gövde: {"event":"message.received"}. Tanımlı adresinize örnek olay gönderir, sunucunuzun HTTP yanıtını ve süresini döner.

GET /conversations

Sohbet listesi. Süzgeçler: status (open/closed/bot), channel, agent_id, unread=true, phone, from/to. Sayfalama: limit (≤100), cursor, order (desc/asc).

curl "https://all.mesajilet.com/api/v1/conversations?status=open&limit=25"   -H "Authorization: Bearer msj_live_…"

// Yanıt
{ "success": true, "data": {
    "conversations": [ { "phone": "905321234567", "channel": "whatsapp", "status": "open",
      "agent": { "id": 8, "name": "Zehra" }, "unread_count": 2,
      "last_message": { "text": "Kargom nerede?", "direction": "in", "at": "2026-08-29T10:12:00+03:00" } } ],
    "pagination": { "limit": 25, "count": 25, "has_more": true, "next_cursor": "NDIzOTQ0" } } }

GET /conversations/{phone}

Tek sohbetin özeti + kişi bilgisi. Numara 0532…, +90532… ya da 90532… biçiminde verilebilir.

GET /conversations/{phone}/messages

Mesaj geçmişi, en yeniden eskiye. Süzgeç: direction (in/out), limit (≤100). Sayfalama zaman damgasıyla: yanıttaki pagination.before değerini ?before= olarak gönderin.

PATCH /conversations/{phone}

Sohbeti kapatır/açar veya temsilciye atar.

curl -X PATCH https://all.mesajilet.com/api/v1/conversations/905321234567   -H "Authorization: Bearer msj_live_…" -H "Content-Type: application/json"   -d '{"status":"closed"}'

// Temsilciye atama (durum otomatik "open" olur)
{ "agent_id": 8 }

GET /contacts

Kişi listesi. search ad, görünen ad, kullanıcı adı, e-posta ve telefonda arar (telefon yazımı serbest: 0532 123 45 67 da bulur).

POST /contacts  ·  PATCH /contacts/{phone}

Alanlar: phone*, name, email, display_name, username. POST varsa günceller, yoksa oluşturur (upsert) — yeni kayıtta 201 döner.

GET /opt-outs  ·  POST  ·  DELETE /opt-outs/{phone}

Pazarlama iletisi istemeyenler. Bu listedeki numaraya kampanya ve akış mesajı gönderilmez.

GET /blocked-numbers  ·  POST  ·  DELETE /blocked-numbers/{phone}

Engellenen numaralar — bu listedekilere hiçbir mesaj gitmez. Pazarlama çıkışından farkı: opt-out yalnız pazarlamayı durdurur, engel tüm iletişimi keser.

GET /stats

Dönem özeti (varsayılan son 30 gün; from/to ile değiştirilir): gelen/giden mesaj, teslim, okunma, başarısız sayıları ve oranları + sohbet durumu dağılımı.

GET /labels  ·  GET /agents

Etiket ve temsilci tanımları. Temsilci kaydında parola/oturum bilgisi dönmez.

Webhook — olay bildirimi

Panel › Geliştirici › Webhook Tanımla: https adresiniz + abone olacağınız olaylar. Her olay POST ile JSON gövde olarak gelir; 10 saniye içinde 2xx dönün (işlemeyi kuyruğa atın).

// Zarf
{
  "id": "whd_01j…",              // teslimat kimliği — aynı id iki kez gelirse yok sayın (dedupe)
  "event": "message.received",
  "api_version": "v1",
  "created_at": "2026-08-23T10:15:02+03:00",
  "company_id": 12,
  "attempt": 1,
  "data": {
    "message": {
      "id": "msg_in_1724412902123",
      "external_id": "wamid.HBgNOTA1…",
      "channel": "whatsapp",
      "connection_id": "wa_15",
      "from": { "id": "905321234567", "name": "Ayşe Yılmaz" },
      "type": "text",                    // text | image | video | audio | document | location | …
      "text": "Siparişim ne zaman gelir?",
      "media": { "url": "https://…", "mime_type": "image/jpeg" },   // medyalı mesajda
      "button": { "payload": "kargo", "title": "Kargo" },            // buton/liste yanıtında
      "reply_to": "wamid.…",                                         // alıntılı cevapta
      "received_at": "2026-08-23T10:15:01+03:00"
    }
  }
}

// message.status → data.message: { id, external_id, channel, to, status: "delivered", error: null|{code,title,detail,provider_message}, occurred_at }
//   Kapsam: API ve panelden gönderilen mesajlar. Toplu KAMPANYA alıcılarının durumları olay olarak GÖNDERİLMEZ
//   (on binlerce olayla sunucunuzu boğmamak için); kampanya raporu panelde ve kampanya dışa aktarımında yer alır.
// template.status → data.template: { name, language, category, status: "APPROVED"|"REJECTED"|…, rejection_reason }

İmza doğrulama

Her istekte X-Mesajilet-Signature: t=<unix>,v1=<hex>. v1 = HMAC_SHA256(secret, t + "." + hamGövde). Ham gövdeyi (yeniden serileştirmeden) kullanın; t 5 dakikadan eskiyse reddedin (tekrar saldırısı koruması). Diğer başlıklar: X-Mesajilet-Event, X-Mesajilet-Delivery-Id, X-Mesajilet-Attempt.

$secret = getenv('MESAJILET_WEBHOOK_SECRET');
$raw    = file_get_contents('php://input');
$hdr    = $_SERVER['HTTP_X_MESAJILET_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $hdr), $p);           // ['t' => '…', 'v1' => '…']

$expected = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret);
if (!hash_equals($expected, $p['v1'] ?? '') || abs(time() - (int) $p['t']) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($raw, true);
// … kuyruğa at, hemen 200 dön
http_response_code(200);

import crypto from 'node:crypto';
// Express: app.post('/webhook', express.raw({ type: '*/*' }), handler)
function handler(req, res) {
  const sig = Object.fromEntries((req.get('X-Mesajilet-Signature') || '').split(',').map(kv => kv.split('=')));
  const expected = crypto.createHmac('sha256', process.env.MESAJILET_WEBHOOK_SECRET)
    .update(`${sig.t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1 || ''))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);         // önce yanıt, sonra işle
  queue.add(event);
}

import hmac, hashlib, time, json
from flask import request, abort

def webhook():
    raw = request.get_data()
    parts = dict(kv.split("=", 1) for kv in request.headers.get("X-Mesajilet-Signature", "").split(","))
    expected = hmac.new(SECRET.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")) or abs(time.time() - int(parts["t"])) > 300:
        abort(401)
    event = json.loads(raw)
    # kuyruğa at
    return "", 200

Yeniden deneme ve sağlık

2xx dışı yanıt ya da 10 sn zaman aşımı → 5 deneme: 1 dk, 5 dk, 30 dk, 2 sa, 12 sa sonra. Her deneme panelde görünür (HTTP kodu, yanıt gövdesinin ilk 500 karakteri). 50 ardışık başarısızlıkta adres otomatik devre dışı kalır; düzeltip panelden yeniden etkinleştirin. 410 Gone dönerseniz adres anında kapatılır. Olaylar sırasız gelebilir (ör. read, delivered'dan önce) — durumu ileri yönde güncelleyin.

Hata kataloğu

Tüm kodlar aşağıdadır; her yanıt reason (neden) ve fix (ne yapmalı) alanlarını taşır. Kodlar kararlıdır — programatik olarak bunlara göre dallanabilirsiniz.

Mesajlardaki {…} yer tutucuları gerçek değerlerle doldurulur (ör. {hours} → 24). PROVIDER_REJECTED yanıtında meta_error alanı sağlayıcının ham hatasını (kod + mesaj) da taşır.

Sürüm notları

v1 — 31.08.2026: İlk sürüm. Kanallar: WhatsApp, Instagram DM, Messenger, Web. Olaylar: message.received, message.status, template.status. OpenAPI 3.1: /developers/openapi.json.

Geriye dönük uyumluluk: /v1 altında alan kaldırılmaz; yeni alanlar eklenebilir — istemcinizi bilinmeyen alanlara toleranslı yazın.