Eylemler: kendi sisteminizden yanıtlar

Bir eylem, botunuzun sohbetin ortasında kendi sisteminizden bir şey sorgulamasını sağlar — bir siparişin nerede olduğu, ne zaman teslim edileceği, bir rezervasyonun onaylanıp onaylanmadığı. Müşteri sorar, bot ihtiyaç duyduğu bilgileri toplar, API'nizi çağırır ve dönen sonuca göre müşterinin dilinde yanıt verir.

Botunuzun çalıştığı her yerde çalışır: web sitesi widget'ı, bot bağlantınız ve QR kodunuz, ayrıca Android, iOS, React Native, Flutter ve Ionic uygulamaları. Hiçbir şey yüklenmez veya güncellenmez — çağrı sunucularımızdan yapılır, bu yüzden API kimlik bilgileriniz asla bir tarayıcıya veya telefona ulaşmaz.

Başlamadan önce: botunuzla herkes sohbet edebilir

Botunuz herkese açık bir sohbettir. Bir siparişi görmek için yalnızca sipariş numarası yeterliyse, herhangi biri biri tutana kadar numara yazabilir.

Bot üç şekilde yardımcı olur, ancak hiçbiri bu kontrolün yerini tutmaz: yalnızca müşterinin gerçekten yazdığı değerleri gönderir, bir sohbetin veya bir adresin yapabileceği sorgu sayısını sınırlar ve yanıtın hangi alanlarını görmesine izin verileceğini siz seçebilirsiniz.

Bir tane kurun

Panelde Eylemler bölümünü açın ve Yeni eylem seçeneğini seçin. Bu ekranı sahipler ve yöneticiler görebilir.

• Ad — sizin için, örneğin "Sipariş durumu".
• Bot bunu ne zaman kullanmalı? — yeni bir iş arkadaşınıza anlatır gibi tek cümle: "Müşteri siparişinin nerede olduğunu veya ne zaman ulaşacağını soruyor."
• API adresiniz — GET veya POST ve bir https:// adresi. Değerin geleceği yere {{order_id}} yazın.
• Botun müşteriden istedikleri — en fazla altı değer. Her birinin kendi kelimelerinizle bir etiketi ("Sipariş numarası"), API'nizin kullandığı adı (order_id) ve bir türü vardır: herhangi bir metin, bir sayı, bir e-posta adresi veya bir telefon numarası.
• Üstbilgiler — API anahtarınız veya belirteciniz. Şifrelenmiş olarak saklanır ve bir daha gösterilmez.
• Botla yalnızca şu alanları paylaş — isteğe bağlı. Yanıtın botun kullanabileceği kısımlarını listeleyin, örneğin status, eta, items[].name. Geri kalan her şey yapay zeka görmeden önce atılır.

Test et düğmesine basın, örnek değerler yazın; gönderilen isteği ve bota tam olarak ne verileceğini görürsünüz. Ardından Test ekranında gerçekten deneyin: "48213 numaralı siparişim nerede? E-postam asha@example.com".

API'nizin aldıkları

GET ile adrese yerleştirdiğiniz değerler doldurulur, geri kalanlar sorgu dizesine eklenir:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

POST ile değerler JSON gövdesidir:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Her istek ayrıca kendi üstbilgilerinizi ve şunları taşır:

Ne göndermeli

8 saniye içinde JSON veya kısa bir düz metin satırıyla yanıt verin.

• Verilerle birlikte 200 — bot bundan yanıt verir. Küçük tutun ve anlaşılır alan adları kullanın: {"status":"shipped","eta":"2 October"} dahili kodlardan daha iyi çalışır.
• Hiçbir şey eşleşmediğinde 404 — bot müşteriye bunu söyler ve yazdıklarını kontrol etmesini ister.
• Başka herhangi bir durum ya da zamanında yanıt gelmemesi — bot özür diler, iletişim bilgilerinizi sunar ve sohbet sizin için işaretlenir. Nedeni Eylemler ekranında gösterilir.

Yönlendirmeler izlenmez ve 256 KB'ı aşan bir yanıt okunmaz.

İmzayı doğrulayın

İstekler Standard Webhooks yöntemiyle imzalanır, bu yüzden mevcut bir kütüphaneyi kullanabilirsiniz. İmzalama gizli anahtarınız Eylemler ekranındadır.

Elle: kimliği, zaman damgasını ve gövdenin tam halini noktalarla birleştirin, bunu gizli anahtarı (whsec_ sonrasındaki kısım, base64 ile çözülmüş) kullanarak HMAC-SHA256 ile imzalayın ve karşılaştırın.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

GET isteğinde gövde boştur, bu yüzden imzalanan metin nokta ile biter. Değerlerin de imza kapsamında olmasını istiyorsanız POST kullanın.

Bot bunu nasıl kullanır

• Eksik olan her şeyi, her seferinde kısa bir soruyla sorar ve müşterinin sohbette daha önce söylediklerini hatırlar.
• Asla bir değeri tahmin etmez. Müşteri yazmadıysa bot sorar.
• Mesaj başına bir sorgu. Kayıtlı yanıtlarınız yine önce gelir; bu yüzden elle yanıtladığınız bir soru asla API'nizi çağırmaz.
• Bir sorgudan gelen yanıtlar asla başka bir müşteri için yeniden kullanılmaz.
• Bir sorgu, yapay zekanın yazdığı diğer yanıtlar gibi bir yanıt olarak sayılır.

Sohbetler bölümünde bir sorgudan gelen yanıtın altında bu belirtilir: hangi eylemin çalıştığı ve nasıl sonuçlandığı. Müşterinin yazdığı değerler yalnızca sohbet dökümünde kalır, başka hiçbir yerde tutulmaz.

Sınırlar

Eylemler bilgi okur. Bir eylemi bir şeyi değiştiren bir adrese yönlendirmeyin — bir siparişi iptal etmek veya iade yapmak, botun henüz sahip olmadığı bir onay adımı gerektirir.