MMF Relay API dokümantasyonu

Nasıl başlanır

Dört adım. Üçüncü adıma kadar hiçbir müşteriye mesaj gitmez; kurulumu canlı veriyle değil /v1/ping ile doğrularsınız.

1. Anahtarı alın

   Çalışma alanının panelinde /ayarlar/api ekranından anahtar üretilir; ekran tenant.settings.manageyetkisi ister. Anahtar üretilirken hangi kapsamları taşıyacağı seçilir. Sır yalnız bir kez gösterilir — kasada şifreli durduğu için geri gösterilemez, kaybedilirse yalnız yenisi üretilir.

2. İmzalı ilk isteği atın

   GET https://api.mmfrelay.com/v1/ping. Kapsam istemez, yalnız geçerli imza ister; yanlış imza API-1003, penceresi kaçmış zaman damgası API-1004 verir.

3. Kapsamları yanıttan doğrulayın

   /v1/ping yanıtı tenant_id, partner ve anahtarın gerçekten taşıdığı scopes listesini döndürür. Eksik bir kapsam burada görünür; ilk gerçek istekte API-1005 olarak değil.

4. Gerçek işi yapın

   Okuma uçlarıyla başlayın (/v1/templates, /v1/contacts), sonra gönderime geçin. Şablon mesajı POST /v1/messages, serbest metin POST /v1/conversations/{id}/messages.

Taban adres ve kimlik doğrulama

Taban adres https://api.mmfrelay.com. Her istek üç başlık taşır: anahtar kimliği satırı seçer, imza isteğin doğruluğunu kanıtlar. Çalışma alanı isteğe hiç girmez — anahtarın satırından okunur, dolayısıyla gövdedeki hiçbir değer hangi çalışma alanına yazılacağını seçemez.

İmza tabanı

zaman_damgası + "." + METOT + "." + yol + "." + ham_gövde

imza = "sha256=" + HMAC_SHA256(taban, gizli_anahtar). Metot büyük harftir. Yol sorgu dizesi olmadan yazılır ve sunucuda yeniden kurulur (sondaki eğik çizgi atılır); başlıktan gelen bir değere güvenilmez. Gövdesiz isteklerde son parça boş dizedir — taban zaten metot ve yolla ayrıştığı için bu güvenlidir: bir ucun imzası başka bir uçta, başka bir metotla veya başka bir gövdeyle yeniden oynatılamaz.

taban   = "1756400000.GET./v1/usage."
imza    = "sha256=" + HMAC_SHA256(taban, gizli_anahtar)
istek   = GET https://api.mmfrelay.com/v1/usage

Zaman penceresi

X-MMF-Timestamp Unix saniyesidir ve tolerans ±300 saniyedir. Pencere imzadan önce sınanır: eski bir isteğin imzası doğru olsa bile penceresi kapanmışsa tekrar oynatılamaz. Sunucunuzun saati kayıyorsa istekler API-1004 alır — NTP ile senkron tutun.

Gövde sınırı

Sözleşme sınırı 256 KiB; aşan istek API-2001 alır. Tek istisna medya ucudur (POST /v1/conversations/{id}/media): base64 dosya taşıdığı için tavanı 24 MiB'dır. Base64 yaklaşık %33 şişirdiği için pratik dosya tavanı ~16 MB olur.

Çalışan örnekler

İkisi de aynı iki kuralı gösterir: gövde bir kez üretilir ve yola sorgu dizesi girmez.

<?php
// Anahtar panelden alınır: /ayarlar/api → "Yeni anahtar". Sır YALNIZ bir kez
// gösterilir; kaybedilirse geri gösterilemez, yalnız yenisi üretilir.
$keyId  = getenv('MMF_KEY_ID');   // X-MMF-Key başlığına gider
$secret = getenv('MMF_SECRET');   // yalnız imza üretiminde kullanılır

function mmfRequest(string $method, string $path, ?array $payload = null): array
{
    global $keyId, $secret;

    // Gövde BİR KEZ üretilir: imzalanan dize ile gönderilen baytlar aynı olmalı.
    // Gövdesiz isteklerde (GET, DELETE, /v1/templates/sync) taban boş dizedir.
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_UNICODE);

    $timestamp = (string) time();
    // taban = zaman + "." + METOT + "." + yol + "." + ham_gövde
    // Yola sorgu dizesi GİRMEZ: "/v1/contacts?limit=100" değil "/v1/contacts".
    $base      = $timestamp . '.' . $method . '.' . $path . '.' . $body;
    $signature = 'sha256=' . hash_hmac('sha256', $base, $secret);

    $ch = curl_init('https://api.mmfrelay.com' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-MMF-Key: ' . $keyId,
            'X-MMF-Timestamp: ' . $timestamp,
            'X-MMF-Signature: ' . $signature,
        ],
    ]);
    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return ['status' => $status, 'body' => json_decode($raw, true)];
}

// 1) Kurulum doğrulaması: kapsam eksiği üretime çıkmadan burada görünür.
$ping = mmfRequest('GET', '/v1/ping');
// => ["ok" => true, "tenant_id" => "...", "partner" => "...", "scopes" => [...]]

// 2) Şablon mesajı. Yanıt 202 ve status "queued": mesaj kuyruğa alındı,
//    Meta'ya isteği kuyruk tüketicisi atar. 200 demek yanlış olurdu.
$sent = mmfRequest('POST', '/v1/messages', [
    'phone'             => '+905321234567',
    'template_name'     => 'fatura_bildirimi',
    'template_language' => 'tr',
    'variables'         => [
        ['key' => 'musteri_adi', 'target' => 'body', 'value' => 'Ayşe Yılmaz'],
    ],
]);

if ($sent['status'] !== 202) {
    // Hata gövdesi her zaman { "error": { "code": "API-xxxx", "message": "..." } }
    error_log('MMF Relay: ' . $sent['body']['error']['code']);
}

import { createHmac } from "node:crypto";

const BASE_URL = "https://api.mmfrelay.com";
const KEY_ID = process.env.MMF_KEY_ID;
const SECRET = process.env.MMF_SECRET;

/**
 * @param {"GET"|"POST"|"PUT"|"PATCH"|"DELETE"} method
 * @param {string} path  Sorgu dizesi HARİÇ yol, ör. "/v1/contacts"
 * @param {object} [payload]
 * @param {Record<string,string>} [query]
 */
async function mmfRequest(method, path, payload, query) {
  // Gövde bir kez üretilir; imzalanan dize ile gönderilen baytlar aynı olmalı.
  const body = payload === undefined ? "" : JSON.stringify(payload);
  const timestamp = Math.floor(Date.now() / 1000).toString();

  // taban = zaman + "." + METOT + "." + yol + "." + ham_gövde
  // Sorgu dizesi tabana GİRMEZ; sunucu yolu kendisi yeniden kurar.
  const signature = createHmac("sha256", SECRET)
    .update(`${timestamp}.${method}.${path}.${body}`)
    .digest("hex");

  const search = query ? `?${new URLSearchParams(query).toString()}` : "";
  const response = await fetch(`${BASE_URL}${path}${search}`, {
    method,
    headers: {
      "Content-Type": "application/json",
      "X-MMF-Key": KEY_ID,
      "X-MMF-Timestamp": timestamp,
      "X-MMF-Signature": `sha256=${signature}`,
    },
    body: body === "" ? undefined : body,
  });

  return { status: response.status, body: await response.json() };
}

// 1) Kurulum doğrulaması.
const ping = await mmfRequest("GET", "/v1/ping");
console.log(ping.body.scopes); // anahtarın gerçekten taşıdığı kapsamlar

// 2) Sorgu dizeli okuma: imza yalnız "/v1/contacts" üzerinden hesaplanır.
//    ?phone= tam eşleşmedir ve normalleştirme sunucudadır: +90…, 90…, 0…
//    ve çıplak biçim aynı kişiyi bulur; bozuk numara API-2003 döner.
const page = await mmfRequest("GET", "/v1/contacts", undefined, {
  phone: "05321234567",
  tag: "vip",
});
// { data: [...], next_cursor: "..." | null }

// 3) Şablon mesajı. Aynı işi tekrar denerken Idempotency-Key kullanın:
//    aynı anahtar + aynı gövde saklanan yanıtı döndürür, ikinci mesaj çıkmaz.
const sent = await mmfRequest("POST", "/v1/messages", {
  contact_id: page.body.data[0]?.contact_id,
  template_name: "fatura_bildirimi",
  template_language: "tr",
  variables: [{ key: "musteri_adi", target: "body", value: "Ayşe Yılmaz" }],
});

if (sent.status !== 202) {
  console.error(sent.body.error.code, sent.body.error.message);
}

Yetki kapsamları

API anahtarının kullanıcısı yoktur, dolayısıyla rolü de yoktur; yetkisi bir kapsam listesidir. Kapsam uç bazındadır, iş ortağı bazında değil: bir gün yalnız okuma yetkisi vermek istediğinizde gönderim yetkisini de vermek zorunda kalmayasınız diye. messages:send bilerek contacts:write'tan ayrıdır — kişi güncellemek ile müşteriye mesaj yollamak aynı riske sahip değildir.

Anahtar bir ucun istediği kapsamı taşımıyorsa istek API-1005 ile döner ve uç hiç çalışmaz.

Uçlar (44)

Yol eşleşmesi metottan bağımsız kaydedilir: yanlış metotla çağrılan bir uç 404 değil 405 alır ve yanıt Allow başlığı taşır. Böyle bir uç yoksa API-2004 döner.

Sayfalama, idempotency ve hız sınırı

Sayfalama — imleç, sayfa numarası değil

Sayfa numarası yoktur. Liste okunurken yeni kayıt yazılır ve sayfa numarası kayar: 2. sayfayı isteyen çağıran, araya giren bir kayıt yüzünden bir satırı iki kez veya hiç görmez. Bütün liste uçları aynı zarfı döndürür.

{
  "data": [ /* ... */ ],
  "next_cursor": "eyJrIjoiY29udGFjdHMiLCJ2IjoiMjAy…" | null
}

• ?limit= varsayılan 50, tavan 200. Geçersiz değer hata değil varsayılandır ve tavan sessizce uygulanır: 10.000 satır isteyen bir çağıranı reddetmek yerine 200 vermek, isteğin yine de işine yaraması demektir.
• ?cursor= bir önceki yanıtın next_cursor değeridir. İmleç base64url ve opaktır; ayrıştırmayın.
• İmleç liste türünü de taşır: bir listenin imleciyle başka bir listeyi sayfalamak API-2007 verir. Sessizce yanlış sonuç dönmez.
• next_cursor null ise liste bitmiştir.

Idempotency-Key

Yalnız POST /v1/messages destekler. Başlık 1–200 yazdırılabilir ASCII karakterdir. Aynı işi yeniden denerken kullanın: ağ zaman aşımından sonra atılan ikinci istek sessizce ikinci bir mesaj üretmesin diye.

Yalnız mesaj gerçekten üretilen sonuç (202) saklanır. Sözleşmenin tek amacı çift mesaj göndermemektir; hata yanıtında ortada gönderilmiş bir mesaj yoktur, dolayısıyla saklanacak bir şey de yoktur. API-6001 (rıza yok) veya API-4002 (kota dolu) alan bir istek anahtarı kilitlemez: rızayı yazdıktan ya da kota yükseltildikten sonra aynı anahtarla yeniden deneme mesajı gönderir. Kayıt 24 saat yaşar.

Hız sınırı

Sınır anahtar başınadır ve token bucket'tır.

Her yanıt X-RateLimit-Remaining ve X-RateLimit-Reset (epoch saniye) taşır. Sınır aşıldığında API-4001 döner ve yanıt ayrıca Retry-After taşır; o değer hiçbir zaman sıfır olamaz.

Sıra kimlik → hız sınırı → kapsam'dır: imzasız bir sel jeton yakamaz, kapsamı eksik bir anahtar da sınırdan muaf değildir. Bu sınır bizim sınırımızdır; Meta'nın numara başına tavanı (Cloud API 80 mesaj/sn, coexistence 20 mesaj/sn ve sabit, aynı kişiye ~0,17 mesaj/sn) ayrı bir şeydir ve gönderim yolunda ayrıca uygulanır.

Rıza asimetrisi

Gerekçe: geri alma mutlaktır. Bir kişi «artık yazmayın» dedikten sonra o kaydı tersine çevirmek yeni ve daha güçlü bir kanıt gerektirir — kişinin kendisinin yeniden rıza vermesi. İşletmenin panelden bilinçli bir işlemi bu kanıtı taşıyabilir: ekranda oturan bir kullanıcı, adı denetim kaydında duran biri, kanıt alanını dolduran biri. Bir entegrasyon anahtarının rutin senkron yazması taşıyamaz: bir ERP kaydı «bu kişi tekrar rıza verdi» demez, «bu kişiyle ticari ilişkim var» der ve ikisi aynı şey değildir.

İkinci fark: API'den gelen her granted kanıt (evidence) taşımak zorundadır, kanal ne olursa olsun. Panel yalnız devralınan kanallarda ister. Kanıtsız rıza Meta denetiminde savunulamaz ve bir makinenin ürettiği rıza kaydının dayanağını sonradan bulmak imkânsızdır.

withdrawn yazmak her zaman serbesttir ve kanıt istemez: çıkış talebini evraka bağlamak, geri almayı geciktirmek olurdu.

Hizmet penceresi

WhatsApp'ta serbest metin yalnız müşterinin son mesajından itibaren 24 saat içinde gönderilebilir. MMF Relay'de bu iki gönderim yolunu birbirinden ayırır:

Pencere kapısı rıza kategorisine bakmaz: «DUR» yazan bir müşterinin kendi sorusuna yanıt engellenmez, ama tanıtım bu kanaldan meşrulaşmaz. Konuşmanın penceresi açık mı, GET /v1/conversations yanıtından okunur.

Gönderim uçlarının hepsi 202 ve status: "queued" döndürür. 200 demek mesajın Meta'ya teslim edildiğini söylemek olurdu ve o an henüz doğru değildir: Meta'ya isteği yalnız kuyruk tüketicisi atar. Teslimat durumu GET /v1/conversations/{id}/messages üzerinden okunur.

Teslimat bildirimi (giden webhook)

Mesajın durumu değiştiğinde biz size imzalı bir POST göndeririz; durumu sormanız gerekmez. Uç çalışma alanı başına bir tanedir ve /ayarlar/api ekranından kurulur. Kaydedildiği anda bir imza anahtarı üretilir ve yalnız o an gösterilir.

Sözleşme, sizin bize gönderdiğiniz olay ucunun aynasıdır: aynı başlık adları, aynı imza tabanı. Gönderirken yazdığınız imza kodunu alırken doğrulama için yeniden kullanabilirsiniz.

imza_tabanı = X-MMF-Timestamp + "." + ham_gövde

{
  "event_id": "evt_9f2c…",        // yeniden denemede AYNI kalır
  "event": "message.status",
  "occurred_at": "2026-09-15T08:14:02.000Z",
  "data": {
    "message_id": "0f1a…",        // POST /v1/messages yanıtındaki kimlik
    "conversation_id": "7c33…",
    "contact_id": "b81e…",
    "status": "delivered",        // sent | delivered | read | failed
    "error_code": null,           // yalnız failed: MSG-xxxx
    "meta_error_code": null,      // yalnız failed: Meta'nın sayısal kodu
    "meta_error_subcode": null
  }
}

• Tekilleştirmeyi event_id ile yapın. Kimlik (çalışma alanı, mesaj, durum) üçlüsünden türetilir: aynı durum ikinci kez üretilse bile kimlik aynı çıkar. X-MMF-Delivery ile karıştırmayın — o her denemede değişir.
• Hızlı ve 2xx dönün. Yanıtın gövdesi okunmaz. 408, 429 ve 5xx yeniden denenir (1 → 2 → 4 → 8 dakika, en fazla 5 deneme); diğer 4xx terminaldir. İstek 10 saniyede zaman aşımına uğrar.
• Sıra garantisi yoktur. Meta'nın bildirimleri sırasız gelir (delivered, sent'ten önce ulaşabilir) ve biz de aynı sırayla iletiriz. Durumu yalnız ileri yönde işleyin.
• wa_message_id gönderilmez. Meta'nın kimliği base64 gövdesinde alıcının telefon numarasını taşıyor ve günlüğünüze düşerdi. Eşleştirme message_id ile yapılır — gönderirken zaten size döndü.
• accepted ve played bildirilmez. Birincisi bizim iç durumumuzdur (Meta isteği kabul etti) ve Meta'nın sent bildirimi saniyeler içinde gelir; ikincisi kapsam dışıdır.
• Art arda 20 başarısız teslimatta uç kapatılır ve panelde gerekçesiyle görünür. Adres yeniden kaydedilince açılır ve sayaç sıfırlanır.

Hata kodları

Kod kararlıdır ve değişmez; metin değişebilir. Günlüğünüzde koda dallanın, metne değil. Her hata yanıtı aynı zarfı taşır:

{
  "error": {
    "code": "API-6002",
    "message": "Kişi bu kategoride rızasını geri almış; mesaj gönderilmedi."
  }
}

Biçim hatalarında mesajın sonuna hangi alanın bozuk olduğu eklenir ( (alan: template_language) ). Şablon yazma hataları ayrıca bir support_id taşır; o kimlikle bize yazarsanız sunucu günlüğündeki Graph kaydını buluruz.

9xxx · Beklenmeyen hata

API-9001 (HTTP 500) bizim tarafımızdaki beklenmeyen bir hatadır. İç ayrıntı dışarı sızmaz ama yanıt bir request_id taşır ve aynı kimlik sunucu günlüğüne yazılır: destek kaydında o kimliği verin. Bu kod yeniden denenebilir.

Bilerek yapılmayanlar

Aşağıdakiler eksiklik değil karardır. Gerekçesiyle birlikte yazıyoruz ki entegratör olmayan bir şeyi aramakla vakit kaybetmesin.

• Meta'nın uçları proxy'lenmedi. POST /v1/messages kendi gönderim yolunu kurmaz; ortak servisi çağırır. Bir gönderim noktası ortak yoldan çıkarsa dört şeyi birden kaybeder: kota kapısı çalışmaz, mesaj gelen kutusunda görünmez, ücretlendirme kaydı yazılmaz ve teslimat bildirimi eşleşecek bir kimlik bulamaz.
• Numara bağlama sunucudan sunucuya yapılamaz. Meta'nın Embedded Signup akışı bir tarayıcı akışıdır: kurumun kendi Meta hesabıyla giriş yapması ve numarayı doğrulaması gerekir. Böyle bir onay API'den vekâleten verilemez. Çözüm tek kullanımlık bağlama bağlantısıdır (POST /v1/tenants yanıtındaki connect_link, 7 gün geçerli).
• Şablon ve kampanya medyası API'den yüklenemez. Medya tanıtıcısı yalnız panelin yeniden başlatılabilir yükleme akışından alınabilir; kampanya medyası ise kampanyanın kendisine aittir (tek dosya, tek Meta kimliği) ve Meta kimliği 30 günde ölür. Medyalı kampanya panelden kurulur, başlatması API'den yapılabilir. Karusel şablonlar da kapsam dışıdır.
• «Olay → şablon adı» kısayolu yok. API'den kural kurmak, panelin kurduğu her şeyi söylemektir: tetikleyici, koşullar, bekleme süresi ve bütün yuvaları kapatan bağlamalar. Şablon adı tek başına mesaj üretmez ve kuralın koşullarını düşürerek baypas etmenin yolu yoktur.
• Tepki kaldırma ucu yok. Meta gönderim tarafı için bir «kaldır» gövdesi dokümante etmedi. Boş emoji sessizce yutulmaz, API-2003 alır.
• Yazıyor göstergesi ucu yok. Gösterge bir mesaj değildir, saklanmaz ve 25 saniyede söner.