> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Para desenvolvedores

> API pública do widget para integrações além do script embed.

<Info>
  Se o script embed e o painel bastam, comece em **[Chat com IA no site](/ai-web-widget/index)**. Esta página resume a API pública para integrações custom.
</Info>

## Em poucas palavras

* **Base:** `https://api.notifique.me/public/ai-widget`
* **Sem API Key** de workspace. Segurança por chave pública do widget, domínios permitidos e token de sessão.
* Rotas, headers e respostas completas: **referência da API** na aba Chat no site.

## Fluxo típico

1. **Obter configuração** do widget (tema, textos, regras de identificação). O script embed faz isso ao carregar.
2. **Criar ou retomar sessão** com `visitorClientId` e dados do visitante (se o modo pedir).
3. **Enviar mensagem** com `sessionToken` e `text` no body (veja exemplos abaixo).
4. Se a resposta vier com status `handoff` ou `automation`, use **polling** para buscar mensagens novas.
5. Com OTP ativo: **pedir código** e **confirmar código** antes de liberar o chat.

## Obter configuração

Use a operação **Obter configuração do widget** na referência da API.

Resposta comum:

```json theme={null}
{
  "success": true,
  "data": {
    "name": "Assistente da Loja",
    "status": "ACTIVE",
    "identificationMode": "OPTIONAL",
    "identificationFieldMode": "EMAIL",
    "requireIdentityOtp": false,
    "theme": { "primaryColor": "#6366f1", "position": "right" },
    "maxMessagesPerSession": 50,
    "messageCooldownMs": 1000,
    "welcomeText": "Olá! Como posso ajudar?",
    "suggestedQuestions": ["Quais são os preços?", "Como funciona a entrega?"]
  }
}
```

## Criar ou retomar sessão

Use a operação **Criar sessão** na referência da API.

```json theme={null}
{
  "visitorClientId": "id-salvo-no-navegador",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "5511999999999"
}
```

| Campo             | Quando enviar         |
| ----------------- | --------------------- |
| `visitorClientId` | Sempre                |
| `name`            | Modo não anônimo      |
| `email` / `phone` | Conforme configuração |

Site com login (verificação automática):

```json theme={null}
{
  "identityPayload": {
    "email": "maria@exemplo.com",
    "exp": 1730000000,
    "publicKey": "ntfw_xxx",
    "v": 1
  },
  "identitySignature": "assinatura-hex-aqui"
}
```

Guarde o `sessionToken` da resposta e envie-o no body das chamadas seguintes (`sessionToken`).

Resposta típica:

```json theme={null}
{
  "success": true,
  "data": {
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessionId": "clsession123",
    "identityVerified": false,
    "messages": []
  }
}
```

## Enviar mensagem

Use a operação **Enviar mensagem** na referência da API.

```json theme={null}
{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "text": "Quanto custa o plano Pro?",
  "clientMessageId": "id-unico-para-evitar-duplicata"
}
```

Resposta da IA:

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "id-da-mensagem",
    "replyText": "O plano Pro custa R$ 97/mês e inclui...",
    "status": "assistant"
  }
}
```

Handoff (transferência humana):

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "id-da-mensagem",
    "replyText": null,
    "status": "handoff"
  }
}
```

| Status       | Significado                          |
| ------------ | ------------------------------------ |
| `assistant`  | IA respondeu                         |
| `handoff`    | Transferiu para humano. Use polling. |
| `automation` | Automação disparada. Use polling.    |

## Buscar mensagens novas (polling)

Use a operação **Listar mensagens** na referência da API, com parâmetro `after` (timestamp).

Recomendado: polling a cada **2 s**, por até **3 minutos**, quando status for `handoff` ou `automation`.

## OTP

* **Pedir código:** operação **Solicitar OTP** com `{ "sessionToken": "..." }`
* **Confirmar código:** operação **Verificar OTP** com `{ "sessionToken": "...", "code": "482913" }`

## Erros comuns

| Código | Significado                                           |
| ------ | ----------------------------------------------------- |
| 403    | Domínio não permitido, OTP pendente ou widget pausado |
| 429    | Rate limit                                            |
| 422    | Máximo de mensagens ou cooldown                       |
| 401    | Sessão inválida ou expirada                           |

## Painel (uso interno)

Endpoints de gestão do widget (listar, criar, atualizar, rotacionar chaves) exigem login no dashboard. Detalhes na **referência da API** na aba Chat no site.

## Todos os tipos de envio

Na referência da API (aba Chat no site), abra **Enviar mensagem no widget** (`POST /v1/...`) e escolha o exemplo no playground: Sessão, Mensagem, OTP.

## Próximos passos

* [Segurança](/ai-web-widget/seguranca): modos de identificação
* [Dicas](/ai-web-widget/boas-praticas)
* [Chat com IA no site](/ai-web-widget/index)