WhatsMod Public API

Hızlı Başlangıç

1. 1
   Hesap aç + token üret. app.whatsmod.io → Ayarlar → API Tokens → Yeni Token. Scope seçin: otp (OTP), messages.send (mesaj gönder), messages.read (durum/geçmiş oku) veya * (tam erişim). En az yetki ilkesi: yalnız ihtiyacın olan scope'u ver.
2. 2
   WhatsApp hesabı bağlayın. Numaranızı QR kodla bağlayın (Ayarlar → Numaralar). Aktif ve connected olmalı.
3. 3
   İsteği atın. Aşağıdaki curl örneğini kopyalayın, wsk_... yerine token'ınızı yapıştırın, telefon numarasını güncelleyin.
4. 4
   Cevabı alın. HTTP 202 + JSON: {sent: true, messageId: "...", creditsRemaining: 498}

Kimlik Doğrulama

Tüm isteklerde Authorization: Bearer wsk_... header'ı zorunlu. Token wsk_ önekiyle başlar ve 52 karakterdir. Sadece üretildiği anda bir kez gösterilir — güvenli bir yerde saklayın.

Endpoint'ler

Base URL: https://gw.whatsmod.io

curl https://gw.whatsmod.io/api/public/v1/accounts \
  -H "Authorization: Bearer wsk_YOUR_TOKEN"

{
  "data": [
    {
      "id": "ck...",
      "phoneNumber": "905XXXXXXXXX",
      "displayName": "Satış",
      "status": "connected",
      "lastSeenAt": "2026-05-25T10:00:00.000Z"
    }
  ]
}

curl -X POST https://gw.whatsmod.io/api/public/v1/messages \
  -H "Authorization: Bearer wsk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2e4a-8b3d-4c5e-a1b2-c3d4e5f6a7b8" \
  -d '{
    "accountId": "ck...",
    "to": "+905XXXXXXXXX",
    "text": "Merhaba! Siparişiniz hazır."
  }'

{
  "message": {
    "id": "ck...",
    "status": "pending",
    "creditsUsed": 1
  }
}

const res = await fetch('https://gw.whatsmod.io/api/public/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WHATSMOD_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    accountId: 'ck...',
    to: '+905XXXXXXXXX',
    text: 'Merhaba! Siparişiniz hazır.',
  }),
});
const data = await res.json();

curl -X POST https://gw.whatsmod.io/api/public/v1/messages/media \
  -H "Authorization: Bearer wsk_YOUR_TOKEN" \
  -H "Idempotency-Key: 9f1c2e4a-8b3d-4c5e-a1b2-c3d4e5f6a7b8" \
  -F "accountId=ck..." \
  -F "to=+905XXXXXXXXX" \
  -F "type=image" \
  -F "caption=Ürün görseli" \
  -F "file=@/path/to/product.jpg"

{
  "message": {
    "id": "ck...",
    "status": "pending",
    "creditsUsed": 1
  }
}

curl https://gw.whatsmod.io/api/public/v1/messages/ck... \
  -H "Authorization: Bearer wsk_YOUR_TOKEN"

{
  "id": "ck...",
  "direction": "outbound",
  "type": "text",
  "status": "delivered",
  "creditsUsed": 1,
  "deliveredAt": "2026-05-25T10:01:00.000Z",
  "readAt": null,
  "createdAt": "2026-05-25T10:00:00.000Z"
}

curl "https://gw.whatsmod.io/api/public/v1/conversations/ck.../messages?limit=50" \
  -H "Authorization: Bearer wsk_YOUR_TOKEN"

{
  "items": [
    {
      "id": "ck...",
      "direction": "inbound",
      "type": "text",
      "content": "Merhaba",
      "status": "read",
      "createdAt": "2026-05-25T09:59:00.000Z"
    }
  ],
  "nextCursor": "ck...",
  "hasMore": true
}

curl -X POST https://gw.whatsmod.io/api/public/v1/otp/send \
  -H "Authorization: Bearer wsk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+905XXXXXXXXX",
    "code": "123456",
    "site": "Siteniz"
  }'

{
  "sent": true,
  "messageId": "ck...",
  "wamid": "3EB0...",
  "creditsRemaining": 498,
  "expiresAt": "2026-05-25T14:40:12.000Z"
}

<?php
$ch = curl_init('https://gw.whatsmod.io/api/public/v1/otp/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $token,
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'phone' => '+905XXXXXXXXX',
  'code' => '123456',
  'site' => 'Siteniz',
]));
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);

const res = await fetch('https://gw.whatsmod.io/api/public/v1/otp/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WHATSMOD_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+905XXXXXXXXX',
    code: '123456',
    site: 'Siteniz',
  }),
});
const data = await res.json();

curl https://gw.whatsmod.io/api/public/v1/balance \
  -H "Authorization: Bearer wsk_YOUR_TOKEN"

{
  "creditBalance": 12450,
  "plan": "pro",
  "accountLimit": 5
}

Webhook'lar

Tenant panelinizden (Ayarlar → Webhooks) URL kaydedin, aşağıdaki event tiplerinden seçim yapın. POST isteği JSON body ile ulaşır. Wait-and-retry 3 kez.

POST https://your-server.com/webhooks/whatsmod HTTP/1.1
Content-Type: application/json

{
  "event": "otp.sent",
  "phone": "+9054*****76",
  "status": "sent",
  "messageId": "ck...",
  "wamid": "3EB0...",
  "tokenId": "ck...",
  "accountId": "ck...",
  "sourceHost": "siteniz.com",
  "userAgent": "whatsmod-wp/1.0.0",
  "occurredAt": "2026-04-24T14:35:12Z"
}

Güvenlik: Webhook payload'ında ham OTP kodu asla yer almaz. Telefon numaraları maskelenir (ilk 5 + son 2 karakter). Hassas bilgi sızması riski yoktur.

Rate Limit'ler

Kurumsal paket kullanıcıları için özel limitler satış ekibimizden talep edilebilir.

Idempotency (Çift Gönderim Önleme)

Ağ kopması veya zaman aşımında isteği güvenle tekrarlayabilmek için POST /messages ve POST /messages/media isteklerine Idempotency-Key header'ı ekleyin (8-255 karakter, UUID önerilir).

• ✓Aynı anahtarla tekrar denenen istek mesajı yeniden GÖNDERMEZ; ilk sonucu aynen döner ve yanıta Idempotent-Replay: true header'ı eklenir.
• ✓Yalnız başarılı gönderim 24 saat saklanır. Hata olursa (kredi/ağ) anahtar serbest bırakılır — gerçek bir retry sorunsuz çalışır.
• ✓Aynı anahtarla eşzamanlı ikinci istek IDEMPOTENCY_IN_PROGRESS (HTTP 409) döner — kısa bir bekleyip tekrar deneyin.

Her mantıksal gönderim için yeni bir anahtar üretin (örn. crypto.randomUUID()). Aynı anahtarı farklı içerikle tekrar kullanırsanız, ikinci içerik gönderilmez — ilk gönderimin sonucu döner.

Hata Kodları

Hata formatı: {code: "...", message: "...", details?: {...}}

Güvenlik

• ✓Tüm istekler HTTPS (TLS 1.3) üzerinden. HTTP kabul edilmez.
• ✓Token'lar DB'de SHA-256 hash olarak saklanır — plain hiçbir yerde yok.
• ✓OTP kodları da sadece SHA-256 hash olarak audit log'unda tutulur (ham kod yok).
• ✓Scope'lu token'lar yalnız izinli endpoint'lere erişir (otp / messages.send / messages.read) — zorlama sunucu tarafında yapılır.
• ✓Token tek bir WhatsApp hesabına allowedAccountId ile kilitlenir ve gönderimde zorlanır — ele geçirilen token'ın blast radius'unu küçültür.
• ✓Idempotency-Key ile güvenli retry — ağ kopmasında çift mesaj gönderimi engellenir.
• ✓Webhook payload'ları telefon numaralarını maskeler, OTP kodu ASLA webhook'ta yer almaz.

Postman ile Hızlı Test

Tüm endpoint'ler Postman collection olarak hazır. İndir, token\'ını yapıştır, test isteği at.

SDK'lar

Her dilde HTTP isteği yazmak yerine hazır client kullanın. Tam TypeScript desteği, typed errors, retry-safe.

npm install @whatsmod/client

import { WhatsMod } from '@whatsmod/client';
const client = new WhatsMod({ apiToken: 'wsk_...' });
await client.otp.send({ phone: '+905...', code: '123456' });

composer require whatsmod/client

$client = new \WhatsMod\Client(['api_token' => 'wsk_...']);
$client->otp->send(['phone' => '+905...', 'code' => '123456']);