# Nilo agent integration concepts

Canonical API contract: https://app.nilo-assistant.com/api-docs/openapi.json
Documentation-only API reference: https://app.nilo-assistant.com/api-docs
Canonical human-readable guide: https://app.nilo-assistant.com/public/agent-docs
Base URL: https://app.nilo-assistant.com

## Authentication and scope

The HTTP API is tenant-scoped. Authenticate every request with:

    Authorization: Bearer $NILO_API_KEY

For ordinary tenant API operations, the bearer key determines the tenant. Do not send tenant identifiers in request URLs or bodies. A partner may use the documented customer-provisioning route to request a named API application for a tenant it administers, supplying that tenant's returned URN in the request body. Keep bearer keys in secret storage; never put them in website HTML, browser JavaScript, prompts, request bodies, or logs.

The OpenAPI JSON is the complete source for paths, methods, request schemas, response schemas, status codes, and endpoint-specific rules. The Swagger page is documentation-only and cannot send any request.

Missing, malformed, revoked, or inactive credentials return 401 with an `error` value. Feature availability returns 403 with `{"error":"feature_not_enabled"}`. Do not assume idempotency, cursor pagination, or asynchronous job behavior unless the OpenAPI contract documents it.

## Website widgets

Widget runtime:

    https://app.nilo-assistant.com/public/widgets/v1/embed.js

Get the actual script snippet, publishable widget key, and widget identifiers from the signed-in Nilo Widgets page. Include the script once per website page:

    <script src="https://app.nilo-assistant.com/public/widgets/v1/embed.js"
            data-nilo-public-key="nwpk_…"
            data-nilo-locale="en"
            async></script>

Then use the matching generated custom element where it belongs:

    <nilo-contact-form widget-id="WIDGET_ID"></nilo-contact-form>
    <nilo-chatbot widget-id="WIDGET_ID"></nilo-chatbot>
    <nilo-news widget-id="WIDGET_ID"></nilo-news>
    <nilo-scheduler widget-id="WIDGET_ID"></nilo-scheduler>

Every element supports `widget-id`, optional `public-key`, and optional `locale`. Element values override the script attributes. The runtime also accepts generic elements marked with `data-nilo-widget`, `data-nilo-widget-id`, `data-nilo-public-key`, and `data-nilo-locale`.

The public key is browser-visible by design and is only for public widgets. It is not an API bearer key. The widget runtime owns bootstrap, visitor time zone reporting, submissions, chatbot history, news refresh, and scheduling interactions. Do not directly reimplement its public widget requests in a separate website integration.

### Scheduler visitor copy

`nilo-scheduler` accepts optional attributes that tailor visitor-facing wording for that one placement. They override the localized Nilo defaults. Use a separate localized tag when the website serves each language.

    <nilo-scheduler
      widget-id="WIDGET_ID"
      locale="es"
      title="Hablemos de tu proyecto"
      intro="Elige el momento que mejor te venga."
      booking-cta="Solicitar una llamada"
      details-heading="Tus datos de contacto"
      notes-label="¿En qué podemos ayudarte?"
      notes-placeholder="Describe brevemente tu consulta (opcional)"
      phone-field="optional"
      notes-field="visible"
      success-title="Solicitud recibida"
      success-message="Te enviaremos la confirmación por correo electrónico.">
    </nilo-scheduler>

Opening and confirmation: `title`, `intro`, `booking-cta`, `success-title`, `success-message`.

Date and appointment flow: `date-heading`, `availability-heading`, `choose-date-prompt`, `appointment-heading`.

Contact form: `details-heading`, `first-name-label`, `last-name-label`, `email-label`, `phone-label`, `notes-label`, `notes-placeholder`.

Field choice: `phone-field` accepts `hidden`, `optional`, or `required`; `notes-field` accepts `hidden` or `visible`.

Availability and failure: `empty-availability`, `error-message`.

For generic `data-nilo-widget` mounts, use the `data-nilo-*` equivalent, for example `data-nilo-booking-cta`. Do not omit the subject, first name, last name, or email: the scheduler needs them to handle the appointment request.

## Widget styling

Widgets render in light DOM, not shadow DOM. You can style their `nilo-*` markup from website CSS. Use the optional deployed starter stylesheet:

    <link rel="stylesheet" href="https://app.nilo-assistant.com/public/widgets/v1/nilo-widgets.css">

Override custom properties on the element or a surrounding wrapper: `--nilo-widget-accent`, `--nilo-widget-accent-soft`, `--nilo-widget-surface`, `--nilo-widget-radius`, `--nilo-widget-font-family`.

Stable shared classes: `.nilo-widget`, `.nilo-widget-card`, `.nilo-widget-title`, `.nilo-widget-text`, `.nilo-widget-grid`, `.nilo-field`, `.nilo-input`, `.nilo-submit`, `.nilo-success`.

Chatbot: `.nilo-chatbot-card`, `.nilo-chatbot-messages`, `.nilo-chatbot-message`, `.nilo-chatbot-message--user`, `.nilo-chatbot-send`.

News: `.nilo-news-list`, `.nilo-news-item`, `.nilo-news-date`, `.nilo-news-item-title`.

Scheduler: `.nilo-scheduler-card`, `.nilo-scheduler-layout`, `.nilo-scheduler-slot`, `.nilo-scheduler-calendar-day`, `.is-active`.

Do not remove required inputs or replace interactive buttons with non-buttons. Preserve an accessible focus indicator if overriding the default styles. Scope CSS to widget elements or a wrapper rather than globally styling all forms or buttons on the host website.
