# API JavaScript: abrir o agente Nodale a partir do seu código

<https://nodale.ai/pt/docs/api>

Os comandos nodale() que uma página pode chamar: abrir o agente a partir do seu botão ou formulário, passar um e-mail e contexto, comunicar o consentimento.

Depois de a [tag estar instalada](https://nodale.ai/pt/docs), a sua página pode enviar-lhe comandos através de uma única função, `nodale()`. Há dois comandos: `open` e `consent`. A tag não expõe nenhum outro método e não envia nenhum evento à sua página.

## A fila de comandos

A tag define `window.nodale` quando é executada. Para chamar um comando antes de a tag ter carregado, cole este stub por cima dela. Os comandos esperam numa fila até a tag estar pronta:

```html
<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Mantenha o `||`. Um script que mais tarde atribua `window.nodale` sem ele remove o comando da tag, e as chamadas seguintes não chegam a lado nenhum.

## `nodale('open')`

Abre o agente a partir do seu próprio código, por exemplo a partir do seu próprio botão ou depois de o seu próprio formulário ser enviado.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contactos por mês': '1500' }
})
```

A chamada inicia uma conversa escrita na janela de diálogo do agente. O microfone não é pedido: espera pelo visitante.

### Opções

| Opção | Tipo | O que faz |
|---|---|---|
| `email` | string | O e-mail do visitante, quando a sua página já o conhece. O visitante é identificado antes da saudação do agente. |
| `context` | object | O que o visitante já lhe disse, em pares de etiqueta e resposta. O agente recebe-o quando a conversa começa. Fica registado na conversa e nunca é mostrado ao visitante. |

Ambas são opcionais. A tag verifica o argumento antes de qualquer coisa sair da página:

- **O argumento** é nada, ou um objeto simples sem outra chave além de `email` e `context`. Qualquer outra coisa e nada abre.
- **`email`** é uma string de 1 a 254 caracteres, depois de retirados os espaços nas extremidades. Caso contrário é descartado, e o agente abre na mesma. A tag não avalia o endereço: é o servidor que decide se o aceita.
- **`context`** contém 20 respostas no máximo. Uma etiqueta tem de 1 a 60 caracteres, uma resposta é uma string de 300 caracteres no máximo, e uma etiqueta é usada uma só vez. Os espaços nas extremidades das etiquetas e das respostas são retirados, e uma resposta vazia é ignorada. Se uma regra for quebrada, o contexto inteiro é descartado, nunca cortado, e o agente abre na mesma sem ele.

`nodale('open')` nunca lança exceções e devolve `undefined`.

### Onde funciona

- **Apenas na barra e na apresentação `hidden`.** Com a apresentação em botão, com um `<div data-nodale-agent>` inline, e numa página onde o agente não é mostrado (uma regra de página, ou uma parte dos visitantes), a chamada não faz nada. Se usar `open`, mantenha a parte dos visitantes desligada, ou a chamada não fará nada para alguns visitantes.
- **Antes de a tag ter carregado**, através do stub acima. Só o último `open` em fila é reproduzido, uma vez.
- **Uma conversa.** O widget inicia uma conversa no máximo e guarda o primeiro e-mail e o primeiro contexto que recebeu. Um `open` durante uma conversa, ou depois de uma ter terminado, apenas mostra a janela de diálogo.
- **Quando o agente pede primeiro o e-mail**, a chamada mostra esse passo, e o seu e-mail e o seu contexto são enviados quando o visitante o submete.

### A partir de um botão

```html
<button type="button" onclick="nodale('open')">Fazer uma pergunta</button>
```

### Depois do seu próprio formulário

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Dimensão da empresa': form.elements.size.value,
      'O que pretende fazer': form.elements.message.value
    }
  })
})
```

## A apresentação hidden

`hidden` é uma apresentação do workspace, ao lado da barra e do botão. Com ela, nada é mostrado até a sua página chamar `nodale('open')`.

- **A página continua totalmente utilizável.** A frame do agente está montada mas invisível, e não recebe nenhum clique.
- **Depois de aberta, é a barra.** Fechar a janela de diálogo volta à barra e mantém a conversa. A barra fica então presente durante o resto do separador.
- **O separador lembra-se.** Uma página seguinte do seu site, no mesmo separador, mostra a barra de imediato, para que o visitante reencontre a conversa. A tag guarda isto em `sessionStorage`, numa chave que não contém nenhum identificador. Um novo separador começa oculto.
- **Testada apenas em browsers Chromium.** O Safari e o Firefox ainda não estão cobertos pelos nossos testes de browser: um browser que abranda as frames invisíveis pode responder a `open` mais tarde.

## `nodale('consent')`

Indica à tag se o visitante aceitou o rastreio de visitas. Use-o quando o seu site não tem um banner de cookies que a tag consiga ler, ou quando gere o consentimento por si.

```js
nodale('consent', 'granted')
nodale('consent', 'revoked')
```

- **Só conta quando o rastreio de visitas está ligado** no seu workspace. O rastreio está desligado por predefinição, e o agente é montado em ambos os casos.
- **O rastreio começa recusado.** Nada é pedido e nenhum cookie é escrito antes de uma autorização. Com `revoked`, a tag para e elimina o seu cookie.
- **Prevalece sobre qualquer banner.** Depois de a sua página o ter chamado, a tag segue a sua chamada e ignora o que um banner diz.
- **O Global Privacy Control prevalece sobre tudo.** Um browser que o envia fica recusado durante toda a visita, seja o que for que a sua página chame.

Sem a chamada, a tag lê a resposta na ferramenta de consentimento da página: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, o banner da HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP e Google Consent Mode v2. Algumas precisam de que a Nodale seja declarada como fornecedor ou como serviço: o guia do rastreio de visitas na aplicação indica a configuração de cada uma.

## Depuração

A tag nunca lança exceções na sua página. Explica-se em `console.debug`, em linhas começadas por `nodale tag:`. Ative o nível verbose da consola do seu browser para as ver.

| Linha | O que aconteceu |
|---|---|
| `open refused` | O argumento não é um objeto simples, ou contém outra chave além de `email` e `context`. |
| `open email dropped` | `email` não é uma string de 1 a 254 caracteres. |
| `open context dropped` | `context` quebra uma das suas regras. |
| `open needs the floating or hidden display` | O workspace usa a apresentação em botão, ou a página monta o agente inline. |
| `open: agent not on this page` | Uma regra de página ou a parte dos visitantes mantém o agente fora desta página. |
| `open not acknowledged` | O widget não respondeu em 30 segundos. |

## Docs

- [Instalar o agente Nodale no seu site](https://nodale.ai/pt/docs): Uma tag de script coloca o agente Nodale no seu site. Onde a colar, o que o seu site tem de permitir e como verificar que funciona. (Markdown: https://nodale.ai/pt/docs.md)
- [Servidor MCP: gerir o seu workspace Nodale no Claude Code](https://nodale.ai/pt/docs/mcp): Ligue o Claude Code ao servidor MCP da Nodale e leia ou altere o seu workspace: conhecimento, assets de demo, definições do agente, sites, implementação. (Markdown: https://nodale.ai/pt/docs/mcp.md)
