Referenca API

REST API za nadzorno ploščo HelpStack, widget in webhooks.

Hitre dejstvice#

Pričakujte 404 na /api samem in 401 na avtenticiranih končnih točkah. Na goli poti https://helpstack.eu/api ni nobene usmeritve — zahtevo vrne 404 po zasnovi, ker je API nabor podpoti (/api/conversations, /api/channels, …), ne pa brskljiva korenina. Odpiranje prave končne točke, kot je /api/conversations, v brskalniku vrne 401 (brez piškotka seje), kar potrjuje, da obstaja in je zaščitena z avtentikacijo. Nobeden od odgovorov ni napaka.

Model avtentikacije — preberite najprej#

Trenutno ni javnega sistema z API-ključem ali žetonom za zunanje klicatelje. Ne iščite "API ključa" — ne obstaja. API nadzorne plošče/interno je avtenticiran s piškotkom seje NextAuth prijavljenega uporabnika, vsaka zahteva pa je s posredniško programsko opremo (withOrganization / withAdmin / withAgent) samodejno omejena na organizacijo tega uporabnika. Te končne točke uporablja UI nadzorne plošče HelpStack.

Za klicanje končnih točk nadzorne plošče zunaj brskalnika morate predvajati avtenticiran piškotok seje. Če potrebujete dostop med stroji, so podprte javne površine:

• Končne točke widgeta — javne, omejene po hitrosti na IP/obiskovalca (glejte Vgraditev widgeta).
• Končne točke webhooks — javne, preverjene z žetonom + podpisom HMAC (glejte Webhooks).

Vse, kar zahteva piškotok seje, obravnavajte kot "preverite pri svoji namestitvi" za programatično uporabo.

Ovojnica odgovora#

Vse API poti vračajo standardno ovojnico.

Uspeh

{ "success": true, "data": { } }

Napaka

{
  "success": false,
  "error": {
    "message": "Human-readable message",
    "code": "OPTIONAL_CODE",
    "fields": { "fieldName": ["error 1"] }
  }
}

code in fields sta neobvezna. fields je zapolnjen pri napakah preverjanja (Zod) s sporočili za posamezno polje.

Kode napak in HTTP status#

Napake ustvarja tipizirani razredi napak in centralni upravljalnik. Pregled na visoki ravni:

Napake pri preverjanju Zod vrnejo 400 s code: "VALIDATION_ERROR" in objektom fields. Nepričakovane napake vrnejo 500 z generičnim sporočilom ("An unexpected error occurred"); dejanske podrobnosti so zabeležene samo na strežniku.

Katalog končnih točk#

Vloge: končna točka označena z ADMIN zahteva skrbnika (withAdmin), AGENT zahteva agenta ali višje (withAgent), Seja zahteva katerega koli avtenticiranega člana organizacije (withOrganization).

Kanali

Ustvari kanal — POST /api/channels (preverjena vsebina, createChannelSchema):

{
  "type": "WEBSITE_CHAT",
  "name": "Website Chat",
  "region": "eu",
  "defaultLanguage": "en",
  "autoTranslate": true,
  "translateToLanguage": "en",
  "fallbackLanguage": "sl",
  "aiProviderId": "PROVIDER_ID",
  "credentials": {},
  "responseTemplate": {},
  "autoReply": false,
  "autoApprove": false,
  "autoEnhance": false
}

Oblike poverilnic za vrsto kanala (credentials) se preverjajo ločeno — npr. E-pošta zahteva { host, port, username, password, from, secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned? }; Facebook zahteva { pageId, accessToken, appSecret? }; Instagram zahteva { accountId, accessToken }. Poverilnice so shranjene šifrirano (AES-256-GCM).

Pogovori

Vrednosti filtra status: OPEN | PENDING | CLOSED | ARCHIVED. pageSize je omejen na 100 (privzeto 20).

Pošlji sporočilo — POST /api/conversations/[id]/messages (preverjena vsebina, sendMessageSchema):

{
  "conversationId": "CONVERSATION_ID",
  "content": "Thanks for reaching out — here's how to fix that.",
  "attachments": ["storage/path/file.png"]
}

Obnašanje: sporočilo je ustvarjeno kot OUTBOUND. Če ima kanal vklopljeno autoTranslate in je znan jezik stranke, je sporočilo ustvarjeno neodobreno in prevedeno v ozadju (agent odobri pred pošiljanjem). Pošiljanje porabi žetone načrta; če organizacija nima žetonov, pot vrne 402 s code: "INSUFFICIENT_TOKENS". Ob uspehu vrne ustvarjeno sporočilo s HTTP 201.

Sporočila

Pogosta vprašanja

Mediji

Obvestila

AI ponudniki

Orodja agenta

Glejte Orodja agenta po meri za celotno anatomijo orodja.

Widget (javno)

Glejte Vgraditev widgeta za koristne obremenitve.

Webhooks (javno)

Glejte Webhooks za podrobnosti o rokovanju in podpisu.

Sorodne teme#

• Vgraditev widgeta
• Webhooks
• E-poštni kanal
• Orodja agenta po meri
• Navodila za kanale
• Slovar