TalkOmni'yi hâlihazırda kullandığınız araçlara bağlayın
Asistanınızın kaydettiği her müşteri adayı, aldığı her randevu ve tamamladığı her çağrı; imzalı bir webhook ile saniyeler içinde CRM'inize, otomasyon platformunuza veya kendi sisteminize ulaşır. Yeniden deneme ve teslimat kaydı dahil.
Dışarı gönderme, içeri okuma, gömme
Gönderme: olaylar TalkOmni'den çıkar
Bir projede bir şey olduğunda, imzalı bir JSON olayını uç noktanıza POST ederiz. n8n, Make, Zapier ve kendi sisteminizin tükettiği şey budur.
Okuma: verileriniz görüşmenin içinde
Asistan, görüşmenin ortasında bir kaydı okumak, uygunluk sorgulamak veya talep açmak için sizin sisteminizi çağırır. Beyaz listeli, parametreleri doğrulanmış ve denetim kaydına yazılmış olarak.
Gömme: temsilcileriniz kendi panelinizden çıkmaz
SSO derin bağlantısı, sizin sisteminizde zaten giriş yapmış bir kullanıcıyı ikinci bir giriş olmadan doğrudan bir TalkOmni ekranına düşürür. Pro'dan itibaren dâhil.
Webhook kabul eden her platformla çalışır
İki tarafta da eklenti yok. Aracınızda bir gelen webhook oluşturur, adresini TalkOmni paneline yapıştırır, istediğiniz olayları işaretlersiniz; sonraki eşleşen işlem size iletilir.
n8n
Bir Webhook tetikleyicisi ekleyin, production adresini TalkOmni'ye girin ve X-Talkomni-Event başlığına göre dallanın. Kendi sunucunuzda da bulutta da çalışır; adresin HTTPS üzerinden erişilebilir olması yeterli.
Veriyi işlemeden önce imzayı bir kod adımında doğrulayın: adresin kendisi kimlik doğrulama değildir.
Make
Özel webhook size bir adres verir. Adresi TalkOmni'ye yapıştırın ve payload alanlarını sonraki modüllere eşleyin.
Aynı kural: senaryo hiçbir yere yazmadan önce imzayı doğrulayın.
Zapier
Olayı Zapier'ın webhook tetikleyicisiyle yakalayın ve Zapier'ın desteklediği binlerce uygulamadan herhangi birine yönlendirin.
Zapier'ın webhook tetikleyicisi ücretli paketlerinde. Bu bizim değil, onların sınırı.
Kendi sisteminiz
Bir HTTPS uç noktası ve bir HMAC kontrolü; tüm olaylar sizde. Aşağıdaki referans alıcılar entegrasyonun tamamıdır.
Onaylamak için 2xx, geçici olarak kapalıysanız 503 dönün ki yeniden denemeler işini yapabilsin.
Üç adımda bağlayın
- 1
Bir uç nokta açın
Otomasyon aracınızda veya kendi servisinizde POST kabul eden bir HTTPS adresi yayınlayın. Düz http:// ve özel ağ adresleri reddedilir.
- 2
Panelden abone olun
Webhook'lar → adresi ekleyin, isim verin, olayları işaretleyin. İmzalama anahtarı yalnızca oluşturma anında bir kez gösterilir; saklayın, kaybederseniz yenileyin.
- 3
Doğrulayın ve işleyin
İmzayı kontrol edin, teslimat kimliğine göre tekilleştirin, 2xx dönün. Her deneme panelde görünür ve başarısız olan yeniden gönderilebilir.
Gerçekte ne geliyor
Her olay için tek ve değişmeyen bir zarf: kimlik, olay tipi, zaman damgası ve olaya özel payload. event_type üzerinden dallanın; başlıklar aynı tipi ve tekilleştirme yapacağınız teslimat kimliğini taşır.
POST https://your-backend.example.com/talkomni
Content-Type: application/json
X-Talkomni-Event: lead.captured
X-Talkomni-Delivery-Id: 8f1b1c1e-...
X-Talkomni-Signature: t=1785312000,v1=9c4f...e1
{
"id": "8f1b1c1e-...",
"event_type": "lead.captured",
"created_at": "2026-08-06T12:00:00Z",
"payload": {
"lead_id": "0b7a...",
"project_id": "3c92...",
"conversation_id": "a41d...",
"name": "Jane Doe",
"phone": "+905551112233",
"email": "jane@example.com",
"note": "Asked for a quote for 40 seats"
}
}İmzayı doğrulama
Uç noktanız herkese açık, dolayısıyla adresi kimlik doğrulama sayılmaz. Her teslimat, yalnızca sizde ve bizde olan bir anahtarla hesaplanmış HMAC-SHA256 imzası taşır. Doğrulanmayan her isteği reddedin.
Tarif
X-Talkomni-Signature: t=<unix_seconds>,v1=<hex>
v1 = HMAC_SHA256(
key = <your webhook secret>,
message = "<unix_seconds>." + <raw request body>
)- Ham gövde baytlarını imzalayın. Ayrıştırılmış bir JSON'ı yeniden serileştirmek baytları değiştirir ve imza asla tutmaz; entegrasyonda en çok zaman kaybettiren hata budur.
- Sabit zamanlı karşılaştırın (timingSafeEqual, hmac.compare_digest, hash_equals). Düz eşitlik kontrolü cevabı zamanlama üzerinden sızdırır.
- Tekrar penceresi sizin kararınız. Zaman damgasını gönderiyoruz ve bir sınır dayatmıyoruz; birkaç dakikadan eskisini reddedin.
- Anahtarı yenilemek anında geçerli olur, geçiş süresi yoktur. Alıcınızın bu sırada reddettiği teslimatlar reddedilmiş sayılır ve dead-letter'a düşer; kendi tarafınızı hemen güncelleyip düşenleri yeniden gönderin.
import crypto from "node:crypto";
const SECRET = process.env.TALKOMNI_WEBHOOK_SECRET;
// `raw` must be the untouched body bytes. In Express:
// app.post("/talkomni", express.raw({ type: "application/json" }), handler)
export function verify(raw, signatureHeader) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signatureHeader || "");
if (!m) return false;
const [, ts, sig] = m;
// Replay window is yours to pick — we do not impose one. 5 minutes is sane.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${ts}.`)
.update(raw)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(sig, "hex"),
Buffer.from(expected, "hex"),
);
}Olay kataloğu
Bugün dokuz olay. Yalnızca ihtiyacınız olana abone olun; işaretlemediğiniz olaylar için webhook'unuza hiçbir şey gelmez.
| Olay | Ne zaman tetiklenir |
|---|---|
lead.captured | Asistanın capture_lead işlemi bir aday kaydeder ya da TalkOmni formlarınızdan veya landing sayfalarınızdan biri gönderilir. Form gönderimleri ayrıca gönderilen tüm alanları ve ziyaretçinin geldiği reklam attribution bilgisini taşır. |
appointment.booked | Asistan bir randevu oluşturur. |
appointment.cancelled | Panelden bir randevu iptal edilir. |
appointment.rescheduled | Panelden bir randevu başka bir tarihe veya saate alınır. |
appointment.reminder | 24 saatlik veya 1 saatlik hatırlatma gönderilir. Hangisi olduğu payload'da yazar. |
appointment.review | Ziyaret sonrası değerlendirme talebi gönderilir. |
voice.call.completed | Bir sesli çağrı biter ve raporu işlenir: süre, bitiş nedeni, özet ve yapılandırılmış çıktı analiziniz. |
handoff.requestedAPI erişimi | Bot bir görüşmeyi bir insana devreder; böylece kendi operasyon sisteminiz API üzerinden devralabilir. |
member.joined | Yeni bir üye organizasyonunuza gelen daveti kabul eder. |
handoff.requested yalnızca API erişimi hakkı olan organizasyonlar için gönderilir (Enterprise veya API erişimi ek paketi); diğer tüm olaylar her pakette kullanılabilir. Alan alan payload şemaları geliştirici referansındadır.
Teslimat kuralları
- Artan aralıklarla yeniden deneme
- 408, 429, tüm 5xx ve iletişim hataları yeniden denenir: en fazla beş deneme, aralarında 5 dakika, 30 dakika, 2 saat ve 12 saat bekleyerek. Sonuncusundan sonra teslimat dead-letter olarak bekletilir.
- Diğer 4xx'ler kesindir
- 400 veya 404, "bu veriyi reddediyorum" demektir; hemen dururuz. Yalnızca geçici olarak kapalıysanız 503 dönün.
- En az bir kez, yani tekilleştirin
- Aynı teslimat birden fazla kez gelebilir. X-Talkomni-Delivery-Id yeniden denemeler boyunca sabittir; idempotency'nizi ona bağlayın.
- Her deneme kayıtlı
- Panel her denemeyi yanıt koduyla ve gönderilen payload ile gösterir; her teslimat elle yeniden gönderilebilir.
- Adres başına dakikada 100
- Tek bir uç noktaya teslimatlar sınırlandırılır. Sınırın üstünde teslimat bir sonraki pencereye ertelenir; bu bir yeniden deneme hakkı harcamaz.
- Yalnızca HTTPS, her seferinde kontrollü
- Düz http:// reddedilir ve sunucu adı her teslimatta yeniden çözümlenir; DNS'i sonradan özel bir adrese dönen uç nokta teslimat almayı bırakır.
Temsilcileriniz kendi panelinizden çıkmaz
Gönderme ve okuma veriyi taşır. Bu yön insanı taşır: sizin backend'iniz, sisteminizde zaten giriş yapmış bir kullanıcı için tek kullanımlık bir bağlantı üretir ve o bağlantı ikinci bir giriş olmadan, yönetecekleri bir parola olmadan bir TalkOmni ekranını açar.
- Bağlantı tek kullanımlıktır ve iki dakikada geçersizleşir. Açtığı oturum 8 saat sürer ve yenileme jetonu yoktur; siz kendi tarafınızda birini çıkardığınızda TalkOmni erişimi de o günün içinde biter.
- Kullanıcı ilk gönderdiğinizde oluşturulur. Kimlik, e-postaya değil sizin external_user_id değerinize göre eşleşir ve organizasyonunuz dışındaki bir hesaba ait e-posta reddedilir.
- Oturum her zaman o tek projenin temsilcisidir; ne gönderirseniz gönderin asla sahip veya yönetici olmaz. target yolunu geçerek kişiyi tam olarak istediğiniz ekrana düşürebilirsiniz.
- Pro ve Enterprise'a dâhil. Tam API erişimi gerektirmeyen tek API rotası budur ve kullandığı anahtar yalnızca sso:write kapsamını taşır.
# Your backend, for a user already logged into YOUR panel.
curl -X POST https://api.talkomni.com/v1/projects/<project_id>/sso/link \
-H "X-API-Key: $TALKOMNI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "ops-4471",
"email": "ayse@musteri.com",
"name": "Ayşe Y.",
"target": "/dashboard/inbox?conversation=123"
}'
# 201 — redirect the person to url. Single-use, 2 minutes.
{
"url": "https://talkomni.com/api/auth/sso?t=6f1c...9ab",
"expires_in": 120,
"expires_at": "2026-08-06T12:02:00Z"
}Yukarıdaki handoff.requested olayıyla birlikte kullanın: uyarıyı kendi paneliniz gösterir, bağlantı da tam o görüşmeyi açar.
Sorular
- Zapier veya Make'te hazır uygulamanız var mı?
- Bugün yok; yapmadığımız şeyin logosunu koymaktansa bunu söylemeyi tercih ederiz. Elimizde olan, o platformların her birinin kendi hazır webhook tetikleyicisiyle tükettiği imzalı webhook. Hazır dizin uygulamalarını, müşteriler belirli birini istediğinde yaparız.
- Hangi pakete ihtiyacım var?
- Giden webhook'lar tüm paketlerde var; sahip veya yönetici panelde Webhook'lar altından kurar. Yalnızca handoff.requested, dış gelen kutusu API'sine ait olduğu için API erişimi hakkı ister.
- Canlıya almadan nasıl test ederim?
- Webhook'u otomasyon aracınızın test adresine yönlendirin ve olayı gerçekten tetikleyin: widget'tan bir aday kaydedin ya da randevu alın. Her deneme, uç noktanızın döndüğü yanıt koduyla birlikte panelde görünür.
- Anahtarı yenilersem ne olur?
- Yeni anahtar bir sonraki teslimattan itibaren geçerlidir ve eskisi doğrulamayı bırakır. Geçiş süresi yoktur; alıcınızı hemen güncelleyin ve arada başarısız olanları yeniden gönderin.
- Uç noktam bir gün kapalı kalırsa ne olur?
- Yeniden deneme merdiveni yaklaşık on beş saati kapsar. Son denemeden sonra hâlâ başarısız olan teslimat silinmez, dead-letter olarak bekler; döndüğünüzde panelden yeniden gönderirsiniz.
- Olaylar sırayla mı iletilir?
- Hayır. Yeniden denemeler ve paralel teslimat nedeniyle sıra garanti edilmez. Her olayı bağımsız kabul edin, sıra önemliyse payload'daki zaman damgalarını kullanın.
Tüm payload şemaları, REST API ve tool gateway: geliştirici referansı