İçeriğe geç
e-Temsilci

REST API · v1

Kendi yazılımınızdan müşterinizi arattırın.

Aboneliği sona eren müşteriniz, ödenmemiş faturası olan müşteriniz ya da randevusunu kaçıran danışanınız: sisteminiz tek bir istekle e-Temsilci asistanına "bu numarayı, bu nedenle, bu bilgilerle ara" der. Asistan kampanyanızın sesiyle ve kurallarıyla arar, sonucu size webhook ile bildirir.

API adresi

https://panel.etemsilci.com/api/v1
Hızlı başlangıç OpenAPI 3.1 dosyası

  • Arama talebi

    Numara, neden, asistana özel talimat ve değişkenler: tek POST /call-requests.

  • Uyum hazır

    İYS, aranmayacaklar listesi, arama saatleri ve deneme sınırları her aramadan önce kontrol edilir.

  • Sonuç size gelir

    Görüşme bitince call_request.completed webhook'u; özet, sonuç ve sonraki adımla.

Geliştiriciler

API anahtarınızı alın.

Ücretsiz hesap açın; Entegrasyonlar → API'den anahtarınızı oluşturup ilk arama talebinizi gönderin.

Şimdi başla

Kredi kartı gerekmez

Giriş

e-Temsilci API'si JSON konuşan bir REST API'dir. Her istek HTTPS üzerinden, firmanıza ait bir API anahtarıyla yapılır; bir anahtar yalnızca kendi firmasının verisini görür.

En sık kullanım arama talebidir: sisteminizde bir olay olduğunda (abonelik sona erdi, fatura ödenmedi, randevu kaçtı) e-Temsilci'ye kimin, hangi kampanyanın asistanıyla, ne zaman ve hangi bilgilerle aranacağını söylersiniz. Arama, kampanyanın ses, kişilik, arama saatleri ve tekrar deneme kurallarıyla yapılır; sonucu webhook ile ya da sorgulayarak alırsınız.

Kişileri kampanya listelerine eklemek, görüşme sonuçlarını çekmek ve kampanyaları listelemek için de aynı API'yi kullanırsınız.

Biçim
İstek ve cevaplar JSON (Content-Type: application/json), karakter kodlaması UTF-8.
Zamanlar
ISO 8601. Cevaplardaki zamanlar UTC'dir (2026-10-07T07:30:00+00:00). İsteklerde saat dilimi yazmazsanız firmanızın saat dilimi (varsayılan Europe/Istanbul) kullanılır.
Telefon
0532 123 45 67, +905321234567 veya 5321234567 biçimleri kabul edilir; cevaplarda hep E.164 (+905321234567). Yurt dışı numaralar + veya 00 ile yazılır.
Kimlikler
Kampanya ve kişi kimlikleri sayıdır; arama talebi ve görüşme kimlikleri 26 karakterlik metindir (ULID).
Sürüm
Adres /api/v1 ile başlar. Mevcut alanlar kaldırılmaz ve anlamı değişmez; yeni alanlar eklenebilir, kodunuz bilmediği alanları yok saymalıdır.

Hızlı başlangıç

Beş adımda ilk aramanızı API'den başlatın.

  1. 01

    Kampanyayı hazırlayın

    Panelde Kampanyalar → Yeni kampanya ile asistanın adını, sesini, açılış cümlesini, bilgi bankasını ve arama saatlerini ayarlayın, sonra kampanyayı Başlat'ın. Arama talepleri için kampanyaya kişi listesi yüklemeniz gerekmez. Hesabınızda en az bir dakikalık görüşmeye yetecek kredi olduğundan emin olun (Ayarlar → Abonelik ve kredi).

  2. 02

    API anahtarı oluşturun

    Entegrasyonlar → API → Yeni API anahtarı (Sahip ve Yönetici rolleri). Anahtar et_live_ ile başlar ve yalnızca bir kez gösterilir; sunucunuzda bir ortam değişkeninde saklayın, örneğin ETEMSILCI_API_KEY.

  3. 03

    Kampanya kimliğini bulun

    GET /campaigns kampanyalarınızı kimlikleriyle listeler.

  4. 04

    Arama talebi gönderin

    POST /call-requests ile numarayı, kampanyayı, aramanın nedenini ve asistanın kullanacağı bilgileri gönderin. Arama saatleri içindeyseniz arama genellikle bir dakika içinde başlar.

  5. 05

    Sonucu alın

    Entegrasyonlar → Webhook'ta "Arama talebi sonuçlandı" olayını seçin; görüşme bitince adresinize call_request.completed gelir. İsterseniz GET /call-requests/{id} ile durumu sorgulayın.

curl -X POST "https://panel.etemsilci.com/api/v1/call-requests" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-FTR-2026-1042" \
  -d '{
    "campaign_id": 12,
    "phone": "05321234567",
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "customer_type": "individual",
    "iys_status": "allowed",
    "consent_source": "Abonelik sözleşmesi, 2025-03-12",
    "reason": "Fatura hatırlatma",
    "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
    "variables": {
        "fatura_no": "FTR-2026-1042",
        "fatura_tutari": "1.250,00 TL",
        "son_odeme_tarihi": "30 Eylül 2026"
    },
    "scheduled_at": "2026-10-07T10:30:00+03:00",
    "external_id": "FTR-2026-1042"
}'

Kimlik doğrulama

Her isteğe API anahtarınızı Authorization başlığında Bearer olarak ekleyin. Anahtarı olmayan, hatalı ya da iptal edilmiş istekler 401 unauthenticated döner.

Anahtarlar firmanıza aittir ve firmanızın tüm kişilerine, kampanyalarına ve görüşmelerine erişir. Anahtarı tarayıcıda, mobil uygulamada ya da herkese açık bir depoda kullanmayın; yalnızca sunucunuzdan istek atın.

Her bağlantı için ayrı anahtar oluşturun (ör. "Muhasebe sistemi", "CRM"). Panelde her anahtarın son kullanım zamanı görünür; kullanılmayanı İptal et ile kapatın, iptal hemen geçerli olur. Firmanın hesabı askıya alınırsa tüm istekler 403 tenant_suspended döner.

HTTP 
Authorization: Bearer et_live_…

Hatalar

Başarılı istekler 2xx döner. Hatalarda gövde her zaman aynı biçimdedir; programınız error.code değerine göre karar vermeli, message yalnızca insanlar içindir ve değişebilir.

422 Cevap 
{
    "error": {
        "code": "validation_failed",
        "message": "Geçerli bir telefon numarası girin.",
        "fields": {
            "phone": [
                "Geçerli bir telefon numarası girin."
            ]
        }
    }
}

Alan hatalarında (validation_failed) her alanın mesajları fields içinde gelir.

  • 401 unauthenticated

    API anahtarı yok, hatalı ya da iptal edilmiş.

    Authorization: Bearer et_live_… başlığını ve anahtarın panelde etkin olduğunu kontrol edin.

  • 403 tenant_suspended

    Firmanın hesabı askıya alınmış.

    Destek ekibimizle iletişime geçin.

  • 404 not_found

    Kayıt bulunamadı. Başka bir firmanın kaydı da 404 döner.

    Kimliği kontrol edin.

  • 409 contact_busy

    Kişi bu kampanyada şu anda aranıyor (arama kuyrukta ya da görüşme sürüyor).

    Görüşme bitince (genellikle birkaç dakika) yeniden deneyin.

  • 409 request_not_cancellable

    Talep iptal edilemez: araması başlamış ya da talep zaten sonuçlanmış.

    Talebin durumunu GET /call-requests/{id} ile okuyun.

  • 409 request_in_progress

    Aynı Idempotency-Key (ya da aynı external_id) ile gönderilen ilk istek hâlâ işleniyor.

    Birkaç saniye bekleyip aynı isteği tekrarlayın.

  • 422 validation_failed

    Bir veya daha fazla alan geçersiz; ayrıntılar fields içinde.

    Alanları düzeltip yeniden gönderin. Aynı isteği değiştirmeden tekrarlamayın.

  • 422 campaign_not_ready

    Kampanya taslak ya da tamamlanmış; arama talebi yalnızca aktif veya duraklatılmış kampanyaya verilebilir.

    Kampanyayı panelde başlatın ya da başka bir kampanya seçin.

  • 422 idempotency_key_reused

    Bu Idempotency-Key son 24 saatte başka bir istek gövdesiyle kullanılmış.

    Her farklı istek için yeni bir anahtar üretin.

  • 429 rate_limited

    Anahtar başına dakikada 120 istek sınırı aşıldı.

    Retry-After başlığındaki saniye kadar bekleyin.

5xx cevapları ve zaman aşımları geçicidir: aynı isteği, varsa aynı Idempotency-Key ile, artan aralıklarla yeniden gönderin.

Hız sınırı

Her API anahtarı dakikada en fazla 120 istek gönderebilir. Sınır aşılırsa 429 rate_limited döner; Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler.

Toplu işlerde (örneğin günün ödenmemiş faturaları) istekleri sıraya koyup dakikada 120'nin altında gönderin. Aramaların kendisi zaten kampanyanın eşzamanlı arama sınırına göre sırayla yapılır; talepleri hızlı göndermek aramaları hızlandırmaz.

Tekrarlanan istekler

Ağ hatasında aynı isteği güvenle tekrarlayabilmeniz için POST isteklerine bir Idempotency-Key başlığı ekleyin (en fazla 255 karakter, boşluksuz; örneğin bir UUID ya da fatura-1042-hatirlatma).

Aynı API anahtarı ve aynı anahtarla gelen ikinci istek 24 saat boyunca yeniden işlenmez: ilk cevabın aynısı döner ve Idempotent-Replayed: true başlığı eklenir. Aynı anahtarı farklı bir gövdeyle kullanırsanız 422 idempotency_key_reused, ilk istek hâlâ işleniyorsa 409 request_in_progress döner. 5xx, 409 ve 429 cevapları saklanmaz; bunları aynı anahtarla tekrar deneyebilirsiniz.

Arama taleplerinde ayrıca external_id kullanın: aynı external_id ile açık (sırada, aranıyor ya da yeniden denenecek) bir talep varsa yenisi oluşturulmaz, mevcut talep 200 ile döner. Böylece aynı fatura için iki ayrı arama yapılmaz. Talep sonuçlandıktan sonra aynı external_id ile yeni talep açabilirsiniz.

Uç noktalar

Arama talepleri

Bir kişiyi bir kampanyanın asistanıyla, belirli bir neden ve bilgilerle arattırın. Talep kişiyi kampanyanın listesine "yeni" olarak koyar (önceki denemeler sıfırlanır); arama, kampanyanın ses, arama saatleri, eşzamanlı arama ve tekrar deneme kurallarıyla yapılır. Aynı kişi için aynı kampanyada açık bir talep varsa yeni talep onun yerini alır (eskisi cancelled, superseded).

Talebin durumları

Talep, kampanyanın arama sırasında ilerler. Açık durumlar queued, calling ve retrying; sonuç durumları completed, failed, cancelled ve blocked. Sonuç durumuna geçişte bir kez call_request.completed webhook'u gönderilir.

queued Sırada. Zamanı, arama saatleri ya da boş hat bekleniyor; next_attempt_at ve waiting_reason nedenini gösterir.
calling Aranıyor: arama kuyruğa alındı, telefon çalıyor ya da görüşme sürüyor.
retrying Kişiye ulaşılamadı (açmadı, meşgul, telesekreter, teknik hata) ya da kişi tekrar aranmak istedi; kampanyanın tekrar deneme kurallarına göre yeniden aranacak.
completed Kişi açtı ve görüşme yapıldı. Sonuç outcome, özet last_call.summary alanında.
failed Kampanyanın izin verdiği tüm denemelerde ulaşılamadı (failure_reason: not_reached).
cancelled Arama yapılmadan kapandı: API ile iptal, yerine yeni talep geldi, kişi kampanya listesinden çıkarıldı ya da kampanya tamamlandı (failure_reason).
blocked Uyum kuralı nedeniyle aranmadı: aranmayacaklar listesi, İYS reddi ya da İYS izni yok (blocked_reason).

Tekrar denemeler

Ulaşılamayan kişi, kampanyanın "En fazla deneme" sayısına kadar yeniden aranır. Bekleme süreleri kampanyada ayarlanır; varsayılanlar: açmadı 120 dk, meşgul 30 dk, teknik hata 60 dk, telesekreter 240 dk. Kişi bir tarih vererek tekrar aranmak isterse o zamanda aranır. Aynı kişi aynı gün en fazla 2 kez aranır.

Asistan bu bilgileri nasıl kullanır?

  • reason, instructions ve variables yalnızca bu talebin görüşmelerinde asistana verilir; kampanyanın açılış cümlesi, kayıt ve yapay zekâ bildirimi, bilgi bankası ve kuralları aynen geçerlidir.
  • Asistan bilgileri doğal bir konuşmada kullanır, tutar ve tarihleri Türkçe okur. Değerleri müşteriye söylenecek biçimde yazın ("1.250,00 TL", "10 Ekim 2026").
  • Asistana kart numarası, şifre veya kimlik numarası gibi bilgiler vermeyin ve bunları istemesini söylemeyin. Görüşmede ödeme almak yerine ödeme kanalınızı (uygulama, web sitesi, şube) tarif ettirin.
POST /api/v1/call-requests

Arama talebi oluştur

Kişiyi telefonuna göre bulur ya da oluşturur (gönderdiğiniz kişi alanları güncellenir), kampanyanın listesine koyar ve scheduled_at zamanında (boşsa hemen) aranmak üzere sıraya alır. Yeni talep 201, aynı external_id ile açık bir talep varsa o talep 200 döner. Kişi aranmayacaklar listesindeyse talep 201 ile ama blocked durumunda oluşturulur ve aranmaz.

Başlıklar

Idempotency-Key string
Ağ hatasında isteği güvenle tekrarlamak için benzersiz bir anahtar (en fazla 255 karakter). Bkz. Tekrarlanan istekler.

Gövde (JSON)

campaign_id integer zorunlu
Aramayı yapacak kampanya (GET /campaigns). Aktif veya duraklatılmış olmalı; asistan, ses, arama saatleri ve tekrar deneme kuralları bu kampanyadan gelir.
phone string zorunlu
Aranacak numara. 0532…, +90532… veya 532… biçiminde; yurt dışı numaralar + veya 00 ile.
first_name string
Ad (en fazla 120 karakter). Asistan kişiye adıyla hitap eder.
last_name string
Soyad (en fazla 120 karakter).
company string
Firma adı (en fazla 255 karakter).
email string · email
E-posta adresi. Asistan dosya gönderirken kullanabilir.
customer_type string
Müşteri tipi; İYS kuralını belirler. Yeni kişide varsayılan individual. Değerler: individual merchant
iys_status string
Kişinin İYS'deki arama izni. İYS entegrasyonunuz bağlıysa izin İYS'den sorgulanır; değilse bu değer kullanılır. Yeni kişide varsayılan unchecked (aranamaz). Bkz. Uyum. Değerler: unchecked allowed denied not_found
consent_source string
İzni nereden aldığınız (en fazla 120 karakter), örneğin "Abonelik sözleşmesi, 2025-03-12".
about string
Kişi hakkında kalıcı bilgi (en fazla 2000 karakter); asistan bu kişiyle her görüşmede kullanır.
custom_fields object
Kişinin özel alanları: ad → metin veya sayı (en fazla 30 alan, değer en fazla 500 karakter). Mevcut alanlarla birleştirilir.
reason string
Aramanın nedeni, kısa (en fazla 200 karakter), örneğin "Fatura hatırlatma". Asistan görüşmeyi bu amaca göre yürütür.
instructions string
Yalnızca bu talebin görüşmelerinde asistana verilecek ek talimat (en fazla 2000 karakter). Kampanyanın talimatlarına eklenir, onları değiştirmez.
variables object
Asistanın görüşmede kullanacağı bilgiler: ad → değer (en fazla 30). Adlar küçük harfle başlar, yalnızca a-z, 0-9 ve _ içerir (en fazla 40 karakter); değerler metin veya sayıdır (en fazla 500 karakter) ve metin olarak saklanır. Değerleri müşteriye söylenecek biçimde yazın: "1.250,00 TL", "10 Ekim".
scheduled_at string · date-time
En erken arama zamanı (ISO 8601), en fazla 30 gün sonrası. Boş ya da geçmiş bir zaman "hemen" demektir. Zaman arama saatleri dışındaysa arama pencerenin açılışına kayar.
external_id string
Sisteminizdeki referans (en fazla 100 karakter), örneğin fatura veya müşteri numarası. Aynı external_id ile açık bir talep varsa yenisi oluşturulmaz. 
curl -X POST "https://panel.etemsilci.com/api/v1/call-requests" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-FTR-2026-1042" \
  -d '{
    "campaign_id": 12,
    "phone": "05321234567",
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "customer_type": "individual",
    "iys_status": "allowed",
    "consent_source": "Abonelik sözleşmesi, 2025-03-12",
    "reason": "Fatura hatırlatma",
    "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
    "variables": {
        "fatura_no": "FTR-2026-1042",
        "fatura_tutari": "1.250,00 TL",
        "son_odeme_tarihi": "30 Eylül 2026"
    },
    "scheduled_at": "2026-10-07T10:30:00+03:00",
    "external_id": "FTR-2026-1042"
}'
201 Cevap 
{
    "data": {
        "id": "01k6zq3m8v2c4x7b9n5t1r0wyd",
        "status": "queued",
        "campaign": {
            "id": 12,
            "name": "Fatura hatırlatma"
        },
        "contact": {
            "id": 4821,
            "phone": "+905321234567",
            "name": "Ayşe Yılmaz"
        },
        "external_id": "FTR-2026-1042",
        "reason": "Fatura hatırlatma",
        "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
        "variables": {
            "fatura_no": "FTR-2026-1042",
            "fatura_tutari": "1.250,00 TL",
            "son_odeme_tarihi": "30 Eylül 2026"
        },
        "scheduled_at": "2026-10-07T07:30:00+00:00",
        "attempts": 0,
        "next_attempt_at": "2026-10-07T07:30:00+00:00",
        "waiting_reason": null,
        "blocked_reason": null,
        "failure_reason": null,
        "outcome": null,
        "outcome_label": null,
        "last_call": null,
        "created_at": "2026-10-06T19:02:11+00:00",
        "updated_at": "2026-10-06T19:02:11+00:00",
        "completed_at": null
    }
}
GET /api/v1/call-requests

Arama taleplerini listele

Son değişen önce. Düzenli çekimde son aldığınız talebin updated_at değerini bir sonraki istekte since olarak kullanın; webhook kullanıyorsanız çekime gerek yoktur.

Sorgu parametreleri

status string
Yalnızca bu durumdaki talepler. Değerler: queued calling retrying completed failed cancelled blocked
external_id string
Yalnızca bu external_id ile açılmış talepler.
campaign_id integer
Yalnızca bu kampanyanın kayıtları.
since string · date-time
Bu zamandan sonra değişen (updated_at) talepler.
limit integer
En fazla kaç kayıt dönsün (1–100). Varsayılan 25. Varsayılan: 25

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/call-requests?status=completed&since=2026-10-07T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": "01k6zq3m8v2c4x7b9n5t1r0wyd",
            "status": "completed",
            "campaign": {
                "id": 12,
                "name": "Fatura hatırlatma"
            },
            "contact": {
                "id": 4821,
                "phone": "+905321234567",
                "name": "Ayşe Yılmaz"
            },
            "external_id": "FTR-2026-1042",
            "reason": "Fatura hatırlatma",
            "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
            "variables": {
                "fatura_no": "FTR-2026-1042",
                "fatura_tutari": "1.250,00 TL",
                "son_odeme_tarihi": "30 Eylül 2026"
            },
            "scheduled_at": "2026-10-07T07:30:00+00:00",
            "attempts": 2,
            "next_attempt_at": null,
            "waiting_reason": null,
            "blocked_reason": null,
            "failure_reason": null,
            "outcome": "completed",
            "outcome_label": "Görüşme yapıldı",
            "last_call": {
                "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
                "campaign": {
                    "id": 12,
                    "name": "Fatura hatırlatma"
                },
                "contact": {
                    "id": 4821,
                    "phone": "+905321234567",
                    "name": "Ayşe Yılmaz"
                },
                "status": "completed",
                "outcome": "completed",
                "outcome_label": "Görüşme yapıldı",
                "direction": "outbound",
                "is_test": false,
                "answered_at": "2026-10-07T08:45:02+00:00",
                "ended_at": "2026-10-07T08:47:16+00:00",
                "duration_seconds": 134,
                "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
                "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
                "interest_score": 70,
                "next_action": "9 Ekim akşamı ödemeyi kontrol et.",
                "callback_at": null,
                "finalized_at": "2026-10-07T08:47:40+00:00",
                "created_at": "2026-10-07T08:44:31+00:00"
            },
            "created_at": "2026-10-06T19:02:11+00:00",
            "updated_at": "2026-10-07T08:47:40+00:00",
            "completed_at": "2026-10-07T08:47:40+00:00"
        }
    ]
}
GET /api/v1/call-requests/{id}

Arama talebini getir

Talebin güncel durumu, deneme sayısı, bir sonraki deneme zamanı ve son görüşmesi (özetiyle).

Adreste

id string zorunlu
Arama talebinin kimliği.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/call-requests/01k6zq3m8v2c4x7b9n5t1r0wyd" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "id": "01k6zq3m8v2c4x7b9n5t1r0wyd",
        "status": "completed",
        "campaign": {
            "id": 12,
            "name": "Fatura hatırlatma"
        },
        "contact": {
            "id": 4821,
            "phone": "+905321234567",
            "name": "Ayşe Yılmaz"
        },
        "external_id": "FTR-2026-1042",
        "reason": "Fatura hatırlatma",
        "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
        "variables": {
            "fatura_no": "FTR-2026-1042",
            "fatura_tutari": "1.250,00 TL",
            "son_odeme_tarihi": "30 Eylül 2026"
        },
        "scheduled_at": "2026-10-07T07:30:00+00:00",
        "attempts": 2,
        "next_attempt_at": null,
        "waiting_reason": null,
        "blocked_reason": null,
        "failure_reason": null,
        "outcome": "completed",
        "outcome_label": "Görüşme yapıldı",
        "last_call": {
            "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
            "campaign": {
                "id": 12,
                "name": "Fatura hatırlatma"
            },
            "contact": {
                "id": 4821,
                "phone": "+905321234567",
                "name": "Ayşe Yılmaz"
            },
            "status": "completed",
            "outcome": "completed",
            "outcome_label": "Görüşme yapıldı",
            "direction": "outbound",
            "is_test": false,
            "answered_at": "2026-10-07T08:45:02+00:00",
            "ended_at": "2026-10-07T08:47:16+00:00",
            "duration_seconds": 134,
            "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
            "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
            "interest_score": 70,
            "next_action": "9 Ekim akşamı ödemeyi kontrol et.",
            "callback_at": null,
            "finalized_at": "2026-10-07T08:47:40+00:00",
            "created_at": "2026-10-07T08:44:31+00:00"
        },
        "created_at": "2026-10-06T19:02:11+00:00",
        "updated_at": "2026-10-07T08:47:40+00:00",
        "completed_at": "2026-10-07T08:47:40+00:00"
    }
}
POST /api/v1/call-requests/{id}/cancel

Arama talebini iptal et

Yalnızca araması başlamamış talepler (queued, retrying) iptal edilebilir; kişi kampanyanın arama sırasından çıkarılır. Örneğin fatura arama saatinden önce ödendiyse kullanın. Aranmakta olan ya da sonuçlanmış talep 409 request_not_cancellable döner.

Adreste

id string zorunlu
Arama talebinin kimliği.

Başlıklar

Idempotency-Key string
Ağ hatasında isteği güvenle tekrarlamak için benzersiz bir anahtar (en fazla 255 karakter). Bkz. Tekrarlanan istekler. 
curl -X POST "https://panel.etemsilci.com/api/v1/call-requests/01k6zq3m8v2c4x7b9n5t1r0wyd/cancel" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "id": "01k6zq3m8v2c4x7b9n5t1r0wyd",
        "status": "cancelled",
        "campaign": {
            "id": 12,
            "name": "Fatura hatırlatma"
        },
        "contact": {
            "id": 4821,
            "phone": "+905321234567",
            "name": "Ayşe Yılmaz"
        },
        "external_id": "FTR-2026-1042",
        "reason": "Fatura hatırlatma",
        "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
        "variables": {
            "fatura_no": "FTR-2026-1042",
            "fatura_tutari": "1.250,00 TL",
            "son_odeme_tarihi": "30 Eylül 2026"
        },
        "scheduled_at": "2026-10-07T07:30:00+00:00",
        "attempts": 0,
        "next_attempt_at": null,
        "waiting_reason": null,
        "blocked_reason": null,
        "failure_reason": "cancelled_by_api",
        "outcome": null,
        "outcome_label": null,
        "last_call": null,
        "created_at": "2026-10-06T19:02:11+00:00",
        "updated_at": "2026-10-07T06:58:03+00:00",
        "completed_at": "2026-10-07T06:58:03+00:00"
    }
}

Uç noktalar

Kişiler

Kişileri telefon numarasına göre ekleyin, güncelleyin ve bulun. campaign_id ile kişiyi bir kampanyanın arama listesine de koyabilirsiniz (kampanyanın kendi sırasıyla aranır).

POST /api/v1/contacts

Kişi ekle veya güncelle

Kişiyi telefona göre bulur; yoksa oluşturur (201), varsa yalnızca gönderdiğiniz alanları günceller (200). campaign_id verilirse kişi kampanyanın listesine eklenir (zaten listedeyse dokunulmaz) ve kampanya aktifse arama saatlerinde sırası gelince aranır.

Başlıklar

Idempotency-Key string
Ağ hatasında isteği güvenle tekrarlamak için benzersiz bir anahtar (en fazla 255 karakter). Bkz. Tekrarlanan istekler.

Gövde (JSON)

phone string zorunlu
Aranacak numara. 0532…, +90532… veya 532… biçiminde; yurt dışı numaralar + veya 00 ile.
first_name string
Ad (en fazla 120 karakter). Asistan kişiye adıyla hitap eder.
last_name string
Soyad (en fazla 120 karakter).
company string
Firma adı (en fazla 255 karakter).
email string · email
E-posta adresi. Asistan dosya gönderirken kullanabilir.
customer_type string
Müşteri tipi; İYS kuralını belirler. Yeni kişide varsayılan individual. Değerler: individual merchant
iys_status string
Kişinin İYS'deki arama izni. İYS entegrasyonunuz bağlıysa izin İYS'den sorgulanır; değilse bu değer kullanılır. Yeni kişide varsayılan unchecked (aranamaz). Bkz. Uyum. Değerler: unchecked allowed denied not_found
consent_source string
İzni nereden aldığınız (en fazla 120 karakter), örneğin "Abonelik sözleşmesi, 2025-03-12".
about string
Kişi hakkında kalıcı bilgi (en fazla 2000 karakter); asistan bu kişiyle her görüşmede kullanır.
custom_fields object
Kişinin özel alanları: ad → metin veya sayı (en fazla 30 alan, değer en fazla 500 karakter). Mevcut alanlarla birleştirilir.
campaign_id integer
Verilirse kişi bu kampanyanın arama listesine eklenir. 
curl -X POST "https://panel.etemsilci.com/api/v1/contacts" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "05321234567",
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "email": "[email protected]",
    "customer_type": "individual",
    "iys_status": "allowed",
    "consent_source": "Web sitesi teklif formu, 2026-10-06",
    "about": "Web sitemizdeki teklif formunu doldurdu.",
    "custom_fields": {
        "musteri_no": "M-20931"
    },
    "campaign_id": 12
}'
201 Cevap 
{
    "data": {
        "id": 4821,
        "phone": "+905321234567",
        "first_name": "Ayşe",
        "last_name": "Yılmaz",
        "company": null,
        "email": "[email protected]",
        "customer_type": "individual",
        "iys_status": "allowed",
        "do_not_call": false,
        "about": "Web sitemizdeki teklif formunu doldurdu.",
        "custom_fields": {
            "musteri_no": "M-20931"
        },
        "created_at": "2026-10-06T19:02:11+00:00"
    },
    "created": true,
    "campaign": {
        "campaign_id": 12,
        "status": "pending",
        "next_attempt_at": "2026-10-06T19:02:11+00:00",
        "excluded_reason": null
    }
}
GET /api/v1/contacts

Telefonla kişi bul

Kişi bulunursa tek elemanlı, bulunamazsa boş bir liste döner.

Sorgu parametreleri

phone string zorunlu
Aranan telefon numarası, kabul edilen her biçimde.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/contacts?phone=05321234567" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": 4821,
            "phone": "+905321234567",
            "first_name": "Ayşe",
            "last_name": "Yılmaz",
            "company": null,
            "email": "[email protected]",
            "customer_type": "individual",
            "iys_status": "allowed",
            "do_not_call": false,
            "about": "Web sitemizdeki teklif formunu doldurdu.",
            "custom_fields": {
                "musteri_no": "M-20931"
            },
            "created_at": "2026-10-06T19:02:11+00:00"
        }
    ]
}
GET /api/v1/contacts/{id}

Kişiyi getir

Tek bir kişinin bilgileri.

Adreste

id integer zorunlu
Kişinin kimliği.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/contacts/4821" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "id": 4821,
        "phone": "+905321234567",
        "first_name": "Ayşe",
        "last_name": "Yılmaz",
        "company": null,
        "email": "[email protected]",
        "customer_type": "individual",
        "iys_status": "allowed",
        "do_not_call": false,
        "about": "Web sitemizdeki teklif formunu doldurdu.",
        "custom_fields": {
            "musteri_no": "M-20931"
        },
        "created_at": "2026-10-06T19:02:11+00:00"
    }
}

Uç noktalar

Kampanyalar

Kampanyaları listeleyin ve kayıtlı kişileri kampanya listesine ekleyin. Kampanyaların kendisi panelde oluşturulur ve düzenlenir.

GET /api/v1/campaigns

Kampanyaları listele

Giden arama kampanyalarınız, ada göre sıralı. Arama talebi için active veya paused bir kampanya seçin.

Parametre yok.

curl "https://panel.etemsilci.com/api/v1/campaigns" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": 14,
            "name": "Abonelik yenileme",
            "status": "active",
            "goal": "upsell"
        },
        {
            "id": 12,
            "name": "Fatura hatırlatma",
            "status": "active",
            "goal": "collection"
        }
    ]
}
POST /api/v1/campaigns/{id}/contacts

Kişileri kampanyaya ekle

Kayıtlı kişileri kimlik veya telefonla kampanyanın listesine ekler. Listede olanlara dokunulmaz; aranmayacaklar listesindekiler "hariç tutuldu" olarak eklenir.

Adreste

id integer zorunlu
Kampanyanın kimliği.

Başlıklar

Idempotency-Key string
Ağ hatasında isteği güvenle tekrarlamak için benzersiz bir anahtar (en fazla 255 karakter). Bkz. Tekrarlanan istekler.

Gövde (JSON)

contact_ids integer[]
Eklenecek kişilerin kimlikleri (en fazla 1000).
phones string[]
Eklenecek kişilerin telefonları (en fazla 1000). Yalnızca kayıtlı kişiler eklenir. 
curl -X POST "https://panel.etemsilci.com/api/v1/campaigns/12/contacts" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
        4821
    ],
    "phones": [
        "05329998877"
    ]
}'
200 Cevap 
{
    "added": 2,
    "matched": 2
}

Uç noktalar

Görüşmeler

Sonuçlanmış görüşmeleri, yapay zekâ özeti, notları ve sonraki adımıyla çekin. Düzenli çekimde since kullanın.

GET /api/v1/calls

Görüşmeleri listele

Sonucu kesinleşmiş görüşmeler, en yeni önce. Test aramaları varsayılan olarak gelmez. Sayfalama yoktur: son aldığınız görüşmenin finalized_at değerini bir sonraki istekte since olarak kullanın.

Sorgu parametreleri

since string · date-time
Bu zamandan sonra sonuçlanan (finalized_at) görüşmeler.
campaign_id integer
Yalnızca bu kampanyanın kayıtları.
outcome string
Yalnızca bu sonuçtaki görüşmeler. Değerler: no_answer busy wrong_number failed voicemail completed hung_up interested callback_requested follow_up_planned meeting_scheduled sale_made payment_promised survey_completed confirmed resolved not_interested do_not_call transferred dialed_out
limit integer
En fazla kaç kayıt dönsün (1–100). Varsayılan 25. Varsayılan: 25
include_tests boolean
true ise paneldeki test aramaları da gelir.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/calls?since=2026-10-07T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
            "campaign": {
                "id": 12,
                "name": "Fatura hatırlatma"
            },
            "contact": {
                "id": 4821,
                "phone": "+905321234567",
                "name": "Ayşe Yılmaz"
            },
            "status": "completed",
            "outcome": "completed",
            "outcome_label": "Görüşme yapıldı",
            "direction": "outbound",
            "is_test": false,
            "answered_at": "2026-10-07T08:45:02+00:00",
            "ended_at": "2026-10-07T08:47:16+00:00",
            "duration_seconds": 134,
            "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
            "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
            "interest_score": 70,
            "next_action": "9 Ekim akşamı ödemeyi kontrol et.",
            "callback_at": null,
            "finalized_at": "2026-10-07T08:47:40+00:00",
            "created_at": "2026-10-07T08:44:31+00:00"
        }
    ]
}
GET /api/v1/calls/{id}

Görüşmeyi getir

Tek bir görüşme. Görüşme sürerken de okunabilir; finalized_at dolunca sonuç ve özet kesinleşmiştir.

Adreste

id string zorunlu
Görüşmenin kimliği.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/calls/01k6zq9h4e2r7s5d3f8g6j1k0m" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
        "campaign": {
            "id": 12,
            "name": "Fatura hatırlatma"
        },
        "contact": {
            "id": 4821,
            "phone": "+905321234567",
            "name": "Ayşe Yılmaz"
        },
        "status": "completed",
        "outcome": "completed",
        "outcome_label": "Görüşme yapıldı",
        "direction": "outbound",
        "is_test": false,
        "answered_at": "2026-10-07T08:45:02+00:00",
        "ended_at": "2026-10-07T08:47:16+00:00",
        "duration_seconds": 134,
        "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
        "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
        "interest_score": 70,
        "next_action": "9 Ekim akşamı ödemeyi kontrol et.",
        "callback_at": null,
        "finalized_at": "2026-10-07T08:47:40+00:00",
        "created_at": "2026-10-07T08:44:31+00:00"
    }
}

Uç noktalar

Otomasyon tetikleyicileri

Zapier, Make, n8n, Pabbly ya da Power Automate için anlık tetikleyiciler (REST hooks): akış açılınca POST /hooks ile tetikleyici açın, kapanınca DELETE /hooks/{id} ile kapatın. Olaylar webhook'larla aynı gövdede, tetikleyicinin kendi imza anahtarıyla gelir. Adresiniz 410 Gone derse tetikleyici kapatılır; art arda başarısız gönderimlerde durdurulur (disabled). Bir anahtar iptal edilince açtığı tetikleyiciler de kapanır. Panelde bunlar Entegrasyonlar → Webhook → Giden webhook'ta görünür. Kod yazmadan kişi arattırmak için kampanyanın gelen webhook adresini kullanın (aynı sayfada Gelen webhook).

GET /api/v1/me

Anahtarın hesabı

Anahtarın hangi hesaba ait olduğu. Otomasyon araçlarının "bağlantıyı test et" adımı ve hesap etiketi için.

Parametre yok.

curl "https://panel.etemsilci.com/api/v1/me" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "account": {
            "id": 318,
            "name": "Ayşe Mobilya"
        },
        "api_key": {
            "name": "Zapier",
            "prefix": "et_live_k3Fq"
        }
    }
}
POST /api/v1/hooks

Tetikleyici aç

Olay olduğunda target_url adresine imzalı POST gönderilir. İmza anahtarı (secret) yalnızca bu cevapta döner. campaign_id ile yalnızca o kampanyanın olayları, outcomes ile (yalnızca call.finalized) yalnızca o sonuçlar gönderilir. Adres https:// olmalı ve herkese açık bir sunucuda bulunmalıdır.

Gövde (JSON)

event string zorunlu
Olay: call.finalized, meeting.scheduled, contact.dnc ya da call_request.completed. Değerler: call.finalized meeting.scheduled contact.dnc call_request.completed
target_url string · uri zorunlu
Olayların gönderileceği adres (aracınızın webhook adresi), https:// ile.
campaign_id integer
Yalnızca bu kampanyanın olayları (call.finalized, meeting.scheduled, call_request.completed).
outcomes string[]
Yalnızca bu sonuçlar (call.finalized için); boşsa her sonuç.
source string
Tetikleyiciyi açan araç; panelde gösterilir. Verilmezse adresin alan adından anlaşılır. Değerler: zapier make n8n pabbly power_automate other

Olası hatalar

curl -X POST "https://panel.etemsilci.com/api/v1/hooks" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "call.finalized",
    "target_url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
    "campaign_id": 12,
    "outcomes": [
        "interested",
        "meeting_scheduled"
    ],
    "source": "zapier"
}'
201 Cevap 
{
    "data": {
        "id": 27,
        "event": "call.finalized",
        "target_url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
        "source": "zapier",
        "filters": {
            "campaign_id": 12,
            "outcomes": [
                "interested",
                "meeting_scheduled"
            ]
        },
        "status": "active",
        "created_at": "2026-10-07T08:30:00+00:00",
        "last_delivered_at": "2026-10-07T08:47:41+00:00",
        "disabled_at": null,
        "secret": "whsec_9pX2mLq7RfT4vN8bK1cW5hJ3dY6sA0eZ"
    }
}
GET /api/v1/hooks

Tetikleyicileri listele

Hesabın açık ve durdurulmuş tetikleyicileri, en yeni önce (panelden eklenenler dahil).

Parametre yok.

curl "https://panel.etemsilci.com/api/v1/hooks" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": 27,
            "event": "call.finalized",
            "target_url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
            "source": "zapier",
            "filters": {
                "campaign_id": 12,
                "outcomes": [
                    "interested",
                    "meeting_scheduled"
                ]
            },
            "status": "active",
            "created_at": "2026-10-07T08:30:00+00:00",
            "last_delivered_at": "2026-10-07T08:47:41+00:00",
            "disabled_at": null
        }
    ]
}
GET /api/v1/hooks/{id}

Tetikleyiciyi getir

Tek tetikleyici: durumu ve son başarılı gönderim zamanı.

Adreste

id integer zorunlu
Tetikleyicinin kimliği.

Olası hatalar

curl "https://panel.etemsilci.com/api/v1/hooks/27" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": {
        "id": 27,
        "event": "call.finalized",
        "target_url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
        "source": "zapier",
        "filters": {
            "campaign_id": 12,
            "outcomes": [
                "interested",
                "meeting_scheduled"
            ]
        },
        "status": "active",
        "created_at": "2026-10-07T08:30:00+00:00",
        "last_delivered_at": "2026-10-07T08:47:41+00:00",
        "disabled_at": null
    }
}
DELETE /api/v1/hooks/{id}

Tetikleyiciyi kapat

Akış kapatıldığında çağırın; bu adrese artık olay gönderilmez.

Adreste

id integer zorunlu
Tetikleyicinin kimliği.

Olası hatalar

curl -X DELETE "https://panel.etemsilci.com/api/v1/hooks/27" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"

204 · Cevap gövdesi yok.

GET /api/v1/hooks/samples/{event}

Örnek olaylar

Hesabın son gerçek olayları (en yeni önce, en fazla 3), tetikleyicinin alacağı gövdeyle; henüz olay yoksa dokümandaki örnek. Alan eşleme ekranları ve Zapier'in "perform list" adımı için. campaign_id ve outcomes[] filtreleri POST /hooks'taki gibidir.

Adreste

event string zorunlu
Olay: call.finalized, meeting.scheduled, contact.dnc ya da call_request.completed. Değerler: call.finalized meeting.scheduled contact.dnc call_request.completed

Sorgu parametreleri

campaign_id integer
Yalnızca bu kampanyanın olayları (call.finalized, meeting.scheduled, call_request.completed).
outcomes[] string[]
Yalnızca bu sonuçlar (call.finalized için); boşsa her sonuç. 
curl "https://panel.etemsilci.com/api/v1/hooks/samples/call.finalized?outcomes[]=interested" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"
200 Cevap 
{
    "data": [
        {
            "id": "5f0c2a7e-9b1d-4e3a-8c6f-2d7b1a9e4c30",
            "event": "call.finalized",
            "created_at": "2026-10-07T08:47:40+00:00",
            "data": {
                "call": {
                    "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
                    "direction": "outbound",
                    "is_test": false,
                    "status": "completed",
                    "outcome": "completed",
                    "outcome_label": "Görüşme yapıldı",
                    "interest_score": 70,
                    "duration_seconds": 134,
                    "answered_at": "2026-10-07T08:45:02+00:00",
                    "ended_at": "2026-10-07T08:47:16+00:00",
                    "callback_at": null,
                    "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
                    "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
                    "next_action": "9 Ekim akşamı ödemeyi kontrol et."
                },
                "campaign": {
                    "id": 12,
                    "name": "Fatura hatırlatma"
                },
                "contact": {
                    "id": 4821,
                    "first_name": "Ayşe",
                    "last_name": "Yılmaz",
                    "company": null,
                    "email": "[email protected]",
                    "phone": "+905321234567",
                    "custom_fields": {
                        "musteri_no": "M-20931"
                    }
                }
            }
        }
    ]
}

Nesneler

Cevaplarda dönen nesnelerin alanları. Yeni alanlar eklenebilir; kodunuz bilmediği alanları yok saymalıdır.

Arama talebi

CallRequest
id string
Talebin kimliği (ULID).
status string
Talebin durumu; bkz. Talebin durumları. Değerler: queued calling retrying completed failed cancelled blocked
campaign object
Aramayı yapan kampanya: id, name.
contact object
Aranan kişi: id, phone (E.164), name (ad soyad, yoksa null).
external_id string boş olabilir
Gönderdiğiniz referans.
reason string boş olabilir
Aramanın nedeni.
instructions string boş olabilir
Asistana bu talep için verilen ek talimat.
variables object
Asistanın kullandığı bilgiler (değerler metin). Yoksa {}.
scheduled_at string · date-time boş olabilir
İstenen en erken arama zamanı.
attempts integer
Bu talep için yapılan arama sayısı.
next_attempt_at string · date-time boş olabilir
Sıradaki aramanın en erken zamanı (queued ve retrying durumunda).
waiting_reason string boş olabilir
Sıradaki talebin neden henüz aranmadığı: campaign_paused, outside_calling_window, holiday, daily_attempt_limit, iys_unavailable, line_refused. Değerler: campaign_paused iys_unavailable holiday outside_calling_window daily_attempt_limit line_refused
blocked_reason string boş olabilir
blocked talebin nedeni; bkz. Uyum. Değerler: contact_do_not_call dnc_listed iys_denied iys_no_consent max_attempts_reached
failure_reason string boş olabilir
failed veya cancelled talebin nedeni: not_reached, cancelled_by_api, superseded, removed_from_campaign, campaign_completed. Değerler: not_reached cancelled_by_api superseded removed_from_campaign campaign_completed
outcome string boş olabilir
Talebin sonucu: kişi açtıysa son cevaplanan görüşmenin sonucu, açmadıysa son denemenin sonucu. Değerler: no_answer busy wrong_number failed voicemail completed hung_up interested callback_requested follow_up_planned meeting_scheduled sale_made payment_promised survey_completed confirmed resolved not_interested do_not_call transferred dialed_out
outcome_label string boş olabilir
Sonucun Türkçe adı.
last_call Call boş olabilir
Talebin son görüşmesi (Görüşme nesnesi) ya da null.
created_at string · date-time
Talebin oluşturulma zamanı.
updated_at string · date-time
Talebin son değiştiği zaman.
completed_at string · date-time boş olabilir
Talebin sonuçlandığı zaman (completed, failed, cancelled, blocked).

Görüşme

Call
id string
Görüşmenin kimliği (ULID).
campaign object
Kampanya: id, name.
contact object
Kişi: id, phone, name.
status string
Teknik durum: queued, dialing, ringing, in_progress, completed, failed. Değerler: queued dialing ringing in_progress completed failed
outcome string boş olabilir
Görüşmenin sonucu; bkz. sonuç değerleri. Değerler: no_answer busy wrong_number failed voicemail completed hung_up interested callback_requested follow_up_planned meeting_scheduled sale_made payment_promised survey_completed confirmed resolved not_interested do_not_call transferred dialed_out
outcome_label string boş olabilir
Sonucun Türkçe adı.
direction string
outbound (giden) veya inbound (gelen çağrı). Değerler: outbound inbound
is_test boolean
Panelden yapılan test araması mı?
answered_at string · date-time boş olabilir
Kişinin açtığı zaman; açmadıysa null.
ended_at string · date-time boş olabilir
Görüşmenin bittiği zaman.
duration_seconds integer boş olabilir
Görüşme süresi (saniye).
summary string boş olabilir
Görüşmenin yapay zekâ özeti.
notes string boş olabilir
Önemli noktalar (madde işaretli metin).
interest_score integer boş olabilir
İlgi puanı (0–100).
next_action string boş olabilir
Önerilen sonraki adım.
callback_at string · date-time boş olabilir
Kişinin tekrar aranmak istediği zaman.
finalized_at string · date-time boş olabilir
Sonucun kesinleştiği zaman; boşsa görüşme sürüyor ya da özetleniyor.
created_at string · date-time
Görüşme kaydının oluşturulma zamanı.

Kişi

Contact
id integer
Kişinin kimliği.
phone string
Telefon (E.164).
first_name string boş olabilir
Ad.
last_name string boş olabilir
Soyad.
company string boş olabilir
Firma.
email string boş olabilir
E-posta.
customer_type string
individual (Bireysel) veya merchant (Tacir / esnaf). Değerler: individual merchant
iys_status string
unchecked, allowed, denied veya not_found. Değerler: unchecked allowed denied not_found
do_not_call boolean
Kişi aranmak istemiyor mu (aranmayacaklar listesi)?
about string boş olabilir
Kişi hakkında bilgi.
custom_fields object
Özel alanlar (ad → metin).
created_at string · date-time boş olabilir
Oluşturulma zamanı.

Kampanya

Campaign
id integer
Kampanyanın kimliği.
name string
Kampanyanın adı.
status string
draft (Taslak), active (Aktif), paused (Duraklatıldı) veya completed (Tamamlandı). Değerler: draft active paused completed
goal string
Kampanyanın hedefi: sales (satış), upsell (yenileme ve ek satış), reactivation (geri kazanma), qualify (nitelendirme), meeting (toplantı ve randevu), product_intro (ürün tanıtımı), promotion (kampanya duyurusu), event (etkinlik daveti), survey (anket), collection (ödeme hatırlatma), confirmation (teyit), inform (bilgilendirme) veya callback (geri arama). Değerler: sales upsell reactivation qualify meeting product_intro promotion event survey collection confirmation inform callback

Tetikleyici

Hook
id integer
Tetikleyicinin kimliği.
event string
Gönderilen olay. Değerler: call.finalized meeting.scheduled contact.dnc call_request.completed
target_url string · uri
Olayların gönderildiği adres.
source string
Tetikleyiciyi açan araç. Değerler: zapier make n8n pabbly power_automate other
filters object boş olabilir
Varsa filtreler: campaign_id, outcomes.
status string
active ya da disabled (art arda başarısız gönderimlerden sonra durduruldu). Değerler: active disabled
created_at string · date-time
Açıldığı zaman.
last_delivered_at string · date-time boş olabilir
Son başarılı gönderim.
disabled_at string · date-time boş olabilir
Durdurulduğu zaman.

Sonuç değerleri

Görüşmenin ve talebin outcome alanı şu değerlerden birini alır:

  • no_answer Açmadı
  • busy Meşgul
  • wrong_number Yanlış numara
  • failed Teknik hata
  • voicemail Telesekreter
  • completed Görüşme yapıldı
  • hung_up Konuşmadan kapattı
  • interested İlgileniyor
  • callback_requested Tekrar aranmak istiyor
  • follow_up_planned Planlama yapıldı
  • meeting_scheduled Toplantı ayarlandı
  • sale_made Satış yapıldı
  • payment_promised Ödeme sözü alındı
  • survey_completed Anket tamamlandı
  • confirmed Onaylandı
  • resolved Talep çözüldü
  • not_interested İlgilenmiyor
  • do_not_call Aranmak istemiyor
  • transferred Temsilciye aktarıldı
  • dialed_out Dışarı arama

Webhook'lar

Webhook bağlantısı, seçtiğiniz olaylarda adresinize imzalı bir POST isteği gönderir. Kurulum: Entegrasyonlar → Webhook (CRM); adresiniz https:// olmalı ve herkese açık bir sunucuda bulunmalıdır. Arama talepleri için Arama talebi sonuçlandı olayını seçin.

  • call_request.completed Arama talebi sonuçlandı

    Bir arama talebi sonuçlandığında (completed, failed, cancelled, blocked), talep başına bir kez. data.call_request, GET /call-requests/{id} cevabıyla aynıdır.

  • call.finalized Görüşme sonuçlandı

    Her görüşmenin sonucu kesinleştiğinde, bir kez (talebe bağlı her deneme dahil). Test aramaları da gönderilir (is_test).

  • meeting.scheduled Toplantı ayarlandı

    Asistan bir görüşmede toplantı ayarladığında.

  • contact.dnc Kişi aranmak istemiyor

    Aranmayacaklar listesine yeni bir numara eklendiğinde.

  • action_rule.triggered Otomasyon kuralı çalıştı

    Kanalı "Webhook" olan bir otomasyon kuralı çalıştığında (abonelik gerekmez).

  • ping Test

    Panelde Test et'e bastığınızda.

İstek gövdesi

Her istek aynı zarfla gelir: olay kimliği (id), olay adı (event), olayın zamanı (created_at) ve olaya göre değişen data. Başlıklar: Content-Type: application/json, X-Arar-Event (olay adı), X-Arar-Event-Id (gövdedeki id), X-Arar-Timestamp (Unix saniye) ve X-Arar-Signature.

POST call_request.completed örneği 
{
    "id": "5f0c2a7e-9b1d-4e3a-8c6f-2d7b1a9e4c30",
    "event": "call_request.completed",
    "created_at": "2026-10-07T08:47:40+00:00",
    "data": {
        "call_request": {
            "id": "01k6zq3m8v2c4x7b9n5t1r0wyd",
            "status": "completed",
            "campaign": {
                "id": 12,
                "name": "Fatura hatırlatma"
            },
            "contact": {
                "id": 4821,
                "phone": "+905321234567",
                "name": "Ayşe Yılmaz"
            },
            "external_id": "FTR-2026-1042",
            "reason": "Fatura hatırlatma",
            "instructions": "Son ödeme tarihinin geçtiğini nazikçe hatırlat ve ödeme kanallarını anlat. Kart bilgisi isteme. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
            "variables": {
                "fatura_no": "FTR-2026-1042",
                "fatura_tutari": "1.250,00 TL",
                "son_odeme_tarihi": "30 Eylül 2026"
            },
            "scheduled_at": "2026-10-07T07:30:00+00:00",
            "attempts": 2,
            "next_attempt_at": null,
            "waiting_reason": null,
            "blocked_reason": null,
            "failure_reason": null,
            "outcome": "completed",
            "outcome_label": "Görüşme yapıldı",
            "last_call": {
                "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
                "campaign": {
                    "id": 12,
                    "name": "Fatura hatırlatma"
                },
                "contact": {
                    "id": 4821,
                    "phone": "+905321234567",
                    "name": "Ayşe Yılmaz"
                },
                "status": "completed",
                "outcome": "completed",
                "outcome_label": "Görüşme yapıldı",
                "direction": "outbound",
                "is_test": false,
                "answered_at": "2026-10-07T08:45:02+00:00",
                "ended_at": "2026-10-07T08:47:16+00:00",
                "duration_seconds": 134,
                "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
                "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
                "interest_score": 70,
                "next_action": "9 Ekim akşamı ödemeyi kontrol et.",
                "callback_at": null,
                "finalized_at": "2026-10-07T08:47:40+00:00",
                "created_at": "2026-10-07T08:44:31+00:00"
            },
            "created_at": "2026-10-06T19:02:11+00:00",
            "updated_at": "2026-10-07T08:47:40+00:00",
            "completed_at": "2026-10-07T08:47:40+00:00"
        }
    }
}
POST call.finalized örneği 
{
    "id": "5f0c2a7e-9b1d-4e3a-8c6f-2d7b1a9e4c30",
    "event": "call.finalized",
    "created_at": "2026-10-07T08:47:40+00:00",
    "data": {
        "call": {
            "id": "01k6zq9h4e2r7s5d3f8g6j1k0m",
            "direction": "outbound",
            "is_test": false,
            "status": "completed",
            "outcome": "completed",
            "outcome_label": "Görüşme yapıldı",
            "interest_score": 70,
            "duration_seconds": 134,
            "answered_at": "2026-10-07T08:45:02+00:00",
            "ended_at": "2026-10-07T08:47:16+00:00",
            "callback_at": null,
            "summary": "Ayşe Hanım faturayı 9 Ekim'de mobil uygulamadan ödeyeceğini söyledi.",
            "notes": "- Ödeme 9 Ekim'de yapılacak\n- Taksit sormadı",
            "next_action": "9 Ekim akşamı ödemeyi kontrol et."
        },
        "campaign": {
            "id": 12,
            "name": "Fatura hatırlatma"
        },
        "contact": {
            "id": 4821,
            "first_name": "Ayşe",
            "last_name": "Yılmaz",
            "company": null,
            "email": "[email protected]",
            "phone": "+905321234567",
            "custom_fields": {
                "musteri_no": "M-20931"
            }
        }
    }
}

İmza doğrulama

X-Arar-Signature = v1= + onaltılık HMAC-SHA256(imza anahtarınız, X-Arar-Timestamp + . + ham gövde). İmzayı ham gövde üzerinden hesaplayın (JSON'u ayrıştırıp yeniden yazmayın), sabit zamanlı karşılaştırın ve 5 dakikadan eski istekleri reddedin.

İmza anahtarı (whsec_…) webhook'u ilk kaydettiğinizde bir kez gösterilir. Kaybettiyseniz kartta Anahtarı yenile'ye basın; eski anahtar hemen geçersiz olur.

<?php

$secret = getenv('ETEMSILCI_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input');
$timestamp = (int) ($_SERVER['HTTP_X_ARAR_TIMESTAMP'] ?? 0);
$signature = $_SERVER['HTTP_X_ARAR_SIGNATURE'] ?? '';

// İmzayı ham gövde üzerinden doğrula; 5 dakikadan eski istekleri reddet
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (! hash_equals($expected, $signature) || abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Aynı olay yeniden denenebilir: olay kimliğiyle tekrarları ayıklayın: $event['id']

if ($event['event'] === 'call_request.completed') {
    $request = $event['data']['call_request'];

    // Sonucu kendi kaydınıza işleyin
    match ($request['status']) {
        'completed' => saveResult($request['external_id'], $request['outcome'], $request['last_call']['summary']),
        'failed' => sendSms($request['external_id']), // Ulaşılamadı: örneğin SMS gönderin
        'blocked' => flagConsent($request['external_id'], $request['blocked_reason']), // Aranamadı (İYS / aranmayacaklar listesi): müşterinin iznini kontrol edin
        default => null,
    };
}

// Hemen 2xx dönün; uzun işleri kuyruğa alın
http_response_code(204);

Teslim ve yeniden deneme

  • Adresiniz 10 saniye içinde 2xx dönmelidir; uzun işleri kuyruğa alıp hemen cevap verin.
  • Bağlantı hatası, 408, 429 ve 5xx cevaplarında istek artan aralıklarla (30 saniyeden 1 saate kadar) toplam 6 kez denenir. Diğer 4xx cevapları yeniden denenmez.
  • Yeniden denemelerde aynı olay kimliği gelir; tekrarları X-Arar-Event-Id ile ayıklayın. Olaylar sırasız gelebilir.
  • Yönlendirmeler (3xx) izlenmez.

Uyum ve aranma kuralları

API'den gelen talep, kampanya listesindeki her kişi gibi aranır: aşağıdaki kurallar her aramadan hemen önce kontrol edilir ve hiçbiri API ile atlanamaz. Bir kural aramayı kalıcı olarak engelliyorsa talep blocked olur; geçici bir engel varsa talep sırada bekler ve waiting_reason nedenini gösterir.

Talebi engelleyen kurallar (blocked_reason)

contact_do_not_call
Kişi aranmak istemiyor olarak işaretli.
dnc_listed
Numara firmanızın aranmayacaklar listesinde. Kişi bir görüşmede aranmak istemediğini söylerse numara otomatik olarak listeye eklenir ve tüm kampanyalarda geçerlidir.
iys_denied
Kişinin İYS'de arama reddi var. Ret kaydı olan kişi, tacir de olsa aranmaz.
iys_no_consent
Bireysel (individual) kişinin İYS'de arama izni yok. Bireysel kişiler yalnızca izin (allowed) varsa aranır.
max_attempts_reached
Kampanyanın deneme hakkı bitmiş.

Talebi bekleten durumlar (waiting_reason)

campaign_paused
Kampanya duraklatılmış; yeniden başlatılınca aranır.
iys_unavailable
İYS durumu doğrulanamadı: İYS entegrasyonunuz varsa sorgu sürüyor; yoksa kişinin iys_status değeri unchecked. Bir saat sonra yeniden denenir.
holiday
Resmî tatil; bir sonraki uygun arama saatinde aranır.
outside_calling_window
Kampanyanın arama saatleri dışında (varsayılan hafta içi 10:00–19:00, firmanızın saat diliminde); next_attempt_at pencerenin açılışıdır.
daily_attempt_limit
Kişi bugün bu kampanyada 2 kez arandı; ertesi gün aranır.
line_refused
Telefon operatörünüz kampanyanın hattından aramayı reddetti (ör. operatör hesabında tutar kalmadı). Deneme hakkı harcanmaz; hat düzelince talep ilk sırada aranır.

Bilmeniz gerekenler

  • İYS: İYS entegrasyonunuz bağlıysa izin her aramadan önce İYS'den doğrulanır. Bağlı değilse kişinin İYS durumu sizin gönderdiğiniz iys_status değeridir ve durumu bilinmeyen (unchecked) kişi aranmaz: izni siz aldıysanız iys_status: "allowed" ve izni nereden aldığınızı consent_source ile gönderin. Tacir veya esnaf müşteriler (merchant) için ön izin gerekmez, yalnızca ret kaydı varsa aranmaz; İYS'de kaydı yoksa iys_status: "not_found" gönderin. Arama izninin hukuki dayanağı firmanızın sorumluluğundadır.
  • Kredi ve eşzamanlılık: Krediniz bir dakikalık görüşmenin altındaysa ya da kampanyanın eşzamanlı arama sınırı doluysa talepler sırada bekler (bu durum waiting_reason'da görünmez). Kredi yalnızca cevaplanan görüşmeler için, konuşulan süre kadar saniye bazında düşer.
  • KVKK: Asistan her görüşmenin başında görüşmenin kaydedildiğini ve bir yapay zekâ asistanıyla konuşulduğunu söyler (kampanyadaki metin). instructions ve variables içine görüşme için gerekmeyen kişisel veri koymayın.
  • Talep ömrü: Açık talepler koşullar uygun olana kadar bekler. Artık gerekmeyen talebi iptal edin; kampanya tamamlanırsa açık talepler cancelled (campaign_completed) olur.

Örnek senaryolar

Gerçek entegrasyonlardan iki örnek: tam istekler cURL, PHP, Python ve Node.js ile.

Aboneliği sona eren müşteriyi arat

Abonelikle çalışan bir hizmetiniz (internet, yazılım, üyelik) var ve müşterinin aboneliği sona erdiğinde asistanın arayıp bilgilendirmesini, yenileme yolunu anlatmasını istiyorsunuz.

  1. 01

    Panelde "Abonelik yenileme" adında, hedefi Bilgilendirme olan bir kampanya oluşturun ve başlatın. Asistanın genel tavrını kampanya talimatlarına, yenileme kanallarınızı bilgi bankasına yazın.

  2. 02

    Abonelik sona erdiğinde sisteminiz aşağıdaki isteği gönderir. external_id müşteri numaranızdır: istek aynı gün iki kez gelse de müşteri bir kez aranır. Idempotency-Key, ağ hatasında isteği güvenle tekrarlamanızı sağlar.

  3. 03

    Sonucu webhook ile alın: completed ise last_call.summary ve outcome değerini müşteri kaydınıza yazın; failed ise (ulaşılamadı) örneğin SMS gönderin; blocked ise müşterinin aranma iznini kontrol edin.

curl -X POST "https://panel.etemsilci.com/api/v1/call-requests" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: yenileme-M-20931-2026-10-06" \
  -d '{
    "campaign_id": 14,
    "phone": "05551234567",
    "first_name": "Mehmet",
    "last_name": "Demir",
    "customer_type": "individual",
    "iys_status": "allowed",
    "consent_source": "Abonelik sözleşmesi, 2025-03-12",
    "reason": "Abonelik sona erdi",
    "instructions": "Müşteriye aboneliğinin sona erdiğini ve hizmetinin yenilenene kadar duraklatıldığını nazikçe bildir. Yenilemek için mobil uygulamayı veya web sitesini öner. Kart bilgisi isteme, ödeme almaya çalışma.",
    "variables": {
        "musteri_no": "M-20931",
        "abonelik": "Aylık 50 GB",
        "bitis_tarihi": "06.10.2026",
        "aylik_ucret": "300,00 TL"
    },
    "external_id": "M-20931-yenileme"
}'

Sonucu webhook ile işleyin →

Ödenmemiş fatura hatırlatması

Son ödeme tarihi geçen faturalar için müşteriyi ertesi sabah aratmak, fatura bu arada ödenirse aramayı iptal etmek istiyorsunuz.

  1. 01

    Hedefi Bilgilendirme olan bir "Fatura hatırlatma" kampanyası oluşturup başlatın. Arama saatlerini (ör. hafta içi 10:00–18:00) kampanyada ayarlayın.

  2. 02

    Gece çalışan işiniz, son ödeme tarihi geçen her fatura için scheduled_at ile ertesi sabaha arama talebi oluşturur. external_id fatura numarasıdır.

  3. 03

    Fatura arama saatinden önce ödenirse talebi external_id ile bulup iptal edin. Aranmakta olan talep iptal edilemez (409); bu yüzden talimata "Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir" gibi bir cümle ekleyin.

  4. 04

    Sonucu call_request.completed webhook'uyla ya da GET /call-requests?external_id=… ile alın.

curl -X POST "https://panel.etemsilci.com/api/v1/call-requests" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-FTR-2026-1042" \
  -d '{
    "campaign_id": 12,
    "phone": "05329998877",
    "first_name": "Kemal",
    "last_name": "Aksoy",
    "company": "Aksoy Gıda Ltd.",
    "customer_type": "merchant",
    "iys_status": "not_found",
    "reason": "Ödenmemiş fatura hatırlatma",
    "instructions": "Faturanın son ödeme tarihinin geçtiğini hatırlat, ne zaman ödeyebileceklerini sor. Ödeme için havale bilgisinin e-postayla gönderileceğini söyle. Müşteri ödediğini söylerse teşekkür edip görüşmeyi kibarca bitir.",
    "variables": {
        "fatura_no": "FTR-2026-1042",
        "fatura_tutari": "1.250,00 TL",
        "son_odeme_tarihi": "30 Eylül 2026",
        "gecikme_gunu": "6"
    },
    "scheduled_at": "2026-10-07T10:30:00+03:00",
    "external_id": "FTR-2026-1042"
}'
# 1) Faturanın arama taleplerini bul
curl "https://panel.etemsilci.com/api/v1/call-requests?external_id=FTR-2026-1042" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"

# 2) Dönen talep queued veya retrying ise iptal et
curl -X POST "https://panel.etemsilci.com/api/v1/call-requests/01k6zq3m8v2c4x7b9n5t1r0wyd/cancel" \
  -H "Authorization: Bearer $ETEMSILCI_API_KEY"

Sonucu webhook ile işleyin →

OpenAPI

Bu sayfadaki uç noktaların tamamı, istek ve cevap şemaları ve örnekleriyle birlikte OpenAPI 3.1 biçiminde de yayımlanır. Postman, Insomnia veya bir istemci kod üreticisine adresi verip içe aktarabilirsiniz.

https://panel.etemsilci.com/gelistiriciler/api/openapi.json
openapi.json dosyasını aç