Wapix

Entegrasyonlar & API

Nedir

Wapix ve diğer yazılımlarınızın birlikte çalışmasının iki yolu:

  • Webhook'lar. Wapix, bir şey olduğunda başka bir araca haber verir. Daha basit bir dilde açıklama için Webhook'lar sayfasına bakın.
  • REST API. Başka bir araç, Wapix'den bir şey yapmasını ister, örneğin bir kişi eklemek veya bir mesaj göndermek.

Bu sayfa her ikisi için de teknik bir referanstır. Bazı bölümleri bir geliştirici veya n8n ve Zapier gibi araçlarla rahat olan biri için yazılmıştır.

Çözdüğü sorun

Müşteri verilerinizin iki kez yazılması gerekmemelidir. Bir web sitesi formu, bir çevrimiçi mağaza, bir CRM ve Wapix her biri resmin bir parçasını tutar. Bunları bağlamak demektir ki:

  • Web sitenizde bir form dolduran bir müşteri, Wapix'e eklenir ve kimse bir şey yapmadan bir WhatsApp mesajı alır;
  • Mağazanızda verilen bir sipariş, "siparişiniz gönderildi" mesajı gönderir;
  • Wapix'den gelen her potansiyel müşteri, elektronik tablonuza veya CRM'inize düşer.

Nasıl çalışır

  • Webhook'lar için, Webhook'lar altında bir uç nokta ekler ve olaylarını seçersiniz. Wapix, her gerçekleştiğinde o adrese bir mesaj gönderir.
  • API için, yan menüde Geliştirici, API tokenları altında bir erişim tokenı oluşturursunuz. Token, başka bir programın çalışma alanınız adına hareket edebileceğini kanıtlamak için kullandığı uzun bir şifredir. Her tokenın ne yapabileceğine siz karar verirsiniz.

API tokenı oluşturma

  1. Yan menüde Geliştirici, API tokenları kısmına gidin. Planınız API erişimini içermelidir.
  2. Tokenın ne için olduğunu hatırlamak için bir isim girin, örneğin "Zapier".
  3. Ne yapabileceğini seçin:
    • Her şey için Tam erişim kutusunu işaretleyin, daha sonra eklenen her şeyi de dahil edin. Bunu yalnızca tamamen güvendiğiniz bir program için kullanın.
    • Ya da yalnızca o aracın ihtiyaç duyduğu yetkileri işaretleyin. Aşağıdaki listeye bakın.
  4. İsteğe bağlı olarak bir son tarih belirleyin (gelecekte bir tarih, en fazla beş yıl). O tarihten sonra token çalışmayı durdurur ve net bir mesajla 401 yanıtı verir.
  5. Oluşturun ve tokenı hemen kopyalayın. Sadece bir kez gösterilir.

Eğer bir token kaybolursa veya sızmış olabileceğinden şüpheleniyorsanız, İptal et butonuna tıklayın ve yenisini oluşturun. İptal edilen bir token hemen çalışmayı durdurur. Token listesi, her tokenın son tarihini ve en son ne zaman kullanıldığını gösterir.

Yetkiler (bir tokenın yapabileceği şeyler)

Yetki Programın…
messages:send Metin ve şablon göndermesine izin verir.
contacts:read / contacts:write Kişileri, segmentleri ve etiketleri okuma / oluşturma, değiştirme, silme ve etiketleme.
conversations:read / conversations:write Sohbetleri ve mesajları okuma / bir sohbetin durumunu ayarlama veya kapatma.
campaigns:read / campaigns:write Kampanyaları ve alıcılarını okuma / oluşturma, başlatma, duraklatma ve yeniden başlatma.
templates:read / templates:write WhatsApp şablonlarını okuma / taslak oluşturma ve bunları Meta'ya gönderme.
automations:trigger Otomasyonları listeleme ve bir kişi için başlatma.
webhooks:write Webhook uç noktalarını yönetme.
ai:read / ai:write Asistanları ve bilgi tabanlarını listeleme / bilgi ekleme ve bir asistandan soru sorma.
deals:read / deals:write Satış hunilerini ve fırsatları okuma / oluşturma ve taşıma.
bookings:read / bookings:write Rezervasyon yapılabilir hizmetleri, boş zamanları ve rezervasyonları okuma / oluşturma ve iptal etme.
analytics:read Özet rakamları okuma.

Bir tokenı bir şifre gibi düşünün. Onu elinde bulunduran herkes, tokenın izin verdiği ölçüde sizin adınıza mesaj gönderebilir veya kişilerinizi okuyabilir. Asla kamuya açık bir web sayfasına koymayın veya sohbetlerde paylaşmayın.

Bu sayfanın geri kalanı tam formatları verir.

1. Webhook'lar

Webhook'lar altında bir uç nokta ekleyin (bkz. Webhook'lar). Her teslimat, her olay için aynı zarfla JSON'un bir HTTP POST'udur:

{
  "event": "message.received",
  "data": { },
  "timestamp": "2026-10-05T10:00:00+00:00"
}

Uç nokta sayfasında Test gönder ile gönderilen bir mesajda ayrıca "test": true bulunur. Gerçek mesajlarda bu asla olmaz. 10 saniye içinde herhangi bir 2xx kodu ile yanıt verin; başka bir şey denendiğinde 3 kez daha tekrar edilir.

İmzanın doğrulanması

Her teslimat X-Threadline-Signature-256: sha256=<hex> taşır. Bu, ham istek gövdesinin HMAC-SHA256'sidir ve uç noktanızın imza sırrı ile anahtarlanmıştır. Kendiniz hesaplayın ve sabit bir zamanda karşılaştırın; eşleşmiyorsa isteği reddedin.

$expected = 'sha256='.hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_THREADLINE_SIGNATURE_256'] ?? '');

Olaylar ve data'ları

message.received: bir müşteri mesaj gönderdi.

{
  "message": { "id": 912, "conversation_id": 55, "text": "Merhaba, bu stokta mı?", "has_image": false, "received_at": "2026-10-05T10:00:00+00:00" },
  "contact": { "id": 7, "name": "Ana Silva", "phone": "15551234567", "email": null, "channel_id": 2, "channel_type": "whatsapp", "opted_in": false }
}

contact.created: { "contact": { …yukarıdaki gibi… } }

lead_form.submitted:

{
  "lead_form": { "id": 3, "title": "Demo rezervasyonu" },
  "contact": { "id": 7, "name": "Ana Silva", "phone": "15551234567", "email": "ana@example.com", "channel_id": 2, "channel_type": "whatsapp", "opted_in": false },
  "conversation_id": 55,
  "answers": [ { "label": "Adınız", "value": "Ana" }, { "label": "E-posta", "value": "ana@example.com" } ],
  "completed_at": "2026-10-05T10:05:00+00:00"
}

conversation.escalated: { "conversation_id": 55, "reason": "anahtar kelime" }. Sebep fallback_phrase, human_requested, keyword veya repeated_question'dan biridir.

conversation.closed: { "conversation_id": 55 }

answer.fallback: { "conversation_id": 55, "kb_id": 4, "question": "Nepal'e gönderim yapıyor musunuz?" }

deal.created, deal.stage_changed, deal.won, deal.lost:

{
  "deal": {
    "id": 31, "title": "Web sitesi yeniden tasarımı", "value": 1500, "currency": "USD", "probability": 50,
    "stage": "Teklif", "stage_kind": "open", "pipeline": "Satış Hunisi",
    "contact_id": 7, "conversation_id": 55, "owner_user_id": 2,
    "expected_close_on": "2026-11-01", "source_channel_type": "whatsapp",
    "won_at": null, "lost_at": null, "lost_reason": null
  },
  "from_stage": "Nitelikli"
}

from_stage yalnızca aşama değişikliği olaylarında bulunur.

booking.created, booking.cancelled, booking.completed:

{
  "booking": {
    "id": 18, "status": "onaylı", "source": "sohbet",
    "service": { "id": 3, "name": "Danışmanlık" },
    "calendar": { "id": 1, "name": "Ana takvim", "timezone": "America/New_York" },
    "contact_id": 7, "conversation_id": 55,
    "starts_at": "2026-12-02T15:00:00+00:00", "ends_at": "2026-12-02T15:30:00+00:00", "local_start": "2026-12-02 10:00",
    "customer_note": "İlk ziyaret", "notes": null, "cancel_reason": null, "meeting_url": null
  }
}

status onaylı, iptal edildi, tamamlandı veya gözükmedi olabilir. source sohbet, ai, agent, public veya api olabilir. Zamanlar UTC'dir; local_start takvimin kendi zaman dilimindedir.

2. REST API

Her istekte tokenınızı gönderin:

Authorization: Bearer kd_…
Accept: application/json

Her şey /api/v1 altında. Bir token bir çalışma alanına aittir ve yalnızca o çalışma alanının verilerini görebilir. Her token dakikada 60 istekle sınırlıdır; bu sınırı aştığınızda 429 alırsınız. Yanlış, iptal edilmiş veya süresi dolmuş bir token 401 alır; gerekli yetkiye sahip olmayan bir token veya API erişimi olmayan bir plan 403 alır.

API referans sayfası

Her uç noktayı bulmak için bu sayfaya ihtiyacınız yok. Yan menüde Geliştirici, API referansı kısmı, tüm 43 uç noktayı parametreleriyle birlikte listeler, kopyalamaya hazır bir curl örneği ve bir örnek yanıt ile birlikte bir arama kutusu içerir. Ayrıca hızlı başlangıç, hata ve hız sınırlama notları, webhook imzalarını kontrol etme (bir Node örneği ile) ve tüm API'yi OpenAPI 3 dosyası olarak indirmenizi sağlar; bu dosyayı Postman veya kod üreticilerine yükleyebilirsiniz.

API'nin kapsadığı alanlar

Alan Örnekler
Hesap GET /me, /channels, /analytics/summary
Kişiler liste, oluştur, göster, güncelle, sil, etiket ekle ve kaldır, /tags, /segments
Sohbetler liste, göster, mesajları oku, durumu ayarla veya kapat
Mesajlar POST /messages: bir metin gönder, veya onaylı bir şablon
Şablonlar liste, göster, taslak oluştur, Meta'ya gönder
Kampanyalar liste, göster, alıcılar, oluştur (ve isteğe bağlı olarak başlat), başlat, duraklat, yeniden başlat
Webhook'lar liste, oluştur (gizli bir kez gösterilir), güncelle, sil (URL'ler kamuya açık olmalıdır)
Asistanlar ve bilgi liste, metin ekle, bir web sayfası veya sorular ve cevaplar ekle, bir asistandan soru sor
Otomasyonlar liste, bir kişi için ekstra veri ile başlat
Fırsatlar satış hunilerini ve fırsatları listele, açık bir aşamada oluştur, taşı

API'de bulunmayanlar: bir sohbeti silmek, bir kişi olarak yanıt vermek ve bir sohbeti kimin yöneteceğini değiştirmek.

Listeler sayfalandırılmıştır: yanıt data, links ve meta içerir.

# Sizinle iletişim kurmayı kabul eden bir kişiyi etiket ile ekleyin
curl -X POST https://your-site.com/api/v1/contacts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"channel_id": 2, "phone": "+1 555 123 4567", "name": "Ana", "opted_in": true, "tags": ["website-lead"]}'

opted_in, kişinin pazarlama mesajlarını kabul ettiğinizi belirten ifadedir. API bunu ayarlayabilir ama asla geri alamaz.

# Bir metin gönder (kuyrukta; 202 ile yanıt verir)
curl -X POST https://your-site.com/api/v1/messages \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"contact_id": 7, "text": "Siparişiniz gönderildi!"}'

# Onaylı bir şablon ile bir sohbet başlat (hemen gönderilir; 201 ile yanıt verir)
curl -X POST https://your-site.com/api/v1/messages \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"channel_id": 2, "phone": "15551234567", "template_id": 12}'

24 saat kuralı geçerlidir: WhatsApp, Instagram ve Messenger'da bir metin yalnızca kişinin son mesajından itibaren 24 saat içinde gönderilir, aksi takdirde 422 yanıtı alırsınız ve bir şablon kullanmanız gerektiği belirtilir. Bir şablon, onaylı bir şablon ve opt-in olmuş bir kişi gerektirir.

3. Tarif: yeni potansiyel müşteri → Google Sheets, n8n ile

  1. n8n'de bir Webhook düğümü ekleyin. Yöntemi POST olarak ayarlayın ve üretim URL'sini kopyalayın.
  2. Wapix'de, Webhook'lar → Uç nokta ekle, o URL'yi yapıştırın ve lead_form.submitted olayına abone olun. İmza sırrını kopyalayın.
  3. Kanalınıza bir potansiyel müşteri formu ekleyin (bkz. Potansiyel Müşteri Formları) ve n8n'in bir örnek alabilmesi için bir kez kendiniz doldurun.
  4. n8n'de, webhook'un ardından bir Google Sheets düğümü ekleyin, Satır ekle olarak ayarlayın ve {{ $json.body.data.contact.name }}, {{ $json.body.data.contact.phone }} ve {{ $json.body.data.answers[1].value }}'yi sütunlara eşleyin.
  5. İsteğe bağlı: verileri güvenilir bulmadan önce imzayı kontrol etmek için aralarına bir Kod düğümü ekleyin (bölüm 1).
  6. İş akışını etkinleştirin. Artık tamamlanan her form bir satır ekler.

4. Tarif: bir formdan WhatsApp mesajı gönder, Zapier ile

  1. Wapix'de, Kişileri oluştur ve Mesaj gönder yetkileri ile bir token oluşturun ve WhatsApp kanalınızın kimliğini ve onaylı bir şablonun kimliğini bulun.
  2. Zapier'de, tetikleyiciyi form aracınızın Yeni gönderim olarak ayarlayın.
  3. Bir Webhooks by Zapier eylemi ekleyin, olay Özel İstek, yöntem POST, URL https://your-site.com/api/v1/contacts, başlık Authorization: Bearer <token>, ve formun adı ve telefonu, "channel_id" ve "opted_in": true içeren bir JSON gövdesi ekleyin eğer form onay talep ediyorsa.
  4. /api/v1/messages için ikinci bir Özel İstek ekleyin {"channel_id": 2, "phone": "<telefon>", "template_id": 12} ile.
  5. Test edin ve Zap'i yayınlayın.

5. Diğer giriş yolları

  • Otomasyon webhook tetikleyicisi. Bir otomasyon, sisteminiz özel bir adresi aradığında başlayabilir. API tokenı gerekmez; gizli adresin içindedir.
  • Çevrimiçi mağazalar kendi webhook'larını Wapix'e gönderir. Bakınız Çevrimiçi Mağazalar.

6. Meta potansiyel müşteri reklamları

Facebook ve Instagram'dan gelen potansiyel müşteri reklamları sizin için otomatik olarak kişiler oluşturabilir. Tam kurulum, Meta'nın onay adımları dahil olmak üzere kendi sayfasında bulunmaktadır: Meta Potansiyel Müşteri Reklamları.

7. WhatsApp bağlantıları

Sizinle bir sohbet açan kısa bağlantılar ve QR kodları ve her müşteriyi hangi reklamın getirdiğini gösterir. Bakınız WhatsApp Bağlantıları.

Sıkça Sorulan Sorular

401 alıyorum. Token yanlış veya iptal edildi. Yeni bir tane oluşturun.

403 alıyorum. Token çalışıyor ama bunu yapmasına izin verilmiyor. İhtiyacınız olan yetkiye sahip bir token oluşturun.

429 alıyorum. O token ile dakikada 60'tan fazla istek gönderdiniz. Biraz bekleyin ve yavaşlayın.

Mesaj gönderirken 422 alıyorum. O kişi için 24 saatlik pencere kapandı. Bunun yerine onaylı bir şablon gönderin.

401 alıyorum ve mesaj süreden bahsediyor. Tokenın son tarihi geçmiş. Yeni bir tane oluşturun.

Ayarlar'da API erişimi yok. Planınız API erişimini içermiyor. Bakınız Planlar & Faturalama.