API referansı

Chats

Sohbet listesi, telefon numarasından sohbet eşleştirme ve sohbet mesaj geçmişi.

get/chats

Sohbetleri listele

Hesaba bağlı sohbetleri son mesaj zamanına göre yeniden eskiye doğru döndürür. Yanıt sayfalıdır: yoğun hatlarda sohbet sayısı on binlere çıkabildiği için tek çağrıda tamamı dönmez. `conversation_state` sohbetin panelde görünen Aktif/Pasif durumudur (`active` | `passive`); `state` parametresiyle yalnız bir durumu listeleyebilirsiniz — süzgeç veritabanında uygulandığı için `limit`/`offset` sayfalaması süzülmüş liste üzerinde doğru çalışır. `last_responder` sohbete en son kimin adına mesaj gittiğini söyler (`null` olabilir). ⚠️ Bu bir **atama** değildir: ZenWapp'ta sohbet başına atama yoktur. Hatta atanmış ekip üyeleri `GET /account` → `assigned_agents` alanındadır.

Gerekli yetki: chats:read

Sorgu parametreleri

`limit`	`integer`	Döndürülecek sohbet sayısı. Üst sınırı aşan değerler sınıra kırpılır.Varsayılan: `500`
`offset`	`integer`	Kaç sohbet atlanacak. `limit` ile birlikte sayfa atlamak için kullanılır.Varsayılan: `0`
`state`	`string`	Sohbet durumu süzgeci. Verilmezse her durum döner. Geçersiz değer `400 validation_error` verir.Değerler: `active`, `passive`

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/chats" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": [
    {
      "id": "[email protected]",
      "name": "Ahmet Yılmaz",
      "type": "direct",
      "is_muted": false,
      "is_archived": false,
      "conversation_state": "active",
      "last_responder": {
        "id": "a1f2c3d4-1111-2222-3333-444455556666",
        "name": "Okan Hocaoğlu"
      },
      "last_message_at": "2026-09-04T12:41:23+00:00"
    }
  ],
  "paging": {
    "limit": 500,
    "offset": 0,
    "state": "active",
    "fetched": 1,
    "hasMore": false
  }
}

Yanıt kodları

200Sohbet listesi
400Gövde veya sorgu parametreleri geçersiz
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok

get/chats/resolve

Telefondan sohbet bul

Serbest formatlı bir telefon numarasını normalize ederek o numaraya ait sohbetleri bulur. Numara biçimi farklılıklarını (boşluk, `+`, `0` öneki) kendisi çözer. Bir numaranın birden fazla sohbet kaydı olabildiği için yanıt her zaman liste döndürür; eşleşme yoksa `404`.

Gerekli yetki: chats:read

Sorgu parametreleri

phonezorunlu string Ülke kodlu telefon numarası. `+90 555 123 45 67`, `05551234567` ve `905551234567` aynı sonucu verir.

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/chats/resolve?phone=905551234567" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "phone": "905551234567",
  "count": 1,
  "matches": [
    {
      "id": "[email protected]",
      "chat_id": "[email protected]",
      "name": "Ahmet Yılmaz",
      "phone": "905551234567",
      "last_message_at": "2026-09-04T12:41:23+00:00",
      "contact_name": "Ahmet Yılmaz",
      "contact_pushname": null,
      "type": "direct"
    }
  ]
}

Yanıt kodları

200Eşleşen sohbet
400Gövde veya sorgu parametreleri geçersiz
404Kaynak bulunamadı

get/chats/{chatId}/messages

Sohbet mesajlarını getir

Bir sohbetin mesaj geçmişini döndürür. **Sayfa içindeki sıra eskiden yeniye**; yani dizinin son elemanı en yeni mesajdır. Geçmişe doğru sayfalamak için yanıttaki `paging.nextBefore` değerini bir sonraki çağrının `before` parametresine verin.

Gerekli yetki: messages:read

Yol parametreleri

chatIdzorunlu string Sohbet kimliği (örn. `[email protected]`).

Sorgu parametreleri

`limit`	`integer`	Döndürülecek mesaj sayısı.Varsayılan: `50`
`before`	`ISO 8601`	Bu zaman damgasından önceki mesajları getirir (ISO 8601). Sayfalama imleci.
`include_raw`	`boolean`	Ham sağlayıcı verisini yanıta ekler.Varsayılan: `true`
`include_presigned_url`	`boolean`	Medya mesajları için süreli indirme bağlantısı üretir.Varsayılan: `true`

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/chats/905551234567/messages" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": [
    {
      "provider": "evolution",
      "account_id": "6e170999-ac8d-4286-80b8-5e2adf70c2ee",
      "message_id": "ACCBAEC4F0637671F23A8589C0B917F1",
      "chat_id": "[email protected]",
      "from_me": false,
      "sender": "[email protected]",
      "receiver": null,
      "body": "Merhaba, fiyat listesi alabilir miyim?",
      "type": "text",
      "normalized_type": "text",
      "timestamp": "2026-09-04T12:41:23+00:00",
      "status": "delivered",
      "source_type": "whatsapp",
      "has_media": false,
      "media": null
    },
    {
      "provider": "evolution",
      "message_id": "3EB0DCDFED6F913E34D131",
      "chat_id": "[email protected]",
      "from_me": true,
      "body": "Fiyat listemiz ekte.",
      "type": "document",
      "normalized_type": "document",
      "timestamp": "2026-09-04T12:03:25+00:00",
      "status": "read",
      "has_media": true,
      "media": {
        "presigned_url": "https://nbg1.your-objectstorage.com/zenwapp-storage/...",
        "expires_in": 3600,
        "mime_type": "application/pdf",
        "filename": "fiyat-listesi.pdf",
        "size": 611730,
        "storage": "s3"
      }
    }
  ],
  "paging": {
    "hasMore": true,
    "nextBefore": "2026-09-04T12:03:25+00:00",
    "fetched": 2,
    "limit": 50
  }
}

Yanıt kodları

200Mesaj listesi
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok

put/chats/state

Sohbet durumlarını toplu değiştir

Birden fazla sohbeti tek çağrıda Pasif ya da Aktif yapar. Tek tek `PUT /chats/{chatId}/state` çağırmak yerine kullanın: yüzlerce eski sohbeti kapatmak tek istekle biter. Kurallar: - `chat_ids` boş olamaz; tekrarlanan kimlikler teke indirilir. - Tekil kimlik sayısı **500**'ü geçerse `400 too_many_chats` döner. Daha fazlası için istekleri 500'lük partilere bölün. - Bu hatta bulunmayan kimlikler isteği düşürmez; `not_found` listesinde geri döner (kısmi başarı normaldir). - Her kasıtlı değişiklik denetim izine yazılır; `GET /chats/{chatId}/state/history` ile okunur.

Gerekli yetki: chats:write

Gövde alanları

`chat_ids`zorunlu	`string[]`	Sohbet kimlikleri. `GET /chats` yanıtındaki `id` alanları.
`state`zorunlu	`string`	Değerler: `active`, `passive`

İstek örneği

curl -X PUT "https://api.zenwapp.com/api/v1/whatsapp/external/chats/state" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_ids":["[email protected]","[email protected]"],"state":"passive"}'

Yanıt 200

{
  "success": true,
  "data": {
    "state": "passive",
    "updated": [
      "[email protected]"
    ],
    "not_found": [
      "[email protected]"
    ],
    "updated_count": 1,
    "not_found_count": 1
  }
}

Yanıt kodları

200Durumlar güncellendi (kısmi başarı dahil)
400`validation_error` (eksik ya da boş `chat_ids`, geçersiz `state`) veya `too_many_chats` (500 üstü tekil kimlik)
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok

get/chats/{chatId}/state

Sohbet durumunu getir

Sohbetin panelde görünen Aktif/Pasif durumunu döndürür. Pasif sohbetler Inbox'ta "Pasif" süzgecinde listelenir ve cevap bekleyen sayımına girmez. Sohbet bu hatta yoksa `404`.

Gerekli yetki: chats:read

Yol parametreleri

chatIdzorunlu string Sohbet kimliği (örn. `[email protected]`). `GET /chats` ya da `GET /chats/resolve` yanıtındaki `id`.

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/chats/905551234567/state" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": {
    "chat_id": "[email protected]",
    "conversation_state": "active"
  }
}

Yanıt kodları

200Sohbet durumu
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok
404Kaynak bulunamadı

put/chats/{chatId}/state

Sohbet durumunu değiştir

Sohbeti Pasif yapar (paneldeki "Konuşmayı Sonlandır") ya da yeniden Aktif yapar. Sohbete yeni bir mesaj gelince ya da sohbetten mesaj gidince durum kendiliğinden `active` olur. Sohbet bu hatta yoksa `404`.

Gerekli yetki: chats:write

Yol parametreleri

chatIdzorunlu string Sohbet kimliği (örn. `[email protected]`).

Gövde alanları

statezorunlu string Değerler: active, passive

İstek örneği

curl -X PUT "https://api.zenwapp.com/api/v1/whatsapp/external/chats/905551234567/state" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"passive"}'

Yanıt 200

{
  "success": true,
  "data": {
    "chat_id": "[email protected]",
    "conversation_state": "passive"
  }
}

Yanıt kodları

200Durum güncellendi
400Gövde veya sorgu parametreleri geçersiz
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok
404Kaynak bulunamadı

get/chats/{chatId}/state/history

Sohbet durum geçmişi

Sohbetin Aktif/Pasif durumunun **kasıtlı** değişikliklerini yeniden eskiye doğru döndürür: kim (API anahtarı ya da panel kullanıcısı), ne zaman, hangi durumdan hangi duruma. ⚠️ **Sohbete mesaj gelince durumun kendiliğinden `active` olması geçmişe yazılmaz.** Yoğun bir hatta günde binlerce satır olurdu; o davranış mesaj akışından okunur. `changed_by` değerleri: `api_key` (dış API), `user` (panel), `system` (otomasyon). `changed_by_name` anahtarın ya da kullanıcının görünen adıdır; iç kimlikler dışa verilmez. Sohbet bu hatta yoksa `404`.

Gerekli yetki: chats:read

Yol parametreleri

chatIdzorunlu string Sohbet kimliği (örn. `[email protected]`).

Sorgu parametreleri

`limit`	`integer`	Döndürülecek kayıt sayısı. Üst sınırı aşan değerler sınıra kırpılır.Varsayılan: `50`
`offset`	`integer`	Kaç kayıt atlanacak.Varsayılan: `0`

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/chats/905551234567/state/history" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": {
    "chat_id": "[email protected]",
    "history": [
      {
        "from_state": "active",
        "to_state": "passive",
        "changed_by": "api_key",
        "changed_by_name": "n8n entegrasyonu",
        "created_at": "2026-10-18T14:02:11.482Z"
      },
      {
        "from_state": "passive",
        "to_state": "active",
        "changed_by": "user",
        "changed_by_name": "Okan Hocaoğlu",
        "created_at": "2026-10-12T09:31:44.117Z"
      }
    ],
    "paging": {
      "limit": 50,
      "offset": 0,
      "fetched": 2,
      "hasMore": false
    }
  }
}

Yanıt kodları

200Durum değişiklik geçmişi
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok
404Kaynak bulunamadı