Jelliu API documentation

{
  "data": {
    "conversations": [
      {
        "id": "3f1c2a9e-5b7d-4e8f-9a01-2c3d4e5f6a7b",
        "tenant_id": "9b2e4d1a-7c3f-4a8e-b5d6-1f0e2c3a4b5d",
        "agent_id": "c4a7e2f1-8b3d-4e6a-9f0c-5d2b1a3e7c9f",
        "contact_id": "7d6c5b4a-3f2e-4d1c-8b9a-0e1f2a3b4c5d",
        "channel": "whatsapp",
        "external_id": "wa_5e8a1c2d-4b6f-4a3e-9d7c-0b1a2f3e4d5c_+573001234567",
        "status": "active",
        "metadata": {},
        "created_at": "2026-09-12T14:02:11.000Z",
        "updated_at": "2026-09-14T16:45:03.000Z",
        "closed_at": null,
        "last_inbound_at": "2026-09-14T16:44:58.000Z",
        "needs_human_at": "2026-09-14T16:45:02.000Z",
        "needs_human_reason": "El cliente pide un descuento por volumen que el agente no puede aprobar.",
        "needs_human_resolved_at": null,
        "summary": "María pregunta por precios para 40 unidades y pide un descuento por volumen.",
        "sentiment_score": 0.35,
        "frustration_score": 0.1,
        "sentiment_low": -0.2,
        "outcome": "unknown",
        "evaluation_criteria_results": {},
        "data_collection_results": {
          "interest_level": {
            "rationale": "Pidió cotización formal.",
            "value": "high"
          }
        },
        "analysis_fetched_at": "2026-09-14T16:50:00.000Z",
        "analysis_attempts": 1,
        "cost_credits": 412,
        "cost_usd": "0.0132",
        "termination_reason": null,
        "main_language": "es",
        "call_success_score": null,
        "tool_call_count": 2,
        "mcp_call_count": 0,
        "rag_lookup_count": 1,
        "tool_result_bytes": "1840",
        "contact_name": "María Fernanda Rojas",
        "contact_phone": "+573001234567",
        "contact_status": "pending",
        "agent_name": "Asesora comercial",
        "last_message": "¿Me pueden hacer un descuento si compro 40 unidades?",
        "last_message_at": "2026-09-14T16:44:58.000Z",
        "last_message_role": "user",
        "qualification": {
          "score": 70,
          "interest": "high",
          "answered": true,
          "next_step": null,
          "objections": [
            "precio"
          ],
          "reasons": [
            "interest: high"
          ]
        }
      }
    ],
    "total": 137,
    "page": 1,
    "limit": 25,
    "needsHumanWaiting": 2
  }
}

Returns one page of the workspace’s active conversations across every text channel. Closed conversations are not listed. Fetch a closed one directly with GET /api/conversations/{conversationId}. Each row carries the conversation columns plus the contact’s name, phone and lead status, the agent’s name, a 160-character preview of the last message and a lead qualification score.

Ordering and filtering. By default rows are ordered by updated_at descending (most recent activity first). With needsHuman=waiting only threads where the agent asked for a person and nobody has resolved it yet are returned, ordered by needs_human_at ascending, so the person who has waited longest comes first.

Pagination. Page-number pagination with page and limit. total is the number of matching conversations across all pages. needsHumanWaiting is the workspace-wide count of threads waiting for a person, whatever page or filter you asked for. Invalid values are never rejected: a non-numeric or zero page becomes 1, a non-numeric or zero limit becomes 50, and a limit above 100 is clamped to 100.

Consistency. Pages are cached for up to 30 seconds. An operator reply sent through POST /api/conversations/{conversationId}/messages clears the cache immediately. needsHumanWaiting is never cached.

Access

Required scope: read (or write).
Rate limit: General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See Rate limits.
Plan: Available on every plan.

Returns one page of the workspace's **active** conversations across every text channel. Closed conversations are not listed. Fetch a closed one directly with `GET /api/conversations/{conversationId}`. Each row carries the conversation columns plus the contact's name, phone and lead status, the agent's name, a 160-character preview of the last message and a lead `qualification` score. **Ordering and filtering.** By default rows are ordered by `updated_at` descending (most recent activity first). With `needsHuman=waiting` only threads where the agent asked for a person and nobody has resolved it yet are returned, ordered by `needs_human_at` **ascending**, so the person who has waited longest comes first. **Pagination.** Page-number pagination with `page` and `limit`. `total` is the number of matching conversations across all pages. `needsHumanWaiting` is the workspace-wide count of threads waiting for a person, whatever page or filter you asked for. Invalid values are never rejected: a non-numeric or zero `page` becomes `1`, a non-numeric or zero `limit` becomes `50`, and a `limit` above 100 is clamped to `100`. **Consistency.** Pages are cached for up to 30 seconds. An operator reply sent through `POST /api/conversations/{conversationId}/messages` clears the cache immediately. `needsHumanWaiting` is never cached. **Access** - **Required scope:** `read` (or `write`). - **Rate limit:** General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Query parameters

pageintegerOptional>=1Defaults to 1

1-indexed page number. Non-numeric or values below 1 are treated as 1.

limitintegerOptional1-100Defaults to 50

Conversations per page. Values above 100 are clamped to 100; non-numeric or values below 1 fall back to 50.

needsHumanenumOptional

Pass waiting to list only threads where the agent asked for a person and it is not resolved yet, oldest wait first. Any other value is ignored and the normal list is returned.

Allowed values:

Response

One page of conversations.

dataobject

Errors

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

Access

Required scope: read (or write).
Rate limit: General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See Rate limits.
Plan: Available on every plan.