API JavaScript: controlar el widget desde su página

El widget proporciona un único objeto global: window.ReactiveChat. Todos los comandos se llaman en forma de función:

ReactiveChat('command', argument1, argument2);

Los nombres de los comandos básicos siguen los de otros widgets de chat habituales (boot, shutdown, open, identify, update, track…), para facilitar el cambio.

La cola antes de la carga

El cargador crea primero ReactiveChat. Hasta que se carga el núcleo, esta versión registra cada llamada en ReactiveChat.q; después, el núcleo procesa la lista en orden. No se pierde ninguna llamada.

Si su código puede ejecutarse antes de la etiqueta del cargador, añada esta línea delante:

window.ReactiveChat = window.ReactiveChat || function () {
  (window.ReactiveChat.q = window.ReactiveChat.q || []).push(arguments);
};

Esto tiene dos consecuencias:

• Antes de la carga, todos los valores de retorno son undefined. Por tanto, utilice los comandos con valor de retorno (getSession, isOpen, tour…) después del evento ready (véase Eventos).
• Un comando activa la carga. Todos los comandos excepto boot, update, track e identify cargan el núcleo de inmediato (disparador command). Por tanto, llamar pronto a identify no tiene coste.

Los comandos nunca lanzan excepciones: un error en un comando da como resultado undefined; un comando desconocido se ignora (con data-rc-debug="true" aparece en la consola).

ReactiveChat('on', 'ready', function () {
  var s = ReactiveChat('getSession');
  console.log('Visitor', s && s.visitorId);
});

Arranque y cierre

• boot (cfg?: object): la primera llamada establece la configuración con los mismos campos que los atributos de la etiqueta de script (camel case, por ejemplo, { siteKey, locale, theme, position, brand }) y arranca. Cada llamada posterior solo adopta locale, theme, dnd, autoOpen, strings y position. Si no hay boot en la cola, el núcleo lo llama por sí mismo.
• shutdown (): elimina el widget de esta página (ventana, conexión y observadores) y restablece ReactiveChat como una simple cola. No está previsto volver a iniciarlo sin recargar la página.

ReactiveChat('boot', { locale: 'en', theme: 'dark' });

Ventana

• open (opts?): abre la ventana. opts es un elemento (la ventana aparece a su lado) o un objeto:
• anchor (elemento, opcional): abrir junto a este elemento; sin él, posición normal.
• message (cadena, opcional): escribir texto en el campo de entrada, sin enviarlo (máximo 200 caracteres).
• tab (msg | home | help, opcional): elegir la pestaña. Si el propio anchor lleva data-rc-message o data-rc-tab, se aplican estos; los valores explícitos de la llamada tienen prioridad. Antes de la carga, la solicitud se recuerda.
• close (): cierra la ventana.
• toggle (): alterna su estado.
• isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Question about my order', tab: 'msg' });
});

Mensajes y conversaciones

• sendMessage (text: string): envía un mensaje en nombre del visitante, como si lo hubiera escrito (se aplican los mismos límites; véase Límites). Utilícelo solo después de una acción del visitante, nunca sin que este lo solicite.
• newConversation (): inicia una conversación nueva.
• leaveMessage (): abre el formulario para dejar un mensaje cuando no hay nadie disponible.
• startConversation (text: string, suche?: string): inicia una conversación nueva y envía text en cuanto esté lista. Smart Answer lo utiliza para continuar una pregunta de búsqueda en el chat.
• continueConversation (id: string, text: string): continúa una conversación existente con text (id debe coincidir con [0-9A-Za-z_-]{1,64}; en caso contrario, se inicia una nueva). También se utiliza para la transferencia desde Smart Answer.

Visitantes y contexto

• identify ({ userId, email, name, userHash, exp }): comunica un usuario con sesión iniciada. Los demás campos se descartan. Sin un userHash válido calculado en su servidor, el usuario se considera no confirmado: el nombre y el correo aparecen en el panel, pero ninguno concede acceso a datos de clientes ni a historiales de conversaciones ajenos. Todo sobre la firma está en Identificar visitantes.
• update (attrs: object): transmite atributos a la conexión de MousePlayer (solo es relevante si utiliza MousePlayer).
• track (name: string, meta?: object): comunica un hito. Los campos de meta incluidos en la lista de contexto (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock y otros) llegan al asistente y a los agentes como contexto de página. Los demás se descartan. Véase Identificar visitantes y transmitir contexto.
• getSession () → { sessionId, visitorId, tabId } o null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId }: de dónde obtiene el widget su conexión; para scripts propios que necesiten la misma dirección.
• portal (basis?: string) → boolean: abre el portal de clientes en una pestaña nueva y transmite la identidad confirmada. false si no hay usuario confirmado. basis es un origen https:// propio opcional.

ReactiveChat('track', 'produkt_angesehen', {
  page_type: 'product', product_id: 'SKU-4711', price: 49.9, currency: 'EUR', in_stock: true
});

Idioma y tema

• setLocale (locale: 'de' | 'en' | 'pl'): cambia el idioma; la elección se recuerda en el navegador.
• setTheme ('light' | 'dark' | 'auto').

Aviso, tarjeta promocional y recorridos

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean: muestra una pequeña burbuja junto al botón del chat. quickReplies, máximo 3; ttlMs, 0–120000 (predeterminado: 15000). No se muestra (false) si la ventana está abierta, el botón del chat está oculto, se aplica «No molestar», hay una conversación en curso o se aplica una limitación de frecuencia.
• show (text | object) → boolean: forma abreviada: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide (): oculta la burbuja.
• promo (false | true | object): ocultar la tarjeta promocional en esta página, volver a mostrarla o sustituirla por sus propios campos (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean: inicia un recorrido del producto creado en su cuenta; false para un identificador desconocido. Los recorridos se configuran en Personalización.
• tourStop (): finaliza el recorrido en curso.

Pruebas A/B

• abVariant () → { test, variant, qa } o null: la variante que ve este visitante.
• abGoal (): comunica que se ha alcanzado el objetivo de la prueba en curso (por ejemplo, en la página de agradecimiento).

ReactiveChat('on', 'ready', function () { ReactiveChat('abGoal'); });

Diseño en tiempo de ejecución

• setBrand (marke: object): sustituye colores y forma sin recompilar; null vuelve a eliminar un valor.
• brandCheck () → lista de los contrastes medidos { paar, ist, soll }.
• brandTokens () → los valores de diseño resueltos.
• setStart (startseite: object): establece la pantalla de inicio en tiempo de ejecución (para vistas previas).

Los campos de estos objetos se describen en Personalización.

Eventos

• on (name, callback) / off (name, callback): suscribirse a eventos y cancelar la suscripción. Lista y datos: Eventos.

Directamente en el objeto

Una vez cargados, algunos comandos también están disponibles como métodos: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Además, ReactiveChat.version (versión del núcleo). Estos métodos no existen antes de la carga; la forma de función es la opción segura.

Qué no existe

Para evitar búsquedas innecesarias: no existen los comandos destroy, reset, setUser, send, setConsent, trackPage ni navigate. El consentimiento se controla mediante su plataforma de consentimiento o data-rc-consent (Integración de privacidad); el widget detecta por sí mismo los cambios de página (SPA); para cerrar la sesión, véase Identificar visitantes.

Siguiente: Eventos