Jelliu API documentation

curl -X POST "https://api.jelliu.co/widget/init?wid=84b5aa0e-f6d6-4d88-b3ad-cd7a5a2aeb9e" \
     -H "x-widget-api-key: 3462145765a6b6c238f79a1e13e10361c24d1740ec30d27bea22dd4106c04284" \
     -H "x-widget-id: 84b5aa0e-f6d6-4d88-b3ad-cd7a5a2aeb9e" \
     -H "x-widget-parent-origin: https://www.clinicasonrisa.co" \
     -H "Content-Type: application/json" \
     -d '{
  "visitor_id": "4c1f8e2a-9b7d-4a6e-8f3c-2d1b0a9e8c7f"
}'

{
  "data": {
    "session_id": "b3e227dd-a9ea-48ce-9afe-09c21a5d8d2d",
    "resumed": false,
    "greeting_message": "¡Hola! ¿En qué te puedo ayudar hoy?",
    "branding": {
      "primary_color": "#1C1D2B",
      "position": "bottom-right",
      "title": "Habla con nosotros",
      "quick_replies": [
        "Agendar una cita",
        "Ver precios"
      ],
      "agent_names": [
        "Laura",
        "Andrés"
      ]
    },
    "voice_enabled": true
  }
}

Credentials. This is a public endpoint. It does not accept a dashboard session or a jl_ API key. Name the widget with exactly one of these, checked in this order:

x-widget-api-key header: the secret plaintext_api_key (server-side callers only);
x-widget-id header: the public widget id (what the embed uses);
wid query parameter: the public widget id.

The API key is never accepted in the query string. A value that looks like a UUID is treated as a widget id, whichever header carries it. Every call must also send x-widget-parent-origin with the origin of the page that embeds the widget; it must match one of the widget’s allowed_origins (scheme and port exactly, hostname modulo one leading www.). The check does not use the browser’s Origin header, and CORS is open (Access-Control-Allow-Origin reflects any origin, no credentials).

Sessions. Sessions are keyed by visitor_id. If the same visitor had a session on this widget that was active in the last 30 days, it is returned with resumed: true and any new metadata is merged into it (keys are added or overwritten, never removed); otherwise a new session is created. Send metadata.email (and metadata.name) to link the visitor’s conversation to a contact.

Side effects. Creates or updates a widget_sessions row (with the caller’s IP and user agent on creation). No conversation is created until the first message; no AI usage is recorded.

Idempotency. Safe to retry with the same visitor_id: a retry resumes the session the first call created. Two truly concurrent first calls for a new visitor can create two sessions.

Access

Required scope: None; jl_ API keys are not used. The widget credential plus a matching x-widget-parent-origin authorise the call.
Rate limit: Widget public — 60 requests/min per IP, plus the widget’s rate_limit_rpm (default 30) per credential and 300 requests/min per workspace across all its widgets; the general limiter also counts 120 requests/min per IP. See Rate limits.
Plan: Available on every plan.

Opens (or resumes) a visitor session and returns what the chat UI needs to render: greeting, branding and whether voice is on. Call it once when the chat loads, then use the returned `session_id` with `POST /widget/message`, `GET /widget/poll` and `GET /widget/history`. The standard embed script does all of this for you. **Credentials.** This is a public endpoint. It does **not** accept a dashboard session or a `jl_` API key. Name the widget with exactly one of these, checked in this order: 1. `x-widget-api-key` header: the secret `plaintext_api_key` (server-side callers only); 2. `x-widget-id` header: the public widget id (what the embed uses); 3. `wid` query parameter: the public widget id. The API key is never accepted in the query string. A value that looks like a UUID is treated as a widget id, whichever header carries it. Every call must also send `x-widget-parent-origin` with the origin of the page that embeds the widget; it must match one of the widget's `allowed_origins` (scheme and port exactly, hostname modulo one leading `www.`). The check does not use the browser's `Origin` header, and CORS is open (`Access-Control-Allow-Origin` reflects any origin, no credentials). **Sessions.** Sessions are keyed by `visitor_id`. If the same visitor had a session on this widget that was active in the last 30 days, it is returned with `resumed: true` and any new `metadata` is merged into it (keys are added or overwritten, never removed); otherwise a new session is created. Send `metadata.email` (and `metadata.name`) to link the visitor's conversation to a contact. **Side effects.** Creates or updates a `widget_sessions` row (with the caller's IP and user agent on creation). No conversation is created until the first message; no AI usage is recorded. **Idempotency.** Safe to retry with the same `visitor_id`: a retry resumes the session the first call created. Two truly concurrent first calls for a new visitor can create two sessions. **Access** - **Required scope:** None; `jl_` API keys are not used. The widget credential plus a matching `x-widget-parent-origin` authorise the call. - **Rate limit:** Widget public — 60 requests/min per IP, plus the widget's `rate_limit_rpm` (default 30) per credential and 300 requests/min per workspace across all its widgets; the general limiter also counts 120 requests/min per IP. See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

Headers

x-widget-parent-originstringRequiredformat: "uri"

Origin (or any URL; only its origin is used) of the page embedding the widget. Must match one of the widget’s allowed_origins. Missing returns 403; an unparseable value returns 403 Invalid parent origin. Only the dashboard preview, which sends a short-lived x-widget-preview-token, may omit it.

Origin (or any URL; only its origin is used) of the page embedding the widget. Must match one of the widget's `allowed_origins`. Missing returns 403; an unparseable value returns 403 `Invalid parent origin`. Only the dashboard preview, which sends a short-lived `x-widget-preview-token`, may omit it.

Query parameters

widstringOptionalformat: "uuid"

Public widget id as a query parameter. Used when neither header is present.

Request

This endpoint expects an object.

visitor_idstringRequired>=1 character

Stable id the embedding page keeps for this visitor (the embed stores a UUID in localStorage). Reusing it within 30 days resumes the same session and conversation.

metadatamap from strings to anyOptional

Free-form visitor data stored on the session (merged on resume). email links the conversation to a contact (created in the workspace’s manual-conversations campaign if none matches, case-insensitively); name fills the contact’s name when it is empty.

Response

Session created or resumed (both return 201).

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

503

Service Unavailable Error

Credentials. This is a public endpoint. It does not accept a dashboard session or a jl_ API key. Name the widget with exactly one of these, checked in this order:

x-widget-api-key header: the secret plaintext_api_key (server-side callers only);
x-widget-id header: the public widget id (what the embed uses);
wid query parameter: the public widget id.

Side effects. Creates or updates a widget_sessions row (with the caller’s IP and user agent on creation). No conversation is created until the first message; no AI usage is recorded.

Idempotency. Safe to retry with the same visitor_id: a retry resumes the session the first call created. Two truly concurrent first calls for a new visitor can create two sessions.

Access

Required scope: None; jl_ API keys are not used. The widget credential plus a matching x-widget-parent-origin authorise the call.
Rate limit: Widget public — 60 requests/min per IP, plus the widget’s rate_limit_rpm (default 30) per credential and 300 requests/min per workspace across all its widgets; the general limiter also counts 120 requests/min per IP. See Rate limits.
Plan: Available on every plan.