API czatu na stronie

Oficjalny widżet instalujesz w aplikacji: zobacz Dodanie czatu na swojej stronie. Opcje fragmentu kodu znajdziesz w Ustawieniach czatu na stronie. Ta strona jest dla deweloperów: widget SDK dla własnego formularza i warstwa REST dla własnego interfejsu czatu. Zobacz OpenAPI, tag inbox.

Widget SDKKopiuj link do tej sekcji

Po załadowaniu skryptu widżetu dostępny jest window.TillorInbox. Za jego pomocą przekazujesz dane kontaktowe z własnego formularza (strona kontaktowa, szczegóły ogłoszenia sprzedaży, zapytanie o ofertę). Wszystkie metody czekają, aż konfiguracja widżetu zostanie załadowana.

getVisitor() zwraca ten obiekt:

Użyj getVisitor(), aby wstępnie wypełnić własny formularz z localStorage (ta sama przeglądarka, także po odświeżeniu strony).

Opcje dla setVisitor (drugi argument):

Opcje dla send:

Przy open: false (domyślnie) przycisk czatu pozostaje zamknięty. Wiadomość mimo to trafia do Tillor; Twój własny formularz może podziękować lub pokazać błąd. Przy open: true okno czatu się otwiera, a odwiedzający widzi normalne zachowanie wysyłania (dźwięk, znaczniki, ewentualne błędy widżetu).

Chcesz użyć własnego przycisku zamiast pływającego przycisku czatu? Ustaw data-launcher="false" we fragmencie kodu i wywołaj TillorInbox.open().

metadata (formularz rezerwacji)Kopiuj link do tej sekcji

Użyj metadata, gdy masz na stronie własny formularz, a Tillie ma wysłać wyłącznie potwierdzenie, bez pytań uzupełniających (na przykład dlatego, że karta się potem zamyka).

await TillorInbox.send({
  name: "Jan Janssens",
  email: "jan@voorbeeld.be",
  phone: "+32 3 779 81 64",
  body: structuredBookingMessage,
  silent: true,
  metadata: {
    forceHandover: true,
    handoverIntent: "reservation",
    source: "website_booking_form",
  },
});

Zastąpienie formularza kontaktowego (ciche wysyłanie)Kopiuj link do tej sekcji

Użyj tego, gdy chcesz zachować istniejący formularz kontaktowy, ale kierować wiadomości przez Tillor bez otwierania okna czatu.

<form id="site-contact-form">
  <input name="name" type="text" required />
  <input name="email" type="email" required />
  <input name="phone" type="tel" />
  <textarea name="message" required></textarea>
  <button type="submit">Verstuur</button>
  <p id="contact-status" hidden></p>
</form>

<script>
  document.getElementById("site-contact-form").addEventListener("submit", async (event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const status = document.getElementById("contact-status");
    const data = new FormData(form);

    try {
      await TillorInbox.send({
        name: String(data.get("name") ?? ""),
        email: String(data.get("email") ?? ""),
        phone: String(data.get("phone") ?? ""),
        body: String(data.get("message") ?? ""),
      });
      status.textContent = "Bedankt, we nemen snel contact op.";
      status.hidden = false;
      form.reset();
    } catch (error) {
      status.textContent = error instanceof Error ? error.message : "Versturen mislukt.";
      status.hidden = false;
    }
  });
</script>

Nie musisz ustawiać open ani silent: bez open: true okno pozostaje zamknięte, a Tillor traktuje wywołanie jako ciche wysłanie.

Połączenie formularza kontaktowego (otwarcie czatu)Kopiuj link do tej sekcji

Przekaż pola i otwórz okno czatu, aby odwiedzający zobaczył rozmowę:

<form id="site-contact-form">
  <input name="name" type="text" required />
  <input name="email" type="email" required />
  <input name="phone" type="tel" />
  <textarea name="message" required></textarea>
  <button type="submit">Verstuur</button>
</form>

<script>
  document.getElementById("site-contact-form").addEventListener("submit", (event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const data = new FormData(form);
    void TillorInbox.send({
      name: String(data.get("name") ?? ""),
      email: String(data.get("email") ?? ""),
      phone: String(data.get("phone") ?? ""),
      body: String(data.get("message") ?? ""),
      open: true,
    });
  });
</script>

Albo tylko wypełnij pola i otwórz okno, bez natychmiastowego wysyłania:

void TillorInbox.setVisitor(
  {
    name: "Jan Janssens",
    email: "jan@voorbeeld.be",
    phone: "+32 3 779 81 64",
    message: "Ik heb een vraag over de stacaravan te koop.",
  },
  { markSubmitted: true, open: true },
);

Strona sprzedaży z natychmiastowym wysłaniem i otwarciem czatu:

void TillorInbox.send({
  name: "Jan Janssens",
  email: "jan@voorbeeld.be",
  phone: "+32 3 779 81 64",
  body: "Ik heb interesse in deze stacaravan.",
  open: true,
});

Synchronizacja na żywo, gdy ktoś pisze:

const form = document.getElementById("site-contact-form");
form.addEventListener("input", () => {
  void TillorInbox.setVisitor({
    name: form.name.value,
    email: form.email.value,
    phone: form.phone.value,
    message: form.message.value,
  });
});

Wczesne wywołanie (przed skryptem widżetu)Kopiuj link do tej sekcji

Jeśli wywołujesz metodę, zanim skrypt się załaduje, dodaj wywołanie do kolejki:

<script>
  window.TillorInbox = window.TillorInbox || { q: [] };
  window.TillorInbox.q.push([
    "setVisitor",
    { name: "Jan", email: "jan@voorbeeld.be" },
    { open: true },
  ]);
</script>
<script src="https://tillor.eu/inbox-widget.js" data-org-id="org_abc123" data-widget-key="iwk_xxx" async defer></script>

Własny interfejs czatuKopiuj link do tej sekcji

Jeśli zamiast widżetu budujesz własny interfejs czatu, użyj warstwy REST poniżej.

Uwierzytelnianie: nagłówek X-Tillor-Inbox-Widget-Key (wartość z Ustawienia > Integracje > Czat na stronie).

Wskaźnik pisaniaKopiuj link do tej sekcji

POST /api/orgs/{orgId}/inbox/website/typing
X-Tillor-Inbox-Widget-Key: iwk_xxx
Content-Type: application/json

{
  "visitorId": "vis_…",
  "active": true,
  "visitorName": "Jan",
  "visitorEmail": "jan@voorbeeld.nl",
  "visitorPhone": "+32470123456"
}

• active: true, gdy odwiedzający pisze; false, gdy pole jest puste lub odwiedzający przestaje pisać (widżet wysyła false po około 4 sekundach bez wprowadzania)
• visitorName / visitorEmail / visitorPhone są opcjonalne
• Używaj tego samego visitorId co przy POST …/inbox/website/messages i GET …/inbox/website/messages

Czas rzeczywisty (SSE)Kopiuj link do tej sekcji

GET /api/orgs/{orgId}/inbox/website/subscribe?visitorId=vis_…
X-Tillor-Inbox-Widget-Key: iwk_xxx
Accept: text/event-stream

Kształt payloadu jest taki sam jak w SSE organizacji (event, data, timestamp). Połącz się ponownie po przerwaniu; wznawianie nie jest obsługiwane.

Oficjalny widżet używa SSE jako głównej warstwy i pobiera GET …/messages ponownie co 5 sekund jako rozwiązanie awaryjne (co 1 sekundę przy otwartym panelu, gdy SSE na chwilę zniknie). Dzięki temu odpowiedzi są oznaczane jako dostarczone, dopóki odwiedzający jest na stronie.

Aktywność odwiedzającegoKopiuj link do tej sekcji

POST /api/orgs/{orgId}/inbox/website/events
X-Tillor-Inbox-Widget-Key: iwk_xxx
Content-Type: application/json

event: chat_closed, tab_hidden lub navigation (przy nawigacji także url). Twój zespół widzi te zdarzenia jako szary tekst informacyjny w rozmowie, zobacz Rozmowy przez czat na stronie.

LimityKopiuj link do tej sekcji

POST …/inbox/website/messages i POST …/inbox/website/attachments/upload odpowiadają 429, gdy odwiedzający lub sieć wysyła za dużo. Treść zawiera data.reason = INBOX_WIDGET_RATE_LIMITED i data.retryAfterSeconds. Limity na organizację:

Odczekaj retryAfterSeconds przed ponowną próbą i pokaż odwiedzającemu komunikat zamiast ponawiać automatycznie.

Zobacz teżKopiuj link do tej sekcji