API de chat web

El widget oficial se instala en la app: consulta Poner el chat en tu sitio web. Las opciones del snippet están en Ajustes del chat web. Esta página es para desarrolladores: el SDK del widget para un formulario propio y la capa REST para una interfaz de chat propia. Consulta OpenAPI, etiqueta inbox.

SDK del widgetCopiar el enlace a esta sección

Tras cargar el script del widget, window.TillorInbox está disponible. Con él pasas datos de contacto desde tu propio formulario (página de contacto, detalle de venta, solicitud de presupuesto). Todos los métodos esperan a que se haya cargado la configuración del widget.

getVisitor() devuelve este objeto:

Usa getVisitor() para rellenar de antemano un formulario propio desde localStorage (mismo navegador, también tras recargar la página).

Opciones de setVisitor (segundo argumento):

Opciones de send:

Con open: false (por defecto) el botón del chat sigue cerrado. El mensaje sí llega a Tillor; tu propio formulario puede dar las gracias o mostrar un error. Con open: true se abre la ventana del chat y el visitante ve el comportamiento de envío normal (sonido, ticks, posibles errores del widget).

¿Quieres usar un botón propio en lugar del botón flotante del chat? Pon data-launcher="false" en el snippet y llama a TillorInbox.open().

metadata (formulario de reserva)Copiar el enlace a esta sección

Usa metadata cuando tengas un formulario propio en el sitio web y Tillie deba enviar solo una confirmación, sin preguntas de seguimiento (por ejemplo porque la pestaña se cierra después).

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

Sustituir el formulario de contacto (envío silencioso)Copiar el enlace a esta sección

Úsalo cuando quieras mantener el formulario de contacto existente, pero hacer que los mensajes pasen por Tillor sin abrir la ventana del 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">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>

No hace falta que pongas open ni silent: sin open: true la ventana permanece cerrada y Tillor trata la llamada como un envío silencioso.

Conectar el formulario de contacto (abrir el chat)Copiar el enlace a esta sección

Pasar los campos y abrir la ventana del chat, para que el visitante vea la conversación:

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

O solo rellenar campos y abrir la ventana, sin enviar de inmediato:

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

Una página de venta con envío directo y apertura del 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 en vivo mientras alguien escribe:

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

Llamar pronto (antes del script del widget)Copiar el enlace a esta sección

Si llamas a un método antes de que se haya cargado el script, pon la llamada en la cola:

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

Interfaz de chat propiaCopiar el enlace a esta sección

Si creas una interfaz de chat propia en lugar del widget, usa la capa REST de abajo.

Autenticación: encabezado X-Tillor-Inbox-Widget-Key (valor de Configuración > Integraciones > Chat web).

Indicador de escrituraCopiar el enlace a esta sección

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 cuando el visitante escribe; false cuando el campo está vacío o el visitante deja de escribir (el widget envía false tras unos 4 segundos sin entrada)
• visitorName / visitorEmail / visitorPhone son opcionales
• Usa el mismo visitorId que en POST …/inbox/website/messages y GET …/inbox/website/messages

Tiempo real (SSE)Copiar el enlace a esta sección

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

La forma del payload es la misma que en el SSE de la organización (event, data, timestamp). Vuelve a conectarte tras una interrupción; no hay reanudación.

El widget oficial usa SSE como capa principal y vuelve a obtener GET …/messages cada 5 segundos como respaldo (cada 1 segundo con el panel abierto cuando SSE se interrumpe un momento). Así, las respuestas se marcan como entregadas mientras el visitante está en la página.

Actividad del visitanteCopiar el enlace a esta sección

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

event: chat_closed, tab_hidden o navigation (en la navegación también url). Tu equipo ve estos eventos como texto informativo en gris en la conversación, consulta Conversaciones por chat web.

LímitesCopiar el enlace a esta sección

POST …/inbox/website/messages y POST …/inbox/website/attachments/upload responden 429 cuando un visitante o una red envía demasiado. El cuerpo incluye data.reason = INBOX_WIDGET_RATE_LIMITED y data.retryAfterSeconds. Límites por organización:

Espera retryAfterSeconds antes de volver a intentarlo y muestra un aviso al visitante en lugar de reintentar automáticamente.

Véase tambiénCopiar el enlace a esta sección