Jelliu API documentation

curl -G https://api.jelliu.co/widget/poll \
     -H "x-widget-api-key: 3462145765a6b6c238f79a1e13e10361c24d1740ec30d27bea22dd4106c04284" \
     -H "x-widget-id: 84b5aa0e-f6d6-4d88-b3ad-cd7a5a2aeb9e" \
     -H "x-widget-parent-origin: https://www.clinicasonrisa.co" \
     -d session_id=b3e227dd-a9ea-48ce-9afe-09c21a5d8d2d \
     --data-urlencode since=2026-09-15T13:20:04.512Z \
     -d wid=84b5aa0e-f6d6-4d88-b3ad-cd7a5a2aeb9e

{
  "data": {
    "messages": [
      {
        "id": "33905cc7-5022-4ba0-b376-231c0bdd7f83",
        "role": "agent",
        "content": "Hola María, soy Carolina del equipo de recepción. Ya te reservé el sábado a las 9:00.",
        "created_at": "2026-09-15T13:20:06.118Z"
      }
    ],
    "now": "2026-09-15T13:20:09.771Z"
  }
}

Returns agent-side messages (AI replies and human operator replies from the dashboard) created at or after since, oldest first, at most 50 per call. Visitor messages are not included, because the UI already shows what the visitor typed. Before the visitor’s first message there is no conversation and messages is empty.

Loop: pass the returned now as the next since. The boundary is inclusive, so a message can come back twice; de-duplicate by id (and against message_id from POST /widget/message). If 50 messages come back, poll again immediately with since set to the last message’s created_at.

Credentials, origin check and limits are the same as POST /widget/init. The session must belong to the widget named by the credential. Each poll counts against the per-IP and per-widget budgets, so poll every few seconds, not continuously.

Idempotency. Read-only; safe to retry.

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 per credential and 300 requests/min per workspace; the general limiter also counts 120 requests/min per IP. See Rate limits.
Plan: Available on every plan.

Returns agent-side messages (AI replies and human operator replies from the dashboard) created at or after `since`, oldest first, at most 50 per call. Visitor messages are not included, because the UI already shows what the visitor typed. Before the visitor's first message there is no conversation and `messages` is empty. Loop: pass the returned `now` as the next `since`. The boundary is inclusive, so a message can come back twice; de-duplicate by `id` (and against `message_id` from `POST /widget/message`). If 50 messages come back, poll again immediately with `since` set to the last message's `created_at`. Credentials, origin check and limits are the same as `POST /widget/init`. The session must belong to the widget named by the credential. Each poll counts against the per-IP and per-widget budgets, so poll every few seconds, not continuously. **Idempotency.** Read-only; safe to retry. **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` per credential and 300 requests/min per workspace; the general limiter also counts 120 requests/min per IP. See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

Headers

Query parameters

widstringOptionalformat: "uuid"

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

session_idstringRequiredformat: "uuid"

Session id from POST /widget/init. Not a UUID returns 400 Invalid query.

sincedatetimeOptional

ISO 8601 UTC timestamp (for example the previous response’s now). Messages created at or after it are returned. Omitted means from the start of the conversation. A value that is not an ISO datetime with Z returns 400 Invalid query.

Response

New agent messages (possibly none).

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

503

Service Unavailable Error

Idempotency. Read-only; safe to retry.

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 per credential and 300 requests/min per workspace; the general limiter also counts 120 requests/min per IP. See Rate limits.
Plan: Available on every plan.