Conversations

A conversation is a text thread between one of your contacts and your workspace on one channel: WhatsApp, email, web chat, Instagram or Messenger. Every message in it, from the contact, from the agent or from a person on your team, is stored as a message on that thread. When the agent that answered the thread finishes, Jelliu attaches its analysis to the conversation: a summary, an outcome, sentiment scores and the fields the agent was configured to collect.

With the Conversations API you can read your inbox, open a thread with its messages, start a new WhatsApp or email conversation, reply as a person, and mark threads where the agent asked for human help as handled.

How it works

• One thread per contact and channel. Inbound messages and your own sends are matched to the same conversation by a channel-specific key, so a reply from the contact lands in the thread you started instead of opening a second one. A closed thread is reopened when a new message arrives on it, rather than duplicated.
• Two statuses. A conversation is active or closed. There is no separate “handed off” status: when the agent needs a person it raises a flag on the thread (see Human handoff) and keeps answering.
• Analysis arrives later. The analysis is produced after the exchange ends. A background sweep runs every 90 seconds, picks up threads that have been quiet for at least 3 minutes, and stores the result. Until then every analysis field is null (or {} for the two result objects). Each new agent turn resets analysis_fetched_at, and the analysis is fetched again, covering the whole thread, once it goes quiet.

Object

Conversation

Returned by GET /api/conversations (one per item) and GET /api/conversations/{conversationId}. Both endpoints shape the conversation the same way: the stored columns plus a few fields joined from the contact, the agent and the latest message.

qualification has this shape:

Message

Returned in the messages array of GET /api/conversations/{conversationId}.

Keys you may find in metadata:

Treat metadata as informational: read the keys you need and ignore the rest.

Human handoff

An agent working a text channel can decide that a person has to step in: a refund it is not allowed to approve, a request for a manager, a question about something it cannot see. When that happens:

1. The conversation gets needs_human_at and needs_human_reason, and your workspace receives an in-app notification.
2. The contact is told nothing. The thread is not closed or paused, and the agent keeps answering normally.
3. Raising the flag again while it is still waiting does nothing, so needs_human_at keeps meaning “waiting since”.
4. A person reads the thread, optionally replies with POST /api/conversations/{conversationId}/messages, and marks it handled with POST /api/conversations/{conversationId}/needs-human/resolve. Resolving sends nothing to the contact.

The flag is closed, not erased: needs_human_at and needs_human_reason remain and needs_human_resolved_at is set. If the agent raises it again later, a new episode starts.

Every list response carries needsHumanWaiting, the number of threads waiting across the whole workspace, independent of the page you asked for.

Common tasks

Read the inbox

curl -sS "https://api.jelliu.co/api/conversations?page=1&limit=50" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": {
    "conversations": [
      {
        "id": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36",
        "tenant_id": "b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
        "agent_id": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
        "contact_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "channel": "whatsapp",
        "external_id": "wa_0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90_+573001234567",
        "status": "active",
        "metadata": null,
        "created_at": "2026-09-14T13:02:11.482Z",
        "updated_at": "2026-09-14T15:40:52.117Z",
        "closed_at": null,
        "last_inbound_at": "2026-09-14T15:40:31.905Z",
        "needs_human_at": null,
        "needs_human_reason": null,
        "needs_human_resolved_at": null,
        "elevenlabs_conversation_id": "conv_4201k52xq7d9f0a8b3c6e5g1h2j4",
        "summary": null,
        "outcome": null,
        "sentiment_score": null,
        "frustration_score": null,
        "sentiment_low": null,
        "evaluation_criteria_results": {},
        "data_collection_results": {},
        "analysis_fetched_at": null,
        "analysis_attempts": 0,
        "cost_credits": null,
        "cost_usd": null,
        "termination_reason": null,
        "main_language": null,
        "call_success_score": null,
        "tool_call_count": null,
        "mcp_call_count": null,
        "rag_lookup_count": null,
        "tool_result_bytes": null,
        "contact_name": "Ana Gómez",
        "contact_status": "pending",
        "agent_name": "Asesora comercial",
        "last_message_at": "2026-09-14T15:40:52.101Z",
        "last_message_role": "agent",
        "qualification": {
          "score": null,
          "interest": null,
          "answered": null,
          "next_step": null,
          "objections": [],
          "reasons": ["..."]
        },
        "contact_phone": "+573001234567",
        "last_message": "Claro, te comparto los horarios disponibles para esta semana."
      }
    ],
    "total": 128,
    "page": 1,
    "limit": 50,
    "needsHumanWaiting": 2
  }
}

curl -sS "https://api.jelliu.co/api/conversations/3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": {
    "id": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36",
    "channel": "whatsapp",
    "status": "active",
    "contact_name": "Ana Gómez",
    "summary": "La clienta ya compró el plan anual y pidió ayuda para cambiar el método de pago.",
    "outcome": "success",
    "sentiment_score": 0.4,
    "frustration_score": 0.1,
    "sentiment_low": -0.2,
    "data_collection_results": {
      "tipo_visitante": { "value": "cliente", "rationale": "Mencionó su suscripción activa." }
    },
    "analysis_fetched_at": "2026-09-14T15:47:03.552Z",
    "qualification": {
      "score": null,
      "interest": null,
      "answered": null,
      "next_step": null,
      "objections": [],
      "reasons": ["Es un cliente actual, no un lead: no se califica."]
    },
    "messages": [
      {
        "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
        "conversation_id": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36",
        "tenant_id": "b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
        "role": "user",
        "content_type": "image",
        "content": "Este es el comprobante",
        "audio_url": null,
        "metadata": {
          "attachment": { "filename": "comprobante.jpg", "content_type": "image/jpeg", "bytes": 184233 },
          "inbound_message_id": "SM8f2a1b3c4d5e6f7a8b9c0d1e2f3a4b5c"
        },
        "created_at": "2026-09-14T15:40:31.905Z",
        "attachment": { "filename": "comprobante.jpg", "contentType": "image/jpeg", "bytes": 184233 }
      },
      {
        "id": "d8e9f0a1-2b3c-4d4e-9f5a-6b7c8d9e0f1a",
        "conversation_id": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36",
        "tenant_id": "b2e4c6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
        "role": "agent",
        "content_type": "text",
        "content": "Gracias, Ana. Ya lo recibí y lo reviso enseguida.",
        "audio_url": null,
        "metadata": { "source": "ai_reply", "tokens_used": 412 },
        "created_at": "2026-09-14T15:40:52.101Z",
        "attachment": null
      }
    ]
  }
}

Start a conversation

POST /api/conversations sends a first message to a phone number on WhatsApp or an email address, and creates or reuses the thread for it.

What happens:

1. Jelliu looks for an existing contact in your workspace: by WhatsApp number for whatsapp, by email (case-insensitive) for email. A contact that already belongs to a campaign is reused and not moved.
2. If none exists, a contact is created in a workspace campaign named Manual Conversations, created on first use and bound to your oldest agent. A workspace with no agents gets 422.
3. The message is sent through the channel, with all of its checks: opt-out, suppression list, the WhatsApp 24-hour window and allowed hours, and the daily send cap.
4. Only after a successful send is the thread created (or reopened) and the message stored with role: "agent".

curl -sS -X POST "https://api.jelliu.co/api/conversations" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "recipient": "+573001234567",
    "templateId": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "templateVariables": ["Ana", "martes 16 de septiembre"]
  }'

{
  "data": {
    "conversationId": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36",
    "contactId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "channel": "whatsapp",
    "externalMessageId": "SM2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c"
  }
}

externalMessageId is the provider’s message ID for WhatsApp and null for email.

Reply to a conversation

POST /api/conversations/{conversationId}/messages sends a reply written by a person on your team. The agent is not invoked: only your text is delivered and stored.

Delivery depends on the thread’s channel:

The provider is called before the message is stored, so a rejected send never leaves a message in the thread that the contact did not receive.

curl -sS -X POST "https://api.jelliu.co/api/conversations/3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36/messages" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hola Ana, soy Laura del equipo de soporte. Ya actualicé tu método de pago." }'

{
  "data": {
    "messageId": "e9f0a1b2-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
    "conversationId": "3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36"
  }
}

Resolve a handoff request

curl -sS "https://api.jelliu.co/api/conversations?needsHuman=waiting" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

curl -sS -X POST "https://api.jelliu.co/api/conversations/3f6a2c1e-8b4d-4f7a-9e2b-5c8d1a0f7e36/needs-human/resolve" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{ "data": { "resolved": true } }

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Esta conversación no está esperando a nadie."
  }
}

Talk to an agent over web chat

POST /api/webchat/message sends a message as a visitor and returns the agent’s reply in the same response. Use it for a custom chat interface on your own backend, or to test an agent. To embed chat on a website, use the web chat widget instead.

curl -sS -X POST "https://api.jelliu.co/api/webchat/message" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "visitorId": "visitor_8f3a2b1c",
    "message": "Hola, ¿qué planes tienen?"
  }'

{
  "data": {
    "conversationId": "4a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
    "reply": "¡Hola! Con gusto te cuento. ¿Para cuántas personas de tu equipo lo necesitas?"
  }
}

Two related endpoints work on the same threads: GET /api/webchat/{conversationId}/history returns { id, role, content, contentType, createdAt } for each message (the same first-50 cap applies), and POST /api/webchat/{conversationId}/close closes the conversation and returns { "data": { "closed": true } }.

Agent replies and silence

A few rules decide whether the agent answers at all. They apply to every text channel.

• Reply budget. The agent sends at most 10 AI replies per conversation in any 24 hours. When the budget is spent, the contact receives one fixed closing notice (stored with metadata.source: "canned_reply" and canned: "budget"), the thread is flagged for a person and closed. Replies from your team, fixed notices and recorded outbound emails do not count toward the budget.
• Paused or deleted agent. A paused agent answers with a fixed notice and the thread stays open, so it resumes where it left off. A thread whose agent was deleted is answered with a notice and closed; no other agent takes over.
• Opt-out means total silence. A WhatsApp message that is exactly an opt-out keyword (STOP, STOPALL, STOP ALL, CANCEL, UNSUBSCRIBE, QUIT, END, BAJA, CANCELAR, DARME DE BAJA, DAR DE BAJA, NO MOLESTAR, case-insensitive, trailing punctuation ignored), or a clear request not to be contacted, marks every matching contact as dnc, adds the number to your suppression list and sends nothing back, not even a confirmation. From then on, API sends to that contact are refused.

Errors

Validation failures return 400 VALIDATION_FAILED with a field map in details (see Errors). Refusals from the messaging channel use the standard envelope with the codes below. Note that some of them use 423.

A provider refusal looks like this:

{
  "error": {
    "code": "OUTSIDE_24H_WINDOW",
    "message": "Outside the 24-hour window: this contact has not messaged you in the last 24h, so Meta requires an approved template to reach them. Pick a template to send."
  }
}

Limits

See Rate limits for the per-plan general limit and Authentication for scopes. None of these endpoints requires a full key.

Other limits:

• Daily send caps. Each workspace can send up to 1,000 WhatsApp messages and 1,000 emails per day by default. A failed send does not consume the cap. Contact support to raise it.
• Plan allowance. AI replies on text channels, web chat included, count toward your plan’s monthly included chat messages.
• Reply budget. 10 AI replies per conversation per 24 hours, as described in Agent replies and silence.
• Freshness. List and detail responses are cached for up to 30 seconds. A reply sent through the API clears the cache for its conversation and your inbox, so an immediate re-read includes it.

Webhooks

There are no dedicated conversation events. Related events from the catalog:

To react to new messages or handoff requests, poll GET /api/conversations (for example with needsHuman=waiting) and compare updated_at and last_message_at.

Related