API për zhvilluesit

Përditësuar më 13.11.2026

Shkarko si PDF

Me API-në e Replivo e lidhni chat-in me sistemin tuaj të punës (backoffice, CRM): merrni mesazhet e vizitorëve sapo shkruhen dhe u përgjigjeni nga programi juaj. Përgjigjja i shfaqet vizitorit në dritaren e chat-it, njësoj si nga paneli.

Si funksionon

1. Krijoni një çelës API te Cilësimet → API dhe integrime.
2. Vendosni adresën e webhook-ut tuaj: Replivo i dërgon aty çdo mesazh të ri të vizitorit.
3. Përgjigjuni duke thirrur API-në me çelësin tuaj.
4. Dërgoni rregullisht sinjalin e pranisë, që widget-i t'ju tregojë online.

Autentikimi

Çdo kërkesë mban çelësin në kokën Authorization. Çelësi është sekret: përdoreni vetëm nga serveri juaj, kurrë nga kodi i një faqeje web. Një çelës i hequr ndalon së punuari brenda një minute.

Authorization: Bearer rpl_…

Adresa bazë: https://developer.replivochat.com/api/v1

Përgjigjet janë JSON: të dhënat te fusha data, gabimet te fusha error me code dhe message.

curl https://developer.replivochat.com/api/v1/me \
  -H "Authorization: Bearer rpl_…"

Pikat e hyrjes

Shembull: përgjigje te një vizitor

curl -X POST https://developer.replivochat.com/api/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer rpl_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "Po, e kemi në stok.", "agentName": "Arta"}'

Dërgimi i një skedari (përmbajtja e koduar në base64)

curl -X POST https://developer.replivochat.com/api/v1/conversations/CONVERSATION_ID/files \
  -H "Authorization: Bearer rpl_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "oferta.pdf", "contentType": "application/pdf", "dataBase64": "JVBERi0xLjQK…"}'

Prania

Widget-i tregon “Online” vetëm kur dikush mund të përgjigjet. Nëse përgjigjeni vetëm nga sistemi juaj, thirreni këtë rregullisht (p.sh. çdo minutë) sa kohë operatorët tuaj janë në punë. Kur sinjali ndalon, widget-i kalon vetë në formularin e mesazheve pasi mbaron afati.

curl -X PUT https://developer.replivochat.com/api/v1/presence \
  -H "Authorization: Bearer rpl_…" \
  -H "Content-Type: application/json" \
  -d '{"online": true, "ttlSeconds": 120}'

Webhooks

Vendosni adresën te Cilësimet → Biznesi → Webhook URL. Duhet të jetë https. Replivo dërgon një kërkesë POST për çdo ngjarje:

Shembull i trupit për message.created

{
  "id": "0b1f…",
  "event": "message.created",
  "workspaceId": "…",
  "createdAt": "2026-11-13T17:40:00.000Z",
  "data": {
    "conversationId": "…",
    "messageId": "…",
    "siteId": "…",
    "from": "visitor",
    "text": "A e keni produktin në stok?",
    "attachments": [],
    "visitor": { "id": "…", "name": "Besa", "email": "besa@example.com" },
    "createdAt": "2026-11-13T17:40:00.000Z"
  }
}

Verifikimi i nënshkrimit

Krijoni një sekret nënshkrimi te Cilësimet → API dhe integrime. Çdo kërkesë mban atëherë kokën X-Replivo-Signature me kohën t dhe nënshkrimin v1 = HMAC-SHA256 i vargut “t.trupi” me sekretin tuaj. Refuzoni kërkesat me nënshkrim të gabuar ose me kohë më të vjetër se pesë minuta.

// Node.js (Express): use the raw request body, not the parsed JSON
const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Për t'u ditur

• Çdo njoftim dërgohet menjëherë. Përgjigjuni brenda 5 sekondash me një kod 2xx; përndryshe ridërgohet pas 1 minute, 5 minutash, 30 minutash, 2 orësh dhe 12 orësh, pastaj shënohet i dështuar.
• Fusha id është e njëjtë në çdo ridërgim: përdoreni për të mos e përpunuar të njëjtën ngjarje dy herë.
• Regjistri i dërgimeve duket te Cilësimet dhe te /webhooks/deliveries, dhe mbahet rreth 7 ditë.
• Kufiri është rreth 240 kërkesa në minutë për çelës. Mbi të kthehet 429.
• Përgjigjja në një bisedë të mbyllur kthen 409: rihapeni më parë.
• Përgjigjja e parë nga API e merr bisedën, njësoj si në panel.

Kodet e gabimeve

Për pyetje teknike na shkruani në info@replivochat.com.