Arama Başlatma — POST /calls

Bir CRM’e yeni lead düştüğünde tek bir POST isteğiyle yapay zeka asistanın o numarayı saniyeler içinde arayabilir — kontak yoksa otomatik açılır, asistan konuşur, görüşme faturalandırılır. Bu uç, Purvisor AI Public API’nin çekirdek yazma aksiyonudur; Zapier ve Make’teki “Arama Başlat” adımı da tam olarak bunu çağırır. Bir düşün: reklamdan gelen lead’i elle aramak yerine, form gönderilir gönderilmez asistanın devreye girer.

İstek

POST /api/v1/calls
X-API-Key: pk_live_...
Content-Type: application/json

Kimlik doğrulama tüm /api/v1/* uçlarında olduğu gibi API anahtarıyla yapılır. Anahtarı nasıl alacağın ve gönderme biçimleri için Kimlik Doğrulama sayfasına bak.

Gövde alanları

İstek gövdesi hem snake_case hem camelCase kabul eder (örn. assistant_id veya assistantId).

Numarayı elle vermek yerine phone_number_id alanını GET /phone-numbers çıktısındaki bir id ile besle — böylece hangi hattan çıktığını kontrol edersin.

curl örneği

curl -X POST https://app.purvisor.ai/api/v1/calls \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+905321234567",
    "assistant_id": "asst_abc123",
    "phone_number_id": "42",
    "first_name": "Ayşe",
    "last_name": "Yılmaz"
  }'

İşleyiş ve kapılar

Uç, kanıtlanmış kampanya makinesini (oda metadata + SIP + agent dispatch + faturalama) yeniden kullanır. Arama gerçekleşmeden önce sırayla şu kapılardan geçilir:

POST /calls
   ↓
Gövde doğrulama (phone + assistant_id, ≥10 hane)   → 400
   ↓
Asistan sahipliği (bu hesaba ait + aktif mi?)       → 404
   ↓
Arayan numara (verilen ait+aktif mi / ilk aktif)    → 404
   ↓
Arama izni: hesap penceresi ∩ yasal pencere         → 422
   ↓
Eşzamanlılık ve hacim tavanı                        → 429 / 503
   ↓
Dakika bakiyesi ≥ 1                                 → 402
   ↓
Kontağı bul (telefonla dedupe) — yoksa oluştur
   ↓
Gizli "zapier-auto" kampanyası (asistan+numara başına)
   ↓
Devam eden arama var mı? (çift arama koruması)       → 409
   ↓
makeCall → arama başlar                              → 502 (başarısızsa)
   ↓
201 { call_id, status: "initiated", ... }

Kontak eşleştirmesi POST /contacts ile aynı mantıkla çalışır: tam numara veya son 10 hane eşleşmesi. Eşleşen kontak yoksa yenisi leadSource="zapier", status="new" ile açılır.

Başarılı yanıt

Arama başlatıldığında HTTP 201 ve şu gövde döner:

{
  "call_id": "1287",
  "status": "initiated",
  "contact_id": "9043",
  "assistant_id": "asst_abc123",
  "from_number": "+904440000",
  "to": "+905321234567"
}

Arama saatleri

Arama iki katmandan geçer ve ikisi de kapıdır:

• Hesap arama penceresi — Ayarlar → Arama penceresi’nde tanımladığın saat ve günler. API’yi çağırmış olman bu pencereyi aşmaz.
• Aranan ülkenin yasal penceresi — numaradan çözülen ülkeye göre uygulanır.

İzin = hesap penceresi ∩ (uygulanıyorsa) yasal pencere. Biri kapalıysa arama başlatılmaz: HTTP 422.

Hangi ülkede hangi pencere?

422 yanıt gövdesi

{
  "error": "Calling is outside your account's calling hours (Settings → Call window). Retry after next_allowed_at.",
  "code": "outside_business_hours",
  "blocked_by": ["account"],
  "country_code": "TR",
  "next_allowed_at": "2026-09-16T06:00:00.000Z"
}

Ne yapmalı?

• next_allowed_at dolu, blocked_by içinde "legal" → yapılacak şey beklemek; Zap’i next_allowed_at’e ertele.
• next_allowed_at dolu, yalnız "account" → ya bekle ya da Ayarlar → Arama penceresi’ni genişlet.
• next_allowed_at null → bu numara bu hesap penceresiyle önümüzdeki haftalarda aranamaz; otomatik yeniden deneme kurma. Pencereyi değiştir. (Yaz saati geçişleri kesişimi haftalar sonra açabilir; pencere değişmeden tekrar denemek günlerce aynı 422’yi döndürür.)
• code: "callee_region_unknown" → yeniden deneme yok, pencere değişikliği de çözmez. Numarayı düzelt.

Kesişim yok örneği (TR hesap 09:00–18:00 + Los Angeles numarası — saat 12:00’de de 20:00’de de aynı gövde döner):

{
  "error": "Your account's calling hours do not overlap the legally permitted hours for the destination country in the coming weeks, so this number cannot be called with the current call window. Retrying will not help; widen the call window (Settings → Call window).",
  "code": "outside_legal_call_window",
  "blocked_by": ["account", "legal"],
  "country_code": "US",
  "next_allowed_at": null
}

Bölgesi çözülemeyen numara örneği:

{
  "error": "The destination number's country or time zone could not be determined, so its legal calling hours cannot be verified and this number will not be called. Retrying will not help; check the phone number (international format, e.g. +49…).",
  "code": "callee_region_unknown",
  "blocked_by": ["legal"],
  "country_code": "NG",
  "next_allowed_at": null
}

status: "initiated" “telefon çaldı/açıldı” demek değildir; sadece aramanın başarıyla kuyruğa alındığını bildirir. Görüşmenin sonucunu (süre, özet, duygu) öğrenmek için call.completed webhook’una abone ol — bkz. Webhook’lar.

Eşzamanlılık ve hacim tavanları

Aynı anda kaç aramanın açık olabileceği planına bağlıdır; ayrıca hesabına saatlik ve günlük toplam arama tavanı koyabilirsin. İstek bu kapıya takılırsa arama başlatılmaz ve bakiyenden dakika düşülmez — kapı bakiye rezervinden önce çalışır.

{
  "error": "Concurrent or volume call limit reached",
  "code": "concurrency_limit",
  "scope": "tenant",
  "active": 10,
  "limit": 10
}

429 ile 503 aynı şey değil:

• 429 gerçek bir tavandır. active ve limit ile birlikte gelir; hızını düşür, kuyruğunu yay. Eşzamanlılık tavanı planına göredir (Planlar); saatlik/günlük tavanlar senin kendi koyduğun frendir ve tanımlı değilse uygulanmaz.
• 503 geçicidir. Tavan dolduğu için değil, kapı o an doğrulanamadığı için reddedilir (arka plandaki sayaç okunamamıştır). Retry-After kadar bekleyip aynı isteği tekrar dene — bir şeyi düzeltmen gerekmiyor. Kapı doğrulanamadan arama açılmaz; çünkü açık geçilseydi tavan hiç uygulanmamış olurdu.

Hata kodları

Tüm hata kodlarının ortak referansı için Limitler ve Hatalar sayfasına bak.

Sorun giderme

İlgili