Entagl API Referansı

Entagl API referansı

API referansı

98 endpoint

58 webhook olayı

Entagl API'si, kendi yazılımınızın bir Entagl workspace'iyle çalışmasını sağlar: kişiler, konuşmalar, mesajlar, randevular, hatırlatıcılar, siparişler, ürünler, yapay zekâ aramaları ve kampanyalar. Webhooks, bir şey olduğu anda sistemlerinize haber verir. Make için Entagl uygulamasının kullandığı API ile aynıdır.

Temel URL

HTTPS

https://api.entagl.com/api/v1

İstekler ve yanıtlar HTTPS üzerinden JSON'dur. Alan adları snake_case biçimindedir. Bir endpoint aksini söylemedikçe ID'ler tam sayıdır. Zamanlar ISO 8601 metinleridir; yanıtlar UTC kullanır.

Kimlik doğrulama

Her istekte Authorization header'ında bir token gönderin: Authorization: Bearer <token>. İki tür token çalışır:

API anahtarı

Kendi sunucu kodunuz için. Entagl uygulamasında Ayarlar → API Anahtarları bölümünden bir tane oluşturun. Anahtarlar ai_ ile başlar. Bir anahtar, oluşturulduğu workspace'te çalışır ve orada sahip yetkilerine sahiptir. Bu yüzden gizli tutun ve asla bir tarayıcıya ya da mobil uygulamaya koymayın.

API Anahtarlarını aç

OAuth 2.0 erişim token'ı

Make için Entagl uygulaması gibi bağlayıcılar tarafından kullanılır. Kişi Entagl hesabıyla giriş yapar ve bağlayıcı, o kişinin workspace'teki rolüyle onun adına işlem yapar. Kendi OAuth entegrasyonunuzu oluşturmak için support@entagl.com ile iletişime geçin.

İstek

curl "https://api.entagl.com/api/v1/contacts?limit=2" \
  -H "Authorization: Bearer ai_your_api_key"

Header eksikse 401 unauthenticated döner. Yanlış ya da iptal edilmiş bir anahtar 401 invalid_api_key döndürür. Süresi dolmuş bir OAuth token'ı 401 invalid_token döndürür: yenileyin ve tekrar deneyin.

Workspace'ler ve izinler

Her istek tam olarak bir workspace üzerinde çalışır. Bir API anahtarı her zaman kendi workspace'ini kullanır. Bir OAuth girişi birden fazla workspace'e ait olabilir (sahibi olduğunuz veya ekip üyesi olarak katıldığınız): birini seçmek için workspace ID'siyle X-Entagl-Workspace header'ını gönderin. Tek workspace varsa header isteğe bağlıdır. GET /me header olmadan çalışır ve girişin kullanabileceği tüm workspace'leri listeler.

İstek

curl "https://api.entagl.com/api/v1/me" \
  -H "Authorization: Bearer <oauth_access_token>"

curl "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "X-Entagl-Workspace: <workspace_id from /me>"

Birden fazla workspace'i olan bir girişte header olmazsa 400 workspace_required alırsınız; girişin erişemediği bir workspace 403 workspace_forbidden döndürür. Başka bir workspace'e ait bir ID her zaman 404 not_found döndürür, asla 403 değil.

Aşağıdaki her endpoint ihtiyaç duyduğu izni gösterir. Sahipler, admin'ler ve API anahtarları her kontrolden geçer. Ekip üyeleri, rolleri ekip ayarlarında o izne sahipse geçer: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns veya integrations. İzin yoksa API 403 insufficient_permissions döndürür.

İstekler ve hatalar

Gövdeleri Content-Type: application/json ile JSON olarak gönderin. Çoğu endpoint bilinmeyen gövde alanlarını 422 ile reddeder, böylece bir yazım hatası sessizce geçmez. Her hata aynı biçimi kullanır: üzerinde dallanabileceğiniz sabit bir code, okunabilir bir message ve doğrulama hatalarında her hatalı alanı gösteren bir details listesi.

422

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid email address",
    "details": [
      { "path": "email", "message": "Invalid email address" }
    ]
  }
}

400Hatalı istek: geçersiz ID, geçersiz cursor, eksik workspace header'ı.
401Eksik, geçersiz veya süresi dolmuş token.
402İşlem için yeterli kredi yok (örneğin bir kampanya gönderirken).
403Kimlik doğrulandı ama izin yok: eksik izin veya workspace erişimi.
404Bulunamadı; başka bir workspace'e ait ID'ler dahil.
409Çakışma: yinelenen ad, yanlış durum veya bir Idempotency-Key çakışması.
422Doğrulama başarısız oldu veya bir iş kuralı değişikliği reddetti.
429İstek sınırına ulaşıldı. Retry-After'a bakın.
500 / 502Entagl veya mesajlaşma kanalı başarısız oldu. Bir yazma işlemini tekrar denemeden önce sonucu kontrol edin.

Eski yanıt biçimi işaretli yollar bu kurallardan öncedir: düz JSON nesneleri veya dizileri döndürür ve çoğu hatayı { "message": "…" } olarak yanıtlar.

Sayfalama

Sayfalı işaretli endpoint'ler en yeni öğeleri önce, bir liste nesnesi içinde döndürür. limit ile en fazla 100 öğe isteyin (varsayılan 25). has_more değeri true olduğunda, sonraki sayfayı almak için next_cursor değerini starting_after olarak gönderin. Diğer listeler her şeyi tek seferde, has_more: false ile döndürür.

Yanıt

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": 6789,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "tags": ["vip"]
    }
  ],
  "has_more": true,
  "next_cursor": "6789"
}

Sonraki sayfa

curl "https://api.entagl.com/api/v1/contacts?limit=100&starting_after=6789" \
  -H "Authorization: Bearer ai_your_api_key"

Idempotency

Standart biçimdeki her POST endpoint Idempotency-Key başlığını kabul eder (en fazla 200 karakter). Her işlem için UUID gibi benzersiz bir değer kullanın. Entagl ilk yanıtı 24 saat saklar: aynı anahtar ve aynı gövdeyle yapılan tekrar, bu yanıtı Idempotent-Replayed: true ile geri alır ve hiçbir şey iki kez çalışmaz. Eski yanıt biçimi ile işaretli rotalar farklı çalışır, aşağıya bakın.

İstek

curl -X POST "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-order-7781" \
  -d '{ "first_name": "Jane", "phone": "+15551234567", "tags": ["vip"] }'

Aynı anahtar farklı bir gövdeyle gelirse 409 idempotency_key_reused döner.
İlk istek hâlâ çalışırken ya da hiç bitmediyse, tekrar deneme 409 request_in_progress döndürür. Sonucu kontrol edin, sonra yeni bir anahtarla tekrar deneyin.
Her sonuç saklanır, hatalar dahil. Başarısız bir isteği yeniden denemek için yeni bir anahtar kullanın.
Anahtarlar workspace'e ve kimlik bilgisine özeldir.

Eski rotalar. POST /messages de Idempotency-Key (veya gövdede message_id) kabul eder: zaten kabul ettiği bir mesajın tekrarı aynı conversationId ile 202 döner ve iki kez işlenmez, aynı anahtar farklı bir gövdeyle gelirse 409 döner. POST /chat için tekrar koruması yoktur: tekrar, yapay zekâyı yeniden çalıştırır, bu yüzden tekrar etmeden önce sonucu kontrol edin.

İstek sınırları

Her workspace dakikada 120 istek yapabilir; bu sınır tüm API anahtarları ve bağlantıları arasında paylaşılır. Yanıtlarda RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset (pencerenin sıfırlanmasına kalan saniye) bulunur. Sınırı aşarsanız Retry-After header'ı ile 429 rate_limited alırsınız: o kadar saniye bekleyin, sonra tekrar deneyin. Eski API kanalı yolları bu sınıra dahil değildir.