Geliştirici API Rehberi

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.

Webhook URL Kimlik Doğrulama
REST JSON API
CORS Enabled
01

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/json

Nasıl Çalışır?

1Kullanıcı web sitenizde chat widget'ınıza bir mesaj yazar
2Widget'ınız bu mesajı UppyPro Webhook URL'sine POST isteği olarak gönderir
3UppyPro AI asistanı mesajı işler ve JSON response olarak yanıt döner
4Widget'ınız bu yanıtı alır ve kullanıcıya gösterir
5İnsan temsilci devralırsa, yanıtları GET ile çekebilirsiniz (polling)
02

Kimlik Doğrulama (Webhook URL)

Widget'ınızı tanıtmak için Webhook URL kullanımı

Webhook URL Nereden Alınır?

UppyPro Panel → AyarlarWeb 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:

Endpoint Yapısı
url
POST {WEBHOOK_URL}
GET  {WEBHOOK_URL}?session_id={SESSION_ID}

Örnek:
POST https://www.upgunai.com/api/webhooks/webchat/wc_abc123xyz789
03

Mesaj Gönderme (POST)

Widget'tan AI asistana mesaj iletme

Request Body (JSON)

ParametreTipZorunluAçıklama
session_id
Alternatif: chatId, sessionId
string✅ EvetHer ziyaretçi oturumu için benzersiz ID. Aynı session_id ile gelen mesajlar aynı konuşmada gruplanır.
message
Alternatif: text, input, chatInput, content
string✅ EvetKullanıcının gönderdiği mesaj metni. Maksimum 2000 karakter.
visitor_name
Alternatif: name, userName
string❌ HayırZiyaretçinin adı. UppyPro panelinde konuşma kartında görünür.
visitor_email
Alternatif: email
string❌ HayırZiyaretçinin e-posta adresi. CRM müşteri kartı oluşturmak için kullanılır.
visitor_phone
Alternatif: phone
string❌ HayırZiyaretç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.

Örnek POST İsteği
curl
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"
  }'
04

Yanıt Formatı

AI asistandan dönen response yapısı

Başarılı Yanıt (200 OK)
json
{
  "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"
    }
  ]
}
AlanTipAçıklama
output / text / replystringAI asistanın yanıt metni. Üçü de aynı değeri döner — widget'ınıza uygun olanı kullanın.
successbooleanİstek başarılı mı? true ise yanıt geçerlidir.
conversation_idstringKonuşmanın benzersiz ID'si. Loglama ve hata ayıklama için kullanabilirsiniz.
modestring"ai" = AI yanıtladı, "human" = İnsan temsilci devrede, "error" = Hata oluştu.
imagesarrayAI'ı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.

05

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.

Görsel Gönderme Örneği
javascript
// 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.

06

Konuşma Geçmişini Çekme (GET)

Mevcut oturumdaki mesaj geçmişini alma

GET İsteği
curl
curl -X GET \
  "WEBHOOK_URL_BURAYA?session_id=visitor_abc123"
Yanıt Formatı
json
{
  "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).

07

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.

Polling Implementasyonu
javascript
// 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);
  }
}
08

Hata Kodları

API'nin döndürdüğü HTTP durum kodları

KodDurumAçıklamaÇözüm
200OKİstek başarılı, AI yanıtı döndü
400Bad RequestGeçersiz JSON, eksik session_id veya messageRequest body'yi kontrol edin
403ForbiddenGeçersiz Webhook URL veya webchat devre dışıWebhook URL'nizi kontrol edin, panelden webchat'i aktif edin
429Too Many RequestsRate limit aşıldı (20 istek/dakika)İstekler arasında bekleme süresi ekleyin
500Server ErrorSunucu hatasıTekrar deneyin, devam ederse destek ekibiyle iletişime geçin
09

Rate Limiting

API kullanım limitleri

20
istek / dakika
IP başına
2000
karakter / mesaj
Metin mesajları
5 MB
maks. dosya boyutu
Görsel yüklemeleri
10

Örnek Kodlar

Farklı dillerde implementasyon örnekleri

JavaScript (Fetch API)
javascript
// 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);
  }
}
Python (requests)
python
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 (cURL)
php
<?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ı?");
?>
11

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.

Minimal Chat Widget (HTML + JS)
html
<!-- 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>
12

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.

Web sitenize özel chat widget tasarımı ve kodlaması
Mevcut chatbot'unuzun UppyPro API'sine bağlanması
Polling mekanizması ve görsel render implementasyonu
Test ve hata ayıklama desteği

Aşağıdaki iletişim kanallarından bize ulaşın, teknik ekibimiz en kısa sürede size geri dönüş yapacaktır.