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

# For developers

> Public widget API for integrations beyond the embed script.

<Info>
  If the embed script and dashboard are enough, start at **[AI chat on your site](/en/ai-web-widget/index)**. This page summarizes the public API for custom integrations.
</Info>

## In short

* **Base:** `https://api.notifique.me/public/ai-widget`
* **No workspace API Key.** Security via widget public key, allowed domains, and session token.
* Full routes, headers, and responses: **API reference** on the Web chat tab.

## Typical flow

1. **Get widget configuration** (theme, copy, identification rules). The embed script does this on load.
2. **Create or resume session** with `visitorClientId` and visitor data (if the mode requires it).
3. **Send message** with `sessionToken` and `text` in the body (see examples below).
4. If the response status is `handoff` or `automation`, use **polling** for new messages.
5. With OTP enabled: **request code** and **verify code** before unlocking chat.

## Get configuration

Use the **Get widget configuration** operation in the API reference.

Typical response:

```json theme={null}
{
  "success": true,
  "data": {
    "name": "Store Assistant",
    "status": "ACTIVE",
    "identificationMode": "OPTIONAL",
    "identificationFieldMode": "EMAIL",
    "requireIdentityOtp": false,
    "theme": { "primaryColor": "#6366f1", "position": "right" },
    "maxMessagesPerSession": 50,
    "messageCooldownMs": 1000,
    "welcomeText": "Hello! How can I help?",
    "suggestedQuestions": ["What are the prices?", "How does delivery work?"]
  }
}
```

## Create or resume session

Use the **Create session** operation in the API reference.

```json theme={null}
{
  "visitorClientId": "id-stored-in-browser",
  "name": "Maria Silva",
  "email": "maria@example.com",
  "phone": "5511999999999"
}
```

| Field             | When to send       |
| ----------------- | ------------------ |
| `visitorClientId` | Always             |
| `name`            | Non-anonymous mode |
| `email` / `phone` | Per configuration  |

Site with login (automatic verification):

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

Save the `sessionToken` from the response and send it in the body of following calls (`sessionToken`).

Typical response:

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

## Send message

Use the **Send message** operation in the API reference.

```json theme={null}
{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "text": "How much is the Pro plan?",
  "clientMessageId": "unique-id-to-avoid-duplicate"
}
```

AI response:

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "message-id",
    "replyText": "The Pro plan costs $97/month and includes...",
    "status": "assistant"
  }
}
```

Handoff (human transfer):

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

| Status       | Meaning                            |
| ------------ | ---------------------------------- |
| `assistant`  | AI replied                         |
| `handoff`    | Transferred to human. Use polling. |
| `automation` | Automation triggered. Use polling. |

## Fetch new messages (polling)

Use the **List messages** operation in the API reference, with `after` (timestamp).

Recommended: poll every **2 s**, for up to **3 minutes**, when status is `handoff` or `automation`.

## OTP

* **Request code:** **Request OTP** operation with `{ "sessionToken": "..." }`
* **Confirm code:** **Verify OTP** operation with `{ "sessionToken": "...", "code": "482913" }`

## Common errors

| Code | Meaning                                           |
| ---- | ------------------------------------------------- |
| 403  | Domain not allowed, OTP pending, or widget paused |
| 429  | Rate limit                                        |
| 422  | Max messages or cooldown                          |
| 401  | Invalid or expired session                        |

## Dashboard (internal use)

Widget management endpoints (list, create, update, rotate keys) require dashboard login. Details in the **API reference** on the Web chat tab.

## All send types

In the API reference (Web chat tab), open **Send widget message** and pick an example in the playground: Session, Message, OTP.

## Next steps

* [Security](/en/ai-web-widget/seguranca): identification modes
* [Tips](/en/ai-web-widget/boas-praticas)
* [AI chat on your site](/en/ai-web-widget/index)