API do chat do website

O widget oficial instala-se na aplicação: consulte Colocar o chat no seu website. As opções do snippet estão em Definições do chat do website. Esta página é para programadores: o SDK do widget para um formulário próprio e a camada REST para uma interface de chat própria. Consulte o OpenAPI, etiqueta inbox.

SDK do widgetCopiar a ligação para esta secção

Depois de carregar o script do widget, window.TillorInbox fica disponível. Com ele passa dados de contacto a partir do seu próprio formulário (página de contacto, detalhe de venda, pedido de orçamento). Todos os métodos esperam até a configuração do widget estar carregada.

getVisitor() devolve este objeto:

Utilize getVisitor() para preencher previamente um formulário próprio a partir de localStorage (mesmo navegador, também após atualizar a página).

Opções para setVisitor (segundo argumento):

Opções para send:

Com open: false (por defeito), o botão do chat permanece fechado. A mensagem chega mesmo assim ao Tillor; o seu formulário pode agradecer ou mostrar um erro. Com open: true, a janela de chat abre e o visitante vê o comportamento normal de envio (som, vistos, eventuais erros do widget).

Quer usar um botão seu em vez do botão de chat flutuante? Defina data-launcher="false" no snippet e chame TillorInbox.open().

metadata (formulário de reserva)Copiar a ligação para esta secção

Utilize metadata quando tiver um formulário próprio no website e a Tillie deva enviar apenas uma confirmação, sem perguntas de seguimento (por exemplo, porque o separador se fecha depois).

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",
  },
});

Substituir o formulário de contacto (envio silencioso)Copiar a ligação para esta secção

Utilize isto quando quiser manter o formulário de contacto existente, mas fazer as mensagens passar pelo Tillor sem abrir a janela de chat.

<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">Enviar</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 = "Obrigado, entraremos em contacto em breve.";
      status.hidden = false;
      form.reset();
    } catch (error) {
      status.textContent = error instanceof Error ? error.message : "Falha ao enviar.";
      status.hidden = false;
    }
  });
</script>

Não precisa de definir open e silent: sem open: true, a janela permanece fechada e o Tillor trata a chamada como envio silencioso.

Ligar o formulário de contacto (abrir o chat)Copiar a ligação para esta secção

Passar os campos e abrir a janela de chat, para que o visitante veja a conversa:

<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">Enviar</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>

Ou apenas preencher os campos e abrir a janela, sem enviar logo:

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 },
);

Uma página de vendas com envio direto e abertura do chat:

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,
});

Sincronizar em direto enquanto alguém escreve:

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,
  });
});

Chamar cedo (antes do script do widget)Copiar a ligação para esta secção

Se chamar um método antes de o script estar carregado, coloque a chamada na fila:

<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>

Interface de chat própriaCopiar a ligação para esta secção

Se criar uma interface de chat própria em vez do widget, utilize a camada REST abaixo.

Autenticação: cabeçalho X-Tillor-Inbox-Widget-Key (valor em Definições > Integrações > Chat do website).

EscritaCopiar a ligação para esta secção

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 quando o visitante escreve; false quando o campo fica vazio ou o visitante pára (o widget envia false após cerca de 4 segundos sem entrada)
• visitorName / visitorEmail / visitorPhone são opcionais
• Utilize o mesmo visitorId que em POST …/inbox/website/messages e GET …/inbox/website/messages

Tempo real (SSE)Copiar a ligação para esta secção

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

O formato do payload é o mesmo do SSE da organização (event, data, timestamp). Volte a ligar após uma interrupção; não há retoma.

O widget oficial usa o SSE como camada principal e volta a obter GET …/messages a cada 5 segundos como alternativa (a cada 1 segundo com o painel aberto quando o SSE cai por momentos). Assim, as respostas são marcadas como entregues enquanto o visitante estiver na página.

Atividade do visitanteCopiar a ligação para esta secção

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

event: chat_closed, tab_hidden ou navigation (na navegação também url). A sua equipa vê estes eventos como texto informativo cinzento na conversa, consulte Conversas através do chat do website.

LimitesCopiar a ligação para esta secção

POST …/inbox/website/messages e POST …/inbox/website/attachments/upload respondem 429 quando um visitante ou uma rede envia demasiado. O corpo traz data.reason = INBOX_WIDGET_RATE_LIMITED e data.retryAfterSeconds. Limites por organização:

Espera retryAfterSeconds antes de tentar de novo e mostra um aviso ao visitante em vez de repetir automaticamente.

Ver tambémCopiar a ligação para esta secção