API për zhvilluesit

Përditësuar më 13.11.2026

ReplivoUdhëzues integrimi · www.replivochat.com

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

Krijoni një çelës API te Cilësimet → API dhe integrime.
Vendosni adresën e webhook-ut tuaj: Replivo i dërgon aty çdo mesazh të ri të vizitorit.
Përgjigjuni duke thirrur API-në me çelësin tuaj.
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

Metoda	Shtegu	Çfarë bën
GET	`/me`	Biznesi, çelësi dhe faqet web. E mirë për të provuar çelësin.
GET	`/conversations?status=active`	Lista e bisedave. status: active (parazgjedhje), open, assigned, closed. limit deri në 100.
GET	`/conversations/{id}`	Një bisedë.
GET	`/conversations/{id}/messages`	Mesazhet e bisedës. after (datë ISO) kthen vetëm më të rejat; limit deri në 200.
POST	`/conversations/{id}/messages`	Dërgon një përgjigje te vizitori. Trupi: text, opsionale agentName.
POST	`/conversations/{id}/close`	Mbyll bisedën.
POST	`/conversations/{id}/reopen`	Rihap një bisedë të mbyllur.
GET	`/tickets`	Mesazhet offline (tiketat).
PUT	`/presence`	Ju tregon online në widget. Trupi: online, ttlSeconds (30–600, parazgjedhje 120).

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"}'

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:

`message.created`	Një vizitor shkroi një mesazh (edhe të parin e bisedës).
`conversation.started`	Nisi një bisedë e re.
`ticket.created`	Një vizitor la një mesazh offline.

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

Webhook-u dërgohet një herë dhe nuk përsëritet. Përgjigjuni brenda 5 sekondash me një kod 2xx; për të mos humbur mesazhe, lexoni periodikisht /conversations.
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

`400 invalid_request`	`401 unauthorized`	`403 suspended`
`404 not_found`	`409 conversation_closed`	`429 rate_limited`

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