REST API
Müşteri adaylarını, aramaları, mesajları, kampanyaları ve randevuları kendi uygulamalarınızdan yönetin.
Temel adres
Tüm REST istekleri aşağıdaki adrese yapılır. OAuth ve MCP uç noktaları alan adının kökündedir.
https://api.speakline.io/api/v1Kimlik doğrulama
İstekler bir API anahtarı ya da OAuth erişim jetonuyla, Authorization başlığında Bearer olarak gönderilir.
API anahtarı
Panelde Ayarlar › API anahtarları bölümünden oluşturulur. Anahtar onu oluşturan üyenin yetkileri ve seçtiğiniz kapsamlarla sınırlıdır; yalnız oluşturulduğunda bir kez gösterilir, isteğe bağlı son kullanma tarihi alır ve istendiğinde iptal edilir. API erişimi içeren planlarda kullanılır.
OAuth 2.1
Başka kullanıcıların hesabına bağlanan uygulamalar içindir. Yetkilendirme kodu akışı kullanılır ve PKCE (S256) zorunludur. Erişim jetonu bir saat, yenileme jetonu 90 gün geçerlidir ve her kullanımda yenilenir. Kullanıcılar bağladıkları uygulamaları panelde Bağlı uygulamalar sayfasından görür ve kaldırır.
| Uç nokta | Amaç |
|---|---|
GET /oauth/authorize | Yetkilendirme ve onay ekranı |
POST /oauth/token | Jeton alma ve yenileme |
POST /oauth/revoke | Jeton iptali |
GET /.well-known/oauth-authorization-server | Yetkilendirme sunucusu bilgileri |
Authorization: Bearer sk_live_…Yanıtlar ve hatalar
Başarılı yanıtlarda sonuç data alanındadır. Hatalı isteklerde HTTP durum kodu sorunu belirtir ve gövde, açıklama içeren bir JSON nesnesidir.
| Durum | Anlamı |
|---|---|
400 | İstek geçersiz |
401 | Kimlik doğrulanmadı: anahtar ya da jeton eksik veya geçersiz |
402 | Plan bu özelliği içermiyor ya da kullanım sınırına ulaşıldı |
403 | Yetki yok |
404 | Kayıt bulunamadı |
422 | Alanlar doğrulanamadı |
429 | Kullanım sınırı aşıldı |
{
"success": true,
"data": { … }
}Sayfalama
Listeler page (1'den başlar) ve page_size (varsayılan 25, en fazla 100) parametreleriyle sayfalanır. Yanıt items, total, page, page_size ve pages alanlarını içerir. Yoğun listelerde imleçli sayfalama (next_cursor, has_more) da kullanılır.
curl "https://api.speakline.io/api/v1/leads?page=2&page_size=50" \
-H "Authorization: Bearer $SPEAKLINE_API_KEY"Kullanım sınırları
- API anahtarıyla saniyede 20, dakikada 1.200 istek.
- Sınır aşıldığında
429yanıtıRetry-AfterveX-RateLimit-*başlıklarıyla döner. - İstek gövdesi en fazla 32 MB olabilir.
Başlıca uç noktalar
Yollar temel adrese göredir.
| Yöntem | Yol | Amaç |
|---|---|---|
GET | /automation/me | API anahtarını ve çalışma alanını doğrular |
GET | /leads | Müşteri adaylarını listeler |
POST | /leads | Müşteri adayı oluşturur |
GET | /leads/{id} | Bir müşteri adayının ayrıntıları |
PATCH | /leads/{id} | Müşteri adayını günceller |
POST | /voice/calls/send | Ses ajanıyla arama başlatır veya planlar |
GET | /voice/calls | Aramaları listeler |
GET | /voice/calls/{id} | Bir aramanın ayrıntıları |
POST | /conversations | Mesaj gönderir |
GET | /campaigns | Kampanyaları listeler |
POST | /campaigns/{id}/leads | Kampanyaya kişi ekler |
POST | /appointments | Randevu oluşturur |
GET | /appointments/calendars | Bağlı takvimleri listeler |
GET | /voicemails | Sesli mesajları listeler |
GET | /agents | Ses ajanlarını listeler |
GET | /channels | Mesajlaşma kanallarını listeler |
GET | /numbers | Telefon numaralarını listeler |
GET | /webhooks/events | Webhook olay kataloğu |
POST | /automation/hooks | Olay aboneliği oluşturur (REST hook) |
DELETE | /automation/hooks/{id} | Olay aboneliğini siler |
Örnek istek
Yeni bir müşteri adayı oluşturur. Telefon numarası E.164 biçiminde yazılır.
curl https://api.speakline.io/api/v1/leads \
-H "Authorization: Bearer $SPEAKLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"full_name": "Emma Clarke",
"phone": "+442079460344",
"email": "emma@example.com",
"source": "api",
"language": "en"
}'