Integro Barleti AI në website-in tënd

1. Si funksionon

Ka dy mënyra integrimi. Shumica e website-eve kanë nevojë vetëm për të parën.

Widget-i hap chat-in zyrtar të Barleti AI në një dritare të izoluar (iframe). Stilet e website-it tuaj nuk ndikojnë te chat-i dhe chat-i nuk ndikon te faqja juaj. Vizitori merr përgjigje nga burimet zyrtare të universitetit, me referenca, pyetje të shpeshta, historik bisedash dhe zgjedhje gjuhe (shqip/anglisht).

2. Para se të filloni

Kërkojini administratorit të Barleti AI të krijojë një integrim për website-in tuaj. Për këtë i duhen:

• Emri i website-it (p.sh. "Faqja e Fakultetit të Drejtësisë").
• Të gjitha domain-et ku do të shfaqet chat-i: prodhimi, staging dhe mjedisi lokal i zhvillimit, p.sh. https://fdrejtesi.umb.edu.al, staging.fdrejtesi.umb.edu.al, localhost:3000. Chat-i shfaqet vetëm në domain-et e regjistruara.

Do të merrni:

• Çelësin publik pk_…. Mund të shfaqet lirshëm në HTML, sepse punon vetëm nga domain-et tuaja.
• Çelësin sekret sk_…, vetëm nëse do të përdorni API-n nga serveri. Mbajeni si fjalëkalim.

3. Hapi 1 - Widget-i

Ngjitni këtë rresht në HTML-në e çdo faqeje ku doni chat-in. Vendi më i mirë është menjëherë para </body>:

<script src="{{BASE}}/widget.js" data-key="{{KEY}}" async></script>

Kaq. Rifreskoni faqen: në cep poshtë djathtas del butoni i Barleti AI, dhe klikimi hap chat-in.

4. Udhëzime sipas platformës

Zgjidhni teknologjinë e website-it tuaj:

• HTML / PHP
• WordPress
• React / Next.js
• Vue / Nuxt
• Angular
• Laravel
• ASP.NET
• Wix / Webflow / Squarespace

    ...
    <script src="{{BASE}}/widget.js" data-key="{{KEY}}" async></script>
  </body>
</html>

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="sq">
      <body>
        {children}
        <Script src="{{BASE}}/widget.js" data-key="{{KEY}}" strategy="lazyOnload" />
      </body>
    </html>
  );
}

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { src: "{{BASE}}/widget.js", "data-key": "{{KEY}}", async: true, tagPosition: "bodyClose" }
      ]
    }
  }
});

  <app-root></app-root>
  <script src="{{BASE}}/widget.js" data-key="{{KEY}}" async></script>
</body>

{{-- .env: BARLETI_AI_KEY={{KEY}} --}}
    <script src="{{BASE}}/widget.js" data-key="{{ env('BARLETI_AI_KEY') }}" async></script>
</body>

    <script src="{{BASE}}/widget.js" data-key="{{KEY}}" async></script>
    @await RenderSectionAsync("Scripts", required: false)
</body>

5. Personalizimi

Pamja e widget-it ndryshohet me atribute te <script>. Të gjitha janë opsionale:

Shembull: butoni në të majtë, me ngjyrën e fakultetit, chat-i në anglisht:

<script src="{{BASE}}/widget.js" data-key="{{KEY}}"
        data-position="left" data-color="#0055A4" data-lang="en" async></script>

Në celular, chat-i hapet automatikisht në ekran të plotë.

6. Kontrolli nga JavaScript

Pasi ngarkohet, widget-i krijon objektin global window.BarletiAI:

Shembull: buton në faqen e pranimeve që pyet drejtpërdrejt:

<button type="button" onclick="window.BarletiAI && BarletiAI.ask('Cilat janë afatet e aplikimit për Master?')">
  Pyet për afatet e aplikimit
</button>

7. Chat brenda faqes (pa buton lundrues)

Nëse doni chat-in si pjesë të faqes, p.sh. te "Kontakt" ose "Ndihmë", përdorni modalitetin inline. Chat-i vendoset brenda elementit të treguar me data-target:

<div id="barleti-ai"></div>

<script src="{{BASE}}/widget.js" data-key="{{KEY}}"
        data-mode="inline" data-target="#barleti-ai" data-height="600px" async></script>

data-height pranon px, vh ose %. Gjerësia merr 100% të elementit.

8. API REST (v1)

Përdoreni API-n nëse doni ndërfaqen tuaj (p.sh. aplikacion celular, chatbot në një platformë tjetër, sistem i brendshëm). Dokumentimi interaktiv, ku çdo endpoint mund të provohet, është te {{BASE}}/api/docs.

Autentikimi

Endpoint-et

URL bazë: {{BASE}}/api/v1

message pranon deri në 600 karaktere. Për të vazhduar të njëjtën bisedë, dërgoni conversationId nga përgjigjja e mëparshme. Chat-i e mban mend kontekstin, kështu që pyetje vijuese si "po për master?" funksionojnë.

Shembuj

• cURL
• Node.js
• PHP
• Python
• JavaScript (shfletues)

curl -X POST {{BASE}}/api/v1/chat \
  -H "Authorization: Bearer sk_JUAJ_CELESI_SEKRET" \
  -H "X-Visitor-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{"message": "Si regjistrohem në programin Master?"}'

// Node 18+ (fetch i integruar). Çelësi nga variablat e mjedisit, jo në kod.
async function askBarleti(message, userId, conversationId) {
  const res = await fetch("{{BASE}}/api/v1/chat", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BARLETI_AI_SECRET}`,
      "X-Visitor-Id": String(userId),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message, conversationId }),
  });
  if (!res.ok) throw new Error((await res.json()).error);
  return res.json(); // { conversationId, answer, citations, status, ... }
}

<?php
$ch = curl_init("{{BASE}}/api/v1/chat");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("BARLETI_AI_SECRET"),
        "X-Visitor-Id: " . $userId,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode(["message" => "Ku ndodhet universiteti?"]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data["answer"];

import os, requests

r = requests.post(
    "{{BASE}}/api/v1/chat",
    headers={
        "Authorization": f"Bearer {os.environ['BARLETI_AI_SECRET']}",
        "X-Visitor-Id": "user-123",
    },
    json={"message": "Çfarë bursash ofron universiteti?"},
    timeout=60,
)
r.raise_for_status()
print(r.json()["answer"])

// ID e qëndrueshme e pajisjes, që historiku të ruhet ndërmjet vizitave
const visitorId = localStorage.getItem("barleti-visitor") || crypto.randomUUID();
localStorage.setItem("barleti-visitor", visitorId);

const res = await fetch("{{BASE}}/api/v1/chat", {
  method: "POST",
  headers: {
    "X-Barleti-Key": "{{KEY}}",
    "X-Visitor-Id": visitorId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Si aplikoj për Erasmus?" }),
});
const data = await res.json();

Përgjigjja

{
  "conversationId": 62,
  "userMessageId": 427,
  "assistantMessageId": 428,
  "answer": "Për t'u regjistruar në programet Master ... (tekst Markdown)",
  "status": "ANSWERED",
  "citations": [
    { "label": "Universiteti Barleti - Pranimet Master", "url": "https://www.umb.edu.al/..." }
  ]
}

• answer është në Markdown (lista, bold, lidhje). Shfaqeni me një renderues Markdown.
• status: ANSWERED, ose UNANSWERED kur burimet zyrtare nuk e mbulojnë pyetjen.
• citations: burimet zyrtare të përdorura. url mund të jetë null për dokumente të brendshme.
• assistantMessageId përdoret për feedback (POST /messages/{id}/feedback).

Gabimet

Çdo gabim kthehet si {"error": "mesazh në shqip"}:

9. Siguria & privatësia

• Çelësi publik (pk_…) mund të shihet në HTML. Nuk mund të përdoret në domain të tjera, dhe shfletuesi e bllokon chat-in jashtë listës së regjistruar.
• Çelësi sekret (sk_…) mbahet vetëm në server, në variabla mjedisi, jo në kod të publikuar apo në Git. Nëse rrjedh, kërkoni menjëherë një çelës të ri. I vjetri çaktivizohet në çast.
• Widget-i nuk vendos cookie në domain-in tuaj dhe nuk lexon asgjë nga faqja juaj. Chat-i funksionon i izoluar në iframe dhe ruan vetëm një ID të rastësishme pajisjeje, për historikun e bisedave.
• Pyetjet përpunohen sipas Politikës së Privatësisë së Barleti AI. Nëse website-i juaj ka politikë cookie/privatësie, përmendni që përdor asistentin e Universitetit Barleti.
• Nëse website-i juaj përdor Content-Security-Policy, lejoni serverin e Barleti AI:
  Kopjo

  script-src ... {{BASE}};
  frame-src  ... {{BASE}};
  connect-src ... {{BASE}};   (vetëm nëse përdorni API-n nga shfletuesi)

10. Zgjidhja e problemeve

11. Ndihmë

Për çelësa, domain-e të reja ose probleme teknike, kontaktoni administratorin e Barleti AI: [email protected]. Në email tregoni emrin e website-it, domain-in dhe, nëse ka, mesazhin e gabimit nga Console.