Uygulama rehberi | Veri Merkezi API

Numaranız WhatsApp Business uygulamasıyla birlikte (coexistence) bağlıysa, telefondaki uygulamanın kişi rehberi Veri Merkezi'ne aktarılır. Rehberde kişi eklediğinizde, adını değiştirdiğinizde ya da sildiğinizde değişiklik birkaç saniye içinde gelir. Bu veri, panel kişi rehberinden (GET /contacts) ayrıdır.

Uç	Ne yapar
`GET /app-contacts`	Rehber kayıtlarını listeler (süzgeç + imleçle sayfalama).
`GET /numbers/{phone_number_id}/app-contacts/sync`	Numaranın senkron durumunu ve kayıt sayılarını verir.
`contact.synced` olayı	Ekleme, düzenleme ve silmeleri toplu gönderir.

Kapsam: contacts:read. Kredi düşmez.

#Nasıl çalışır

Numara coexistence ile bağlanınca Veri Merkezi, Meta'dan rehberin ilk aktarımını otomatik ister. Kayıtlar source: "app_initial_sync" ile gelir.
Sonrasında telefondaki her ekleme, düzenleme ve silme Meta'dan kendiliğinden gelir (source: "app_sync").
2.23.0'dan önce bağlanmış numaralarda daha önce saklanmış rehber olayları geriye dönük işlendi (source: "app_backfill").

Not Meta ilk aktarımı yalnız numara bağlandıktan sonraki 24 saat içinde ve bir kez verir (Meta belgesi). Tekrar istemek için uç yoktur. Eski numarada durum ucu initial_sync.status: "expired" döner. Tam rehberi yeniden almak için numarayı panelden ayırıp yeniden bağlayın.

#Durumu kontrol edin

BASH

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

sync_supported: false ise reason nedeni verir: not_coexistence (numara uygulamayla birlikte kullanılmıyor) ya da number_detached (numara ayrıldı). contact_count etkin, removed_count silinmiş kayıt sayısıdır.

#İlk tam çekim

BASH

curl "https://api.verimerkezi.app/wa/app-contacts?phone_number_id=1234567890&include_removed=true&limit=200" \
  -H "Authorization: Bearer $VM_API_KEY"

let cursor = null;
do {
  const sayfa = await vm.listAppContacts({ phoneNumberId: '1234567890', includeRemoved: true, limit: 200, cursor });
  for (const k of sayfa.app_contacts) kaydet(k);
  cursor = sayfa.next_cursor;
} while (cursor);

cursor = None
while True:
    sayfa = vm.list_app_contacts(phone_number_id='1234567890', include_removed=True, limit=200, cursor=cursor)
    for k in sayfa['app_contacts']:
        kaydet(k)
    cursor = sayfa.get('next_cursor')
    if not cursor:
        break

Parametre	Açıklama
`phone_number_id`	Yalnız bu numaranın rehberi. Verilmezse bütün numaralarınız.
`updated_since`	ISO 8601. Yalnız bu zamandan sonra değişen kayıtlar.
`include_removed`	`true` ise rehberden silinmiş kayıtlar da gelir (`removed_at` dolu).
`limit`	1–200, varsayılan 50.
`cursor`	Önceki yanıttaki `next_cursor`.

Sıralama updated_at azalan, sonra id azalandır. Kayıt alanları: id, phone_number_id, phone (E.164), wa_id, user_id (BSUID), full_name, first_name, source, updated_at, removed_at.

#Değişiklikleri olayla alın

Webhook aboneliğinize contact.synced olayını ekleyin (* aboneliği bu olayı kapsamaz).

JSON

{
  "event": "contact.synced",
  "data": {
    "phone_number_id": "1234567890",
    "sync_type": "incremental",
    "batch": { "index": 1, "count": 1 },
    "changes": [
      { "action": "update", "id": 502, "phone": "+905552223344", "wa_id": "905552223344", "user_id": null,
        "full_name": "Mehmet Kaya (İş)", "first_name": "Mehmet", "changed_at": "2026-10-13T10:15:00+03:00" }
    ]
  }
}

changes[].action: add, update ya da remove. Meta düzenlemeyi de "ekleme" olarak gönderir; Veri Merkezi karşılaştırıp yalnız gerçek değişikliği yayınlar.
remove'da full_name ve first_name nulldır. Eşleştirmeyi id (yoksa phone) ile yapın.
Bir olayda en fazla 100 değişiklik bulunur. Fazlası batch.index / batch.count ile bölünür. İlk aktarımda sync_type: "initial" gelir.
Olay kaçırırsanız günde bir kez artımlı okuyun: GET /app-contacts?updated_since=<son eşitleme>&include_removed=true.

#Test edin

Test anahtarıyla (vmk_test_) GET /app-contacts 3 sabit örnek kayıt döner ("simulated": true). Webhook alıcınızı denemek için:

BASH

curl -X POST https://api.verimerkezi.app/wa/test/inbound \
  -H "Authorization: Bearer $VM_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "1234567890", "type": "app_contact_sync" }'

Bu istek add, update ve remove içeren örnek bir contact.synced olayı gönderir. Rehbere kayıt yazılmaz.

#Silme

POST /numbers/{phone_number_id}/detach + purge_messages: true: numaranın rehber kayıtları silinir (number.purged → counts.app_contacts). false ise kayıtlar kalır, yeni senkron durur.
POST /privacy/erasure: kişinin rehber kayıtları da silinir (erased.app_contacts).

Tüm alanlar: Uygulama rehberi referansı.