Web Chat API Entegrasyonu
Kendi web chat widget'ınızı UppyPro AI asistanına bağlayın. REST API ile mesaj gönderin, AI yanıtları alın, görsel paylaşın ve konuşma geçmişini çekin.
Genel Bakış
API yapısı ve temel kavramlar
Bu Rehber Kimler İçin?
Web sitenize zaten bir chat widget'ı entegre ettiyseniz veya kendi özel widget'ınızı geliştirmek istiyorsanız, bu rehber widget'ınızı UppyPro AI asistanına bağlamanız için ihtiyacınız olan tüm bilgileri içerir.
Base URL
https://www.upgunai.com/api/webhooks/webchat/Content Type
application/jsonNasıl Çalışır?
Kimlik Doğrulama (Webhook URL)
Widget'ınızı tanıtmak için Webhook URL kullanımı
Webhook URL Nereden Alınır?
UppyPro Panel → Ayarlar → Web Chat Ayarları bölümünden işletmenize özel Webhook URL'nizi bulabilirsiniz. Web Chat özelliğinin aktif olduğundan emin olun.
Panelden aldığınız Webhook URL'sini doğrudan kullanabilirsiniz. Ayrı bir header veya API anahtarı göndermenize gerek yoktur:
POST {WEBHOOK_URL}
GET {WEBHOOK_URL}?session_id={SESSION_ID}
Örnek:
POST https://www.upgunai.com/api/webhooks/webchat/wc_abc123xyz789Mesaj Gönderme (POST)
Widget'tan AI asistana mesaj iletme
Request Body (JSON)
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
session_idAlternatif: chatId, sessionId | string | ✅ Evet | Her ziyaretçi oturumu için benzersiz ID. Aynı session_id ile gelen mesajlar aynı konuşmada gruplanır. |
messageAlternatif: text, input, chatInput, content | string | ✅ Evet | Kullanıcının gönderdiği mesaj metni. Maksimum 2000 karakter. |
visitor_nameAlternatif: name, userName | string | ❌ Hayır | Ziyaretçinin adı. UppyPro panelinde konuşma kartında görünür. |
visitor_emailAlternatif: email | string | ❌ Hayır | Ziyaretçinin e-posta adresi. CRM müşteri kartı oluşturmak için kullanılır. |
visitor_phoneAlternatif: phone | string | ❌ Hayır | Ziyaretçinin telefon numarası. CRM müşteri eşleştirmesi için kullanılır. |
💡 session_id İpuçları: Her tarayıcı oturumu için benzersiz bir ID oluşturun.crypto.randomUUID() veyaDate.now() + Math.random() kullanabilirsiniz. Aynı session_id ile gönderilen mesajlar aynı konuşma altında gruplanır.
curl -X POST \
"WEBHOOK_URL_BURAYA" \
-H "Content-Type: application/json" \
-d '{
"session_id": "visitor_abc123",
"message": "Yarın akşam 4 kişilik masa var mı?",
"visitor_name": "Ahmet Yılmaz",
"visitor_email": "ahmet@example.com",
"visitor_phone": "+905551234567"
}'Yanıt Formatı
AI asistandan dönen response yapısı
{
"output": "Merhaba Ahmet Bey! 🌟 Yarın akşam...",
"text": "Merhaba Ahmet Bey! 🌟 Yarın akşam...",
"reply": "Merhaba Ahmet Bey! 🌟 Yarın akşam...",
"success": true,
"conversation_id": "uuid-conversation-id",
"mode": "ai",
"images": [
{
"url": "https://storage.example.com/photo.jpg",
"caption": "📸 VIP Masa - Teras"
}
]
}| Alan | Tip | Açıklama |
|---|---|---|
output / text / reply | string | AI asistanın yanıt metni. Üçü de aynı değeri döner — widget'ınıza uygun olanı kullanın. |
success | boolean | İstek başarılı mı? true ise yanıt geçerlidir. |
conversation_id | string | Konuşmanın benzersiz ID'si. Loglama ve hata ayıklama için kullanabilirsiniz. |
mode | string | "ai" = AI yanıtladı, "human" = İnsan temsilci devrede, "error" = Hata oluştu. |
images | array | AI'ın paylaştığı görseller. Her öğe { url, caption } formatında. Widget'ta img olarak render edin. |
💡 İnsan Temsilci Modu: mode: "human" döndüğünde, AI devre dışıdır ve işletme temsilcisi yanıt verecektir. Bu durumda widget'ınızpolling mekanizması ile yeni mesajları kontrol etmelidir.
Görsel Gönderme
Base64 formatında görsel yükleme
Kullanıcı widget'ınız üzerinden bir görsel gönderdiğinde, görseli base64 formatında message alanına ekleyerek gönderebilirsiniz. UppyPro görseli otomatik olarak yükler ve AI'a iletir.
// Kullanıcının seçtiği dosyayı base64'e çevir
const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];
const reader = new FileReader();
reader.onload = async () => {
const base64Data = reader.result; // "data:image/jpeg;base64,/9j/4AAQ..."
const response = await fetch(WEBHOOK_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
session_id: sessionId,
message: base64Data, // Base64 data URL
visitor_name: "Ahmet Yılmaz"
})
});
const data = await response.json();
// data.output → AI'ın görsel hakkındaki yanıtı
};
reader.readAsDataURL(file);⚠️ Kısıtlamalar: Maksimum dosya boyutu 5MB. Desteklenen formatlar:JPEG, PNG, WebP, GIF. Base64 string data:image/ ile başlamalıdır.
Konuşma Geçmişini Çekme (GET)
Mevcut oturumdaki mesaj geçmişini alma
curl -X GET \
"WEBHOOK_URL_BURAYA?session_id=visitor_abc123"{
"success": true,
"messages": [
{
"role": "user",
"text": "Yarın akşam masa var mı?",
"sender": "CUSTOMER",
"timestamp": "2024-04-09T12:00:00.000Z",
"message_type": "text",
"media_url": null
},
{
"role": "assistant",
"text": "Merhaba! Yarın akşam için birkaç uygun masamız var 🌟",
"sender": "BOT",
"timestamp": "2024-04-09T12:00:02.000Z",
"message_type": "text",
"media_url": null
},
{
"role": "assistant",
"text": "📸 VIP Masa - Teras",
"sender": "BOT",
"timestamp": "2024-04-09T12:00:03.000Z",
"message_type": "image",
"media_url": "https://storage.example.com/photo.jpg"
}
]
}💡 Kullanım Alanı: Sayfa yenilendiğinde veya widget yeniden açıldığında, mevcut session_id ile GET isteği yaparak konuşma geçmişini geri yükleyebilirsiniz. Maksimum 50 mesaj döner (kronolojik sırayla).
Polling Mekanizması
İnsan temsilci yanıtlarını almak için periyodik sorgulama
AI yanıtları POST isteğinin response'unda anında döner. Ancak, bir insan temsilci konuşmayı devralırsa (mode: "human"), temsilcinin yanıtlarını almak için periyodik olarak GET isteği yapmanız gerekir.
// Panelden aldığınız Webhook URL
const WEBHOOK_URL = "https://www.upgunai.com/api/webhooks/webchat/wc_XXXXX";
let lastMessageCount = 0;
let pollingInterval = null;
function startPolling(webhookUrl, sessionId) {
// Her 3 saniyede yeni mesajları kontrol et
pollingInterval = setInterval(async () => {
try {
const res = await fetch(
`${webhookUrl}?session_id=${sessionId}`
);
const data = await res.json();
if (data.success && data.messages.length > lastMessageCount) {
// Yeni mesajlar var — sadece yeni olanları göster
const newMessages = data.messages.slice(lastMessageCount);
newMessages.forEach(msg => {
if (msg.role === "assistant") {
displayMessage(msg.text, "bot", msg.media_url);
}
});
lastMessageCount = data.messages.length;
}
} catch (err) {
console.error("Polling error:", err);
}
}, 3000);
}
function stopPolling() {
if (pollingInterval) {
clearInterval(pollingInterval);
pollingInterval = null;
}
}
// POST yanıtında mode "human" ise polling başlat
async function sendMessage(text) {
const res = await fetch(WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ session_id: sessionId, message: text })
});
const data = await res.json();
displayMessage(data.output, "bot");
if (data.mode === "human" && !pollingInterval) {
startPolling(WEBHOOK_URL, sessionId);
}
}Hata Kodları
API'nin döndürdüğü HTTP durum kodları
| Kod | Durum | Açıklama | Çözüm |
|---|---|---|---|
| 200 | OK | İstek başarılı, AI yanıtı döndü | — |
| 400 | Bad Request | Geçersiz JSON, eksik session_id veya message | Request body'yi kontrol edin |
| 403 | Forbidden | Geçersiz Webhook URL veya webchat devre dışı | Webhook URL'nizi kontrol edin, panelden webchat'i aktif edin |
| 429 | Too Many Requests | Rate limit aşıldı (20 istek/dakika) | İstekler arasında bekleme süresi ekleyin |
| 500 | Server Error | Sunucu hatası | Tekrar deneyin, devam ederse destek ekibiyle iletişime geçin |
Rate Limiting
API kullanım limitleri
Örnek Kodlar
Farklı dillerde implementasyon örnekleri
// Panelden aldığınız Webhook URL'yi buraya yapıştırın
const WEBHOOK_URL = "https://www.upgunai.com/api/webhooks/webchat/wc_XXXXX";
// Oturum ID'si oluştur (tarayıcı başına benzersiz)
const sessionId = localStorage.getItem("chat_session")
|| (() => {
const id = "visitor_" + Date.now() + "_" + Math.random().toString(36).slice(2, 8);
localStorage.setItem("chat_session", id);
return id;
})();
async function sendMessage(userMessage) {
const response = await fetch(WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
session_id: sessionId,
message: userMessage,
visitor_name: "Web Ziyaretçisi"
})
});
const data = await response.json();
if (data.success) {
console.log("AI Yanıtı:", data.output);
// Görseller varsa render et
if (data.images && data.images.length > 0) {
data.images.forEach(img => {
console.log("Görsel:", img.url, "Başlık:", img.caption);
});
}
} else {
console.error("Hata:", data.error);
}
}import requests
import uuid
# Panelden aldığınız Webhook URL'yi buraya yapıştırın
WEBHOOK_URL = "https://www.upgunai.com/api/webhooks/webchat/wc_XXXXX"
session_id = f"py_{uuid.uuid4().hex[:12]}"
def send_message(message: str, name: str = "Web Ziyaretçisi"):
response = requests.post(WEBHOOK_URL, json={
"session_id": session_id,
"message": message,
"visitor_name": name,
})
data = response.json()
if data.get("success"):
print(f"AI: {data['output']}")
# Görselleri kontrol et
for img in data.get("images", []):
print(f"📸 {img['caption']}: {img['url']}")
else:
print(f"Hata: {data.get('error')}")
# Kullanım
send_message("Merhaba, fiyatlarınız hakkında bilgi alabilir miyim?")<?php
// Panelden aldığınız Webhook URL'yi buraya yapıştırın
$webhookUrl = "https://www.upgunai.com/api/webhooks/webchat/wc_XXXXX";
$sessionId = "php_" . bin2hex(random_bytes(6));
function sendMessage($url, $sessionId, $message, $name = "Web Ziyaretçisi") {
$payload = json_encode([
"session_id" => $sessionId,
"message" => $message,
"visitor_name" => $name,
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if ($data["success"]) {
echo "AI: " . $data["output"] . "\n";
// Görseller
foreach ($data["images"] ?? [] as $img) {
echo "📸 " . $img["caption"] . ": " . $img["url"] . "\n";
}
} else {
echo "Hata: " . ($data["error"] ?? "Bilinmeyen") . "\n";
}
}
sendMessage($webhookUrl, $sessionId, "Yarın için müsait odalar var mı?");
?>Tam Widget Örneği
Kopyala-yapıştır hazır minimal chat widget
Aşağıdaki örnek, web sitenize ekleyebileceğiniz minimal bir chat widget'ıdır. Tek bir HTML dosyasına yapıştırarak veya mevcut sayfanıza ekleyerek hemen kullanabilirsiniz.
<!-- UppyPro Web Chat Widget -->
<div id="uppy-chat-widget">
<button id="uppy-chat-toggle" onclick="toggleChat()"
style="position:fixed;bottom:20px;right:20px;width:60px;height:60px;
border-radius:50%;background:#f97316;border:none;cursor:pointer;
box-shadow:0 4px 12px rgba(249,115,22,0.4);z-index:9999;
display:flex;align-items:center;justify-content:center;">
<svg width="28" height="28" fill="white" viewBox="0 0 24 24">
<path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2z"/>
</svg>
</button>
<div id="uppy-chat-box" style="display:none;position:fixed;bottom:90px;
right:20px;width:380px;height:520px;background:white;border-radius:16px;
box-shadow:0 8px 30px rgba(0,0,0,0.15);z-index:9999;
display:flex;flex-direction:column;overflow:hidden;">
<!-- Header -->
<div style="background:#f97316;color:white;padding:16px;
display:flex;align-items:center;gap:10px;">
<div style="width:36px;height:36px;background:rgba(255,255,255,0.2);
border-radius:50%;display:flex;align-items:center;justify-content:center;">
🤖
</div>
<div>
<div style="font-weight:700;font-size:14px;">AI Asistan</div>
<div style="font-size:11px;opacity:0.8;">Çevrimiçi</div>
</div>
<button onclick="toggleChat()" style="margin-left:auto;background:none;
border:none;color:white;font-size:20px;cursor:pointer;">✕</button>
</div>
<!-- Messages -->
<div id="uppy-messages" style="flex:1;overflow-y:auto;padding:16px;
display:flex;flex-direction:column;gap:8px;background:#f8fafc;"></div>
<!-- Input -->
<div style="padding:12px;border-top:1px solid #e2e8f0;display:flex;gap:8px;">
<input id="uppy-input" type="text" placeholder="Mesajınızı yazın..."
onkeypress="if(event.key==='Enter')sendMsg()"
style="flex:1;border:1px solid #e2e8f0;border-radius:24px;
padding:10px 16px;font-size:14px;outline:none;"/>
<button onclick="sendMsg()"
style="background:#f97316;color:white;border:none;border-radius:50%;
width:40px;height:40px;cursor:pointer;font-size:16px;">➤</button>
</div>
</div>
</div>
<script>
// ─── KONFİGÜRASYON ───
// Panelden aldığınız Webhook URL'yi buraya yapıştırın
const UPPY_URL = "https://www.upgunai.com/api/webhooks/webchat/wc_XXXXX";
const SESSION = localStorage.getItem("uppy_sid") || (() => {
const id = "w_" + Date.now() + "_" + Math.random().toString(36).slice(2,8);
localStorage.setItem("uppy_sid", id);
return id;
})();
let chatOpen = false;
function toggleChat() {
chatOpen = !chatOpen;
document.getElementById("uppy-chat-box").style.display = chatOpen ? "flex" : "none";
if (chatOpen) loadHistory();
}
function addBubble(text, role, mediaUrl) {
const container = document.getElementById("uppy-messages");
const bubble = document.createElement("div");
const isUser = role === "user";
bubble.style.cssText = `max-width:80%;padding:10px 14px;border-radius:16px;
font-size:13px;line-height:1.5;word-wrap:break-word;
align-self:${isUser ? "flex-end" : "flex-start"};
background:${isUser ? "#f97316" : "white"};
color:${isUser ? "white" : "#1e293b"};
border:1px solid ${isUser ? "transparent" : "#e2e8f0"};`;
if (mediaUrl) {
bubble.innerHTML = `<img src="${mediaUrl}" style="max-width:100%;
border-radius:8px;margin-bottom:6px;"/><div>${text}</div>`;
} else {
bubble.textContent = text;
}
container.appendChild(bubble);
container.scrollTop = container.scrollHeight;
}
async function sendMsg() {
const input = document.getElementById("uppy-input");
const text = input.value.trim();
if (!text) return;
input.value = "";
addBubble(text, "user");
try {
const res = await fetch(UPPY_URL, {
method: "POST",
headers: {"Content-Type": "application/json"},
body: JSON.stringify({ session_id: SESSION, message: text })
});
const data = await res.json();
if (data.success) {
addBubble(data.output, "assistant");
// Görselleri render et
(data.images || []).forEach(img => addBubble(img.caption, "assistant", img.url));
}
} catch (err) {
addBubble("Bağlantı hatası. Lütfen tekrar deneyin.", "assistant");
}
}
async function loadHistory() {
try {
const res = await fetch(UPPY_URL + "?session_id=" + SESSION);
const data = await res.json();
if (data.success && data.messages.length > 0) {
document.getElementById("uppy-messages").innerHTML = "";
data.messages.forEach(m => addBubble(m.text, m.role, m.media_url));
}
} catch {}
}
</script>Teknik Destek
Entegrasyon yardımı ve yazılım desteği
Yazılım Desteğine mi İhtiyacınız Var?
Web sitenize bir chatbot eklemek istiyorsanız veya mevcut widget'ınızı UppyPro'ya entegre ederken teknik desteğe ihtiyaç duyuyorsanız, UpgunAI teknik ekibi size yardımcı olabilir.
Aşağıdaki iletişim kanallarından bize ulaşın, teknik ekibimiz en kısa sürede size geri dönüş yapacaktır.
