API referansı

Uygulama rehberi

WhatsApp Business uygulamasıyla birlikte kullanılan (coexistence) numaraların telefondaki kişi rehberini okuyun ve senkron durumunu izleyin.

#AppContact nesnesi

idinteger
Kaydın kimliği (numara + telefon başına tekil). contact.synced olayındaki changes[].id ile aynıdır.
phone_number_idstring
Rehberin ait olduğu işletme numarası.
phonestring · boş olabilir
Kişinin telefonu, + önekiyle (E.164). Meta vermezse null.
wa_idstring · boş olabilir
WhatsApp kimliği (telefonun rakamları). Meta bu alanı göndermez; telefondan türetilir.
user_idstring · boş olabilir
Kişinin işletmeye özel kullanıcı kimliği (BSUID). Meta göndermediyse null.
full_namestring · boş olabilir
Telefondaki rehberde kayıtlı ad soyad. Silinen kayıtta null.
first_namestring · boş olabilir
Rehberdeki ad. Silinen kayıtta null.
sourcestring
Son değişikliğin kaynağı.Değerler: app_sync, app_initial_sync, app_backfill
updated_atstring
Son ekleme, güncelleme ya da silme zamanı (ISO 8601). updated_since buna göre süzer.
removed_atstring · boş olabilir
Kişi telefondaki rehberden silindiyse silinme zamanı (ISO 8601).

AppContact nesnesi

{
  "id": 501,
  "phone_number_id": "1234567890",
  "phone": "+905551112233",
  "wa_id": "905551112233",
  "user_id": "TR.1A2B3C4D5E6F7G8H",
  "full_name": "Ayşe Yılmaz",
  "first_name": "Ayşe",
  "source": "app_sync",
  "updated_at": "2026-10-13T10:15:00+03:00",
  "removed_at": null
}

#Uygulama rehberini listele

GET/app-contacts

Coexistence numaralarınızın telefondaki WhatsApp Business uygulaması rehberini döndürür. Panel kişi rehberinden (GET /contacts) ayrı bir kaynaktır. Sıralama updated_at azalan, sonra id azalan. İlk tam çekimden sonra contact.synced olayını dinleyin; kaçan olayları günlük updated_since + include_removed=true ile telafi edin. Kapsam: contacts:read

Kredi düşmez.

source: app_initial_sync (numara bağlanınca Meta'nın tek seferlik ilk aktarımı), app_sync (sonraki canlı değişiklik), app_backfill (2.23.0 öncesinde saklanmış olaylardan geriye dönük doldurulan kayıt; ilk aktarımı expired olan eski numaralarda da döner).

Meta telefondaki düzenlemeyi de add olarak gönderir; sunucu değişikliği karşılaştırıp yalnız gerçek değişiklikleri yazar.

Ayrılan numaranın kayıtları silinene kadar (purge_messages: true) okunabilir; ayrıldıktan sonra yeni senkron gelmez.

Test anahtarı (vmk_test_) gerçek veri yerine 3 sabit örnek kayıt döner ("simulated": true).

Meta belgesi: https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/smb_app_state_sync

Sorgu parametreleri

phone_number_idstringisteğe bağlı
Yalnız bu numaranın rehberi. Verilmezse hesabınızdaki bütün numaralar.
updated_sincestringisteğe bağlı
ISO 8601; yalnız updated_at bu zamana eşit ya da sonra olanlar (artımlı eşitleme).
include_removedbooleanisteğe bağlı
true ise telefondaki rehberden silinmiş kayıtlar da döner (removed_at dolu).Varsayılan: False
limitintegeristeğe bağlı
Sayfa boyutu (1–200).Varsayılan: 50
cursorstringisteğe bağlı
Opak imleç; önceki yanıttaki next_cursor.

Hatalar

Durum	Kod	Ne zaman
403	`insufficient_scope`	Anahtarda `contacts:read` kapsamı yok.
404	`number_not_found`	`phone_number_id` hesabınıza ait değil.
422	`invalid_request`	`updated_since`, `limit`, `cursor` ya da `phone_number_id` geçersiz (`field` alanına bakın).

curl -X GET "https://api.verimerkezi.app/wa/app-contacts?phone_number_id=1234567890&updated_since=2026-10-13T00%3A00%3A00%2B03%3A00" \
  -H "Authorization: Bearer $VM_API_KEY"

const res = await fetch("https://api.verimerkezi.app/wa/app-contacts?phone_number_id=1234567890&updated_since=2026-10-13T00%3A00%3A00%2B03%3A00", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VM_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.verimerkezi.app/wa/app-contacts?phone_number_id=1234567890&updated_since=2026-10-13T00%3A00%3A00%2B03%3A00",
    headers={"Authorization": f"Bearer {os.environ['VM_API_KEY']}"},
)
data = res.json()

<?php
$ch = curl_init("https://api.verimerkezi.app/wa/app-contacts?phone_number_id=1234567890&updated_since=2026-10-13T00%3A00%3A00%2B03%3A00");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("VM_API_KEY"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Yanıt 200

{
  "ok": true,
  "app_contacts": [
    {
      "id": 501,
      "phone_number_id": "1234567890",
      "phone": "+905551112233",
      "wa_id": "905551112233",
      "user_id": "TR.1A2B3C4D5E6F7G8H",
      "full_name": "Ayşe Yılmaz",
      "first_name": "Ayşe",
      "source": "app_sync",
      "updated_at": "2026-10-13T10:15:00+03:00",
      "removed_at": null
    }
  ],
  "next_cursor": "eyJpZCI6NTAxLCJrIjoidXBkYXRlZF9hdCIsImQiOiJkZXNjIiwidSI6IjIwMjYtMTAtMTMgMTA6MTU6MDAifQ",
  "has_more": true
}

#Rehber senkron durumunu getir

GET/numbers/{phone_number_id}/app-contacts/sync

Numaranın uygulama rehberi senkronunu destekleyip desteklemediğini, ilk aktarımın durumunu ve kayıt sayılarını döndürür. Kapsam: contacts:read

reason: not_coexistence (numara WhatsApp Business uygulamasıyla birlikte kullanılmıyor), number_detached (numara ayrıldı; yeni senkron gelmez) ya da null.

initial_sync.status: not_requested, requested, in_progress, completed, expired (Meta'nın süresi geçti), failed.

Meta ilk aktarımı yalnız numara bağlandıktan sonraki 24 saat içinde ve bir kez verir; Veri Merkezi bunu bağlantı anında otomatik ister. Tekrar istemek için API ucu yoktur: tam rehberi yeniden almak için numarayı panelden ayırıp yeniden bağlayın. Sonraki ekleme, düzenleme ve silmeler Meta'dan kendiliğinden gelir.

Rehberi boş numarada Meta parça göndermeyebilir; istekten 60 dakika sonra durum completed, completed_at null olur.

Meta belgesi: https://developers.facebook.com/docs/whatsapp/embedded-signup/custom-flows/onboarding-business-app-users

Yol parametreleri

phone_number_idstringzorunlu
Numaranızın Meta kimliği (yalnız rakam, 5–32 hane).

Hatalar

Durum	Kod	Ne zaman
403	`insufficient_scope`	Anahtarda `contacts:read` kapsamı yok.
404	`number_not_found`	Numara size ait değil.
422	`invalid_request`	`phone_number_id` yalnız rakam olmalı.

curl -X GET "https://api.verimerkezi.app/wa/numbers/1234567890/app-contacts/sync" \
  -H "Authorization: Bearer $VM_API_KEY"

const res = await fetch("https://api.verimerkezi.app/wa/numbers/1234567890/app-contacts/sync", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VM_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.verimerkezi.app/wa/numbers/1234567890/app-contacts/sync",
    headers={"Authorization": f"Bearer {os.environ['VM_API_KEY']}"},
)
data = res.json()

<?php
$ch = curl_init("https://api.verimerkezi.app/wa/numbers/1234567890/app-contacts/sync");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("VM_API_KEY"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Yanıt 200

{
  "ok": true,
  "phone_number_id": "1234567890",
  "coexistence": true,
  "sync_supported": true,
  "reason": null,
  "initial_sync": {
    "status": "completed",
    "requested_at": "2026-10-13T09:00:00+03:00",
    "completed_at": "2026-10-13T09:02:10+03:00"
  },
  "last_event_at": "2026-10-13T10:15:00+03:00",
  "contact_count": 842,
  "removed_count": 12
}