Aidiance Messaging API — Entegrasyon dokümantasyonu

Temel URL

https://www.aidiance.com/api/v1/{resource}

JSON. CORS yok (tarayıcıya anahtar koymayın). Yalnızca HTTPS. Anahtarları panelden oluşturun: Ayarlar → Entegrasyon.

Kimlik doğrulama

Her istekte dört başlık zorunludur:

Başlık	Açıklama
`Authorization`	`Bearer aid_live_…` — panelde bir kez gösterilir, sunucuda yalnızca HMAC karması tutulur.
`X-Aidiance-Timestamp`	Unix saniye (UTC). ±5 dakika pencere.
`X-Aidiance-Nonce`	16–64 hex karakter, anahtar başına tek kullanımlık (replay koruması).
`X-Aidiance-Signature`	Aşağıdaki kanonik metnin HMAC-SHA256 (hex) değeri.
`X-Aidiance-Idempotency-Key`	İsteğe bağlı (POST gönderim). 24 saat aynı yanıtı döndürür; çift mesajı önler.

Yetkiler (scope): conversations.read, messages.read, messages.send. Anahtar isteğe bağlı IP allowlist ve asistan kısıtı ile üretilir.

İmza algoritması

UTF-8, satır sonu \n:

timestamp
nonce
METHOD
resource
canonicalQuery
sha256hex(body)

METHOD büyük harf: GET / POST
resource küçük harf: messages, conversations, …
canonicalQuery: resource hariç sorgu parametreleri, anahtara göre sıralı key=urlencode(value). POST’ta boş satır.
body ham baytlar (GET’te boş; SHA-256 boş gövde = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855)

İmza: HMAC-SHA256(api_key, payload) küçük harf hex. Gönderilen JSON ile hash’lenen gövde birebir aynı olmalıdır.

Konuşma kimliği

Kanal	conversation_id
whatsapp	`wa:{asistan_token}:{telefon}` — telefon ülke kodu ile, yalnızca rakam
instagram	`ig:{asistan_token}:{participant_id}`
twitter	`x:{asistan_token}:{participant_id}`
web	`web:{grpid}`

Liste uçundan gelen id alanını olduğu gibi kullanın. WhatsApp 24 saatlik oturum penceresi Meta kurallarına tabidir.

Uçlar

GET /api/v1/me

Anahtar adı, scope ve kanal özeti. Gövde yok.

GET /api/v1/assistants

Hesaba (ve anahtar kısıtına) ait asistanlar. Scope: conversations.read veya messages.read.

GET /api/v1/conversations

Sorgu: channel (whatsapp | instagram | twitter | web, boş = izinli hepsi), limit (1–50).

{
  "ok": true,
  "items": [
    {
      "id": "wa:TOKEN:905551112233",
      "channel": "whatsapp",
      "assistant_token": "TOKEN",
      "assistant_name": "Satış",
      "contact": "Ayşe",
      "handle": "905551112233",
      "last_message": "Merhaba",
      "last_at": "2026-09-10T16:01:00"
    }
  ]
}

GET /api/v1/messages

Sorgu: conversation_id (zorunlu), since_id (dahil değil, polling), limit (1–50).

{
  "ok": true,
  "items": [
    {
      "id": 1201,
      "provider_id": "wamid....",
      "direction": "inbound",
      "type": "text",
      "text": "Fiyat nedir?",
      "status": "",
      "created_at": "2026-09-10T16:00:12"
    }
  ]
}

Yeni mesaj için son gördüğünüz id ile since_id gönderin (en fazla birkaç saniyede bir; rate limit).

POST /api/v1/messages

{
  "conversation_id": "wa:TOKEN:905551112233",
  "text": "Merhaba, nasıl yardımcı olabilirim?"
}

veya:

{
  "channel": "whatsapp",
  "assistant_token": "TOKEN",
  "to": "905551112233",
  "text": "Merhaba"
}

Başarılı: ok, message_id, conversation_id. Metin en fazla 4096 karakter.

Hatalar

{
  "ok": false,
  "error": "bad_signature",
  "message": "İmza doğrulanamadı.",
  "request_id": "…"
}

HTTP	error
401	auth_required / invalid_key / bad_signature / replay	Kimlik veya imza
403	https_required / ip_denied / insufficient_scope / forbidden	Yetki
429	rate_limited / auth_locked	Hız limiti
502	provider_error	WhatsApp / Meta / X

Python örneği

import hashlib, hmac, json, time, uuid, requests

KEY = "aid_live_..."  # panelden
BASE = "https://www.aidiance.com/api/v1"

def call(method, resource, query=None, json_body=None):
    ts = str(int(time.time()))
    nonce = uuid.uuid4().hex
    body = b""
    if json_body is not None:
        body = json.dumps(json_body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    q_items = []
    if query:
        for k in sorted(query):
            if k == "resource":
                continue
            q_items.append("%s=%s" % (requests.utils.quote(str(k), safe=""), requests.utils.quote(str(query[k]), safe="")))
    canon_q = "&".join(q_items)
    payload = "\n".join([ts, nonce, method.upper(), resource.lower(), canon_q, hashlib.sha256(body).hexdigest()])
    sig = hmac.new(KEY.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
    headers = {
        "Authorization": "Bearer " + KEY,
        "X-Aidiance-Timestamp": ts,
        "X-Aidiance-Nonce": nonce,
        "X-Aidiance-Signature": sig,
        "Content-Type": "application/json",
    }
    url = BASE + "/" + resource
    if query:
        url += "?" + "&".join("%s=%s" % (k, requests.utils.quote(str(query[k]), safe="")) for k in query)
    if method == "GET":
        return requests.get(url, headers=headers, timeout=20)
    headers["X-Aidiance-Idempotency-Key"] = uuid.uuid4().hex
    return requests.post(url, data=body, headers=headers, timeout=20)

print(call("GET", "conversations", {"channel": "whatsapp", "limit": "20"}).json())
print(call("POST", "messages", json_body={
    "conversation_id": "wa:TOKEN:905551112233",
    "text": "Merhaba"
}).json())

PHP örneği (imza)

function aidiance_sign($key, $ts, $nonce, $method, $resource, $canonQuery, $body) {
    $bodyHash = hash('sha256', $body === null ? '' : $body);
    $payload = $ts."\n".$nonce."\n".strtoupper($method)."\n".strtolower($resource)."\n".$canonQuery."\n".$bodyHash;
    return hash_hmac('sha256', $payload, $key);
}

GET konuşma listesi için canonicalQuery örneği: channel=whatsapp&limit=20 (alfabetik).

Güvenlik kuralları

Anahtarı git’e, frontend’e veya log’a yazmayın. Sızıntıda panelden hemen iptal edin.
Mümkünse IP allowlist kullanın (sunucu çıkış IP’niz).
Gönderim yetkisini yalnızca ihtiyaç varsa verin; salt okuma anahtarı ayrı üretin.
Nonce’u her istekte yenileyin; aynı imzayı tekrar kullanmayın.
Bu API mobil uygulama oturum API’sinden (/app_api/) ayrıdır.

Messaging API v1