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

> API pública del widget para integraciones más allá del script embed.

<Info>
  Si el script embed y el panel bastan, comience en **[Chat con IA en su sitio](/es/ai-web-widget/index)**. Esta página resume la API pública para integraciones personalizadas.
</Info>

## En resumen

* **Base:** `https://api.notifique.me/public/ai-widget`
* **Sin API Key** de workspace. Seguridad por clave pública del widget, dominios permitidos y token de sesión.
* Rutas, headers y respuestas completas: **referencia de la API** en la pestaña Chat en el sitio.

## Flujo típico

1. **Obtener configuración** del widget (tema, textos, reglas de identificación). El script embed hace esto al cargar.
2. **Crear o reanudar sesión** con `visitorClientId` y datos del visitante (si el modo lo pide).
3. **Enviar mensaje** con `sessionToken` y `text` en el body (vea ejemplos abajo).
4. Si la respuesta viene con status `handoff` o `automation`, use **polling** para buscar mensajes nuevos.
5. Con OTP activo: **pedir código** y **confirmar código** antes de liberar el chat.

## Obtener configuración

Use la operación **Obtener configuración del widget** en la referencia de la API.

Respuesta común:

```json theme={null}
{
  "success": true,
  "data": {
    "name": "Asistente de la Tienda",
    "status": "ACTIVE",
    "identificationMode": "OPTIONAL",
    "identificationFieldMode": "EMAIL",
    "requireIdentityOtp": false,
    "theme": { "primaryColor": "#6366f1", "position": "right" },
    "maxMessagesPerSession": 50,
    "messageCooldownMs": 1000,
    "welcomeText": "¡Hola! ¿Cómo puedo ayudar?",
    "suggestedQuestions": ["¿Cuáles son los precios?", "¿Cómo funciona la entrega?"]
  }
}
```

## Crear o reanudar sesión

Use la operación **Crear sesión** en la referencia de la API.

```json theme={null}
{
  "visitorClientId": "id-guardado-en-navegador",
  "name": "María Silva",
  "email": "maria@ejemplo.com",
  "phone": "5511999999999"
}
```

| Campo             | Cuándo enviar       |
| ----------------- | ------------------- |
| `visitorClientId` | Siempre             |
| `name`            | Modo no anónimo     |
| `email` / `phone` | Según configuración |

Sitio con login (verificación automática):

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

Guarde el `sessionToken` de la respuesta y envíelo en el body de las llamadas siguientes (`sessionToken`).

Respuesta típica:

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

## Enviar mensaje

Use la operación **Enviar mensaje** en la referencia de la API.

```json theme={null}
{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "text": "¿Cuánto cuesta el plan Pro?",
  "clientMessageId": "id-unico-para-evitar-duplicado"
}
```

Respuesta de la IA:

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "id-del-mensaje",
    "replyText": "El plan Pro cuesta R$ 97/mes e incluye...",
    "status": "assistant"
  }
}
```

Handoff (transferencia humana):

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

| Status       | Significado                            |
| ------------ | -------------------------------------- |
| `assistant`  | La IA respondió                        |
| `handoff`    | Transferido a humano. Use polling.     |
| `automation` | Automatización disparada. Use polling. |

## Buscar mensajes nuevos (polling)

Use la operación **Listar mensajes** en la referencia de la API, con parámetro `after` (timestamp).

Recomendado: polling cada **2 s**, por hasta **3 minutos**, cuando el status sea `handoff` o `automation`.

## OTP

* **Pedir código:** operación **Solicitar OTP** con `{ "sessionToken": "..." }`
* **Confirmar código:** operación **Verificar OTP** con `{ "sessionToken": "...", "code": "482913" }`

## Errores comunes

| Código | Significado                                          |
| ------ | ---------------------------------------------------- |
| 403    | Dominio no permitido, OTP pendiente o widget pausado |
| 429    | Rate limit                                           |
| 422    | Máximo de mensajes o cooldown                        |
| 401    | Sesión inválida o expirada                           |

## Panel (uso interno)

Endpoints de gestión del widget (listar, crear, actualizar, rotar claves) exigen login en el dashboard. Detalles en la **referencia de la API** en la pestaña Chat en el sitio.

## Todos los tipos de envío

En la referencia de la API (pestaña Chat web), abra **Enviar mensaje en el widget** y elija un ejemplo en el playground: Sesión, Mensaje, OTP.

## Próximos pasos

* [Seguridad](/es/ai-web-widget/seguranca): modos de identificación
* [Consejos](/es/ai-web-widget/boas-praticas)
* [Chat con IA en su sitio](/es/ai-web-widget/index)