Formlar (WhatsApp Flows)

Formlar (WhatsApp Flows), müşterinin sohbetten çıkmadan doldurduğu çok ekranlı arayüzlerdir: başvuru, randevu, anket, iletişim formu. Form tasarımı Meta'nın Flow JSON biçimindedir. Müşteri formu gönderdiğinde yanıt flow.completed olayıyla gelir.

#Akış

1. POST /flows ile formu DRAFT olarak oluşturun.
2. validation_errors boş değilse PUT /flows/{flow_id}/json ile düzeltin.
3. Taslağı kendinize POST /messages ve flow.mode: "draft" ile göndererek deneyin.
4. POST /flows/{flow_id}/publish ile yayınlayın. Yayınlanan form değiştirilemez.
5. Müşteriye form mesajı ya da form butonlu şablon gönderin.
6. Yanıtı flow.completed olayıyla alın.

Formlar işletme hesabı (WABA) düzeyindedir; phone_number_id ile numaranızın WABA'sı seçilir. Form yönetimi kredi düşmez; form mesajı normal mesaj gibi 1 kredidir. Gerekli kapsamlar: flows:read, flows:write.

#Form oluşturun

curl -X POST https://api.verimerkezi.app/wa/flows \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "phone_number_id": "1234567890",
    "name": "Teklif formu",
    "categories": ["LEAD_GENERATION"],
    "flow_json": { "version": "7.2", "screens": [] }
  }'

const form = await vm.createFlow('1234567890', 'Teklif formu', ['LEAD_GENERATION'], flowJson);
console.log(form.flow_id, form.validation_errors);

form = vm.create_flow('1234567890', 'Teklif formu', ['LEAD_GENERATION'], flow_json)
print(form['flow_id'], form['validation_errors'])

<?php
$form = $vm->createFlow('1234567890', 'Teklif formu', ['LEAD_GENERATION'], $flowJson);
echo $form['flow_id'];

{ "ok": true, "flow_id": "1234567890123456", "status": "DRAFT", "validation_errors": [] }

• categories en az bir değer içermelidir: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER.
• flow_json nesne ya da JSON metni olabilir; en fazla 10 MB.
• Form yazma uçları test anahtarıyla çalışmaz (403 test_mode_unsupported).

#Koşullu alanlar (If) — Meta kuralları

Meta'nın If bileşeninde (condition) == ve != için iki taraf aynı türde olmalıdır. Metin değişmezi tek tırnakla ('2'), sayı tırnaksız yazılır. >, >=, <, <= yalnız sayılarla çalışır. İç içe If en fazla 3 seviyedir (Meta: If bileşeni).

Canlı Meta testlerinde (14.10.2026) ek kısıtlar gözlendi:

• Bir ifadede tek eşitlik. (${form.arac} == '2') || (${form.arac} == '3') reddedilir. Meta bunu ((${form.arac} == '2') || ${form.arac}) == '3' diye çözer ve Type mismatch in an equality operation hatası verir.
• Çalışan biçimler: tek karşılaştırma (${form.arac} == '2'), mantıksal değerle birleşim (${form.onay} || (${form.arac} == '2')), sayısal aralık ((${form.yas} > 2) || (${form.yas} < 1)).
• Birden çok değeri kontrol etmek için koşulu iç içe If'lere bölün (en fazla 3 seviye) ya da her değer için ayrı bir If yazın.
• Switch bileşeni aynı testlerde Cannot read property 'type' hatası verdi. Şimdilik If kullanın.

Meta bu hatayla reddettiğinde yanıta hint ve hint_message eklenir. Başarılı yanıtta (validation_errors) bu alanlar üst düzeyde, 422 meta_flow_failed yanıtında ise error içinde yer alır. Flow JSON'unuz değiştirilmez.

#Form mesajı gönderin

{
  "phone_number_id": "1234567890",
  "to": "905550000000",
  "type": "flow",
  "flow": {
    "flow_id": "1234567890123456",
    "flow_token": "crm-basvuru-42",
    "cta": "Formu Aç",
    "body": "Teklif için formu doldurun.",
    "screen": "WELCOME"
  }
}

Serbest mesaj kuralları geçerlidir: 24 saat penceresi kapalıyken form butonlu bir şablon kullanın.

#Şablonla gönderin

Şablonu POST /templates ile FLOW butonuyla oluşturun. Gönderimde buton parametresi:

{ "type": "button", "sub_type": "flow", "index": 0,
  "parameters": [ { "type": "action", "flow_token": "crm-basvuru-42", "flow_action_data": { "ad": "Ahmet" } } ] }

#Yanıtı alın

Müşteri formu gönderdiğinde flow.completed olayı gelir. Aynı mesaj ayrıca message.received (type: interactive) olarak da gelir.

{
  "event": "flow.completed",
  "data": {
    "event_id": "flow_7f3c2a91",
    "phone_number_id": "1234567890",
    "from": "905550000000",
    "flow_token": "crm-basvuru-42",
    "flow_id": "1234567890123456",
    "response": { "flow_token": "crm-basvuru-42", "ad": "Ayşe Yılmaz", "brans": "trafik" },
    "media": [],
    "timestamp": "1791619800"
  }
}

• response, form tasarımınızdaki alan adlarıyla ayrıştırılmış yanıttır.
• Formdaki fotoğraf ve belgeler sunucumuzda indirilir; media[].media_id ile GET /media/{media_id} üzerinden alınır.
• data.event_id aynı yanıt için sabittir; yinelenenleri bununla ayıklayın.
• flow.completed ve flow.status_changed olayları * aboneliğine dahil değildir; açıkça seçin.

#Yönetim

Meta'nın yönetim arayüzünde oluşturduğunuz formlar için {flow_id} uçlarına ?phone_number_id= ekleyin; form hesabınıza bağlanır.

Tüm alanlar: Formlar referansı.