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
   ↓
Aranan ülkenin YASAL arama penceresi açık mı?       → 422
   ↓
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, aranan kişinin ülkesindeki yasal arama penceresi dışındaysa başlatılmaz: HTTP 422 ve code: "outside_legal_call_window" döner. Yanıttaki next_allowed_at (ISO-8601), pencerenin yeniden açılacağı ilk anı verir — Zap’ini o zamana kadar geciktirmek için doğrudan kullanabilirsin.

{
  "error": "Calling is outside the legally permitted hours for the destination country. Retry after next_allowed_at.",
  "code": "outside_legal_call_window",
  "country_code": "TR",
  "next_allowed_at": "2026-08-19T06:00:00.000Z"
}

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.

Hata kodları

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

Sorun giderme

İlgili