API JavaScript: controlar o widget pela sua página

O widget fornece um único objeto global: window.ReactiveChat. Você chama todos os comandos no formato de função:

ReactiveChat('command', argument1, argument2);

Os nomes dos comandos básicos seguem os widgets de chat comuns (boot, shutdown, open, identify, update, track …), para facilitar a migração.

A fila antes do carregamento

O carregador cria ReactiveChat primeiro. Até o núcleo carregar, essa versão registra cada chamada em ReactiveChat.q; o núcleo depois processa a lista na ordem. Nenhuma chamada se perde.

Se seu código puder ser executado antes da tag do carregador, coloque esta linha antes dele:

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

Disso decorrem duas coisas:

• Antes do carregamento, todo valor de retorno é undefined. Portanto, use comandos com retorno (getSession, isOpen, tour …) após o evento ready (veja Eventos).
• Um comando aciona o carregamento. Todo comando, exceto boot, update, track e identify, carrega o núcleo imediatamente (gatilho command). Por isso, chamar identify antes não tem custo adicional.

Comandos nunca lançam exceções: um erro resulta em undefined, e um comando desconhecido é ignorado (com data-rc-debug="true", aparece no console).

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

Inicialização e encerramento

• boot (cfg?: object) – a primeira chamada define a configuração com os mesmos campos dos atributos da tag script (camel case, por exemplo, { siteKey, locale, theme, position, brand }) e inicia. Cada chamada posterior só aplica locale, theme, dnd, autoOpen, strings e position. Se boot estiver ausente na fila, o núcleo o chama sozinho.
• shutdown () – remove o widget desta página (janela, conexão, observadores) e redefine ReactiveChat como uma fila simples. Não é previsto reiniciar sem recarregar a página.

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

Janela

• open (opts?) – abre a janela. opts é um elemento (a janela aparece ao lado dele) ou um objeto:
• anchor (elemento, opcional) – abrir ao lado desse elemento; sem ele: posição normal.
• message (string, opcional) – inserir texto no campo de entrada, sem enviá-lo (no máximo 200 caracteres).
• tab (msg | home | help, opcional) – escolher a aba. Se o próprio anchor contiver data-rc-message ou data-rc-tab, esses valores se aplicam; valores explícitos na chamada têm prioridade. Antes do carregamento, a solicitação é lembrada.
• close () – fecha a janela.
• toggle () – alterna a janela.
• isOpen () → boolean.

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

Mensagens e conversas

• sendMessage (text: string) – envia uma mensagem em nome do visitante, como se ele a tivesse digitado (os mesmos limites se aplicam; veja Limites). Use somente após uma ação do visitante, nunca sem solicitação.
• newConversation () – inicia uma nova conversa.
• leaveMessage () – abre o formulário para deixar uma mensagem quando ninguém está disponível.
• startConversation (text: string, suche?: string) – inicia uma nova conversa e envia text assim que estiver pronta. Usado pelo Smart Answer para continuar uma pergunta de pesquisa no chat.
• continueConversation (id: string, text: string) – continua uma conversa existente com text (id correspondente a [0-9A-Za-z_-]{1,64}; caso contrário, inicia uma nova). Também usado na transferência do Smart Answer.

Visitantes e contexto

• identify ({ userId, email, name, userHash, exp }) – informa um usuário conectado. Outros campos são descartados. Sem um userHash válido calculado no seu servidor, o usuário conta como não confirmado: nome e e-mail aparecem no painel, mas nada disso concede acesso a dados de clientes ou históricos de conversas de outras pessoas. Tudo sobre a assinatura está em Identificar visitantes.
• update (attrs: object) – passa atributos à conexão com o MousePlayer (relevante apenas se você usa MousePlayer).
• track (name: string, meta?: object) – informa um marco. Campos de meta que estão na lista de contexto (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock e outros) vão ao assistente e aos atendentes como contexto da página. Outros campos são descartados. Veja Identificar visitantes e passar contexto.
• getSession () → { sessionId, visitorId, tabId } ou null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – de onde o widget obtém a conexão; para scripts próprios que precisam do mesmo endereço.
• portal (basis?: string) → boolean – abre o portal do cliente em uma nova aba e passa a identidade confirmada. false se não houver usuário confirmado. basis é uma origem https:// própria opcional.

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

Idioma e tema

• setLocale (locale: 'de' | 'en' | 'pl') – troca o idioma; a escolha é lembrada no navegador.
• setTheme ('light' | 'dark' | 'auto').

Bolha de aviso, card promocional e tours

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – mostra uma pequena bolha no botão do chat. quickReplies no máximo 3, ttlMs de 0–120000 (padrão 15000). Não é exibida (false) se a janela estiver aberta, o botão oculto, “Não perturbe” ativo, uma conversa em andamento ou um limite de frequência aplicável.
• show (text | object) → boolean – forma curta: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – oculta a bolha.
• promo (false | true | object) – ocultar o card promocional nesta página, mostrá-lo novamente ou substituí-lo com campos próprios (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – inicia um tour criado na conta; false para ID desconhecido. Os tours são configurados em Personalização.
• tourStop () – encerra o tour em andamento.

Testes A/B

• abVariant () → { test, variant, qa } ou null – a variante que o visitante vê.
• abGoal () – informa que a meta do teste em andamento foi alcançada (por exemplo, na página de agradecimento).

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

Design durante a execução

• setBrand (marke: object) – substitui cores e forma sem reconstruir; null remove um valor novamente.
• brandCheck () → lista dos contrastes medidos { paar, ist, soll }.
• brandTokens () → os valores de design resolvidos.
• setStart (startseite: object) – define a tela inicial durante a execução (para prévias).

Os campos desses objetos estão descritos em Personalização.

Eventos

• on (name, callback) / off (name, callback) – assinar e cancelar a assinatura de eventos. Lista e dados: Eventos.

Diretamente no objeto

Após o carregamento, alguns comandos também estão disponíveis como métodos: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Além disso, ReactiveChat.version (versão do núcleo). Esses métodos não existem antes do carregamento; o formato de função é a forma segura.

O que não existe

Para ninguém precisar procurar: não há comandos destroy, reset, setUser, send, setConsent, trackPage ou navigate. Você controla o consentimento pela plataforma de consentimento ou por data-rc-consent (Integração de privacidade), o widget detecta mudanças de página sozinho (SPA), e para sair veja Identificar visitantes.

A seguir: Eventos