Conversations

Read conversation history, review it, export it, and escalate a thread to a human.

dev · https://api.dev.oprag.ai

7 endpoints. 1 are reachable without a dashboard session — they are listed in the Integration API — and the other 6 require a Cognito JWT. The badge under each path says which.

GET /v1/conversations

Every conversation in the workspace, newest activity first.

Auth Cognito JWT member

Before you call it

  • Sorted by updatedAt, descending.
  • Each row carries channel (dashboard, public, or whatsapp) and source (frontend, api_key, or whatsapp).

Path parameters

None.

Query parameters

Name Type Required Default Description
projectId string Optional — Narrow the result to one project. Omit to span the whole workspace.
cursor string Optional — Opaque cursor from the previous response's nextCursor. Omit for the first page — see pagination. An undecodable cursor is a 400, not an empty page.
limit number Optional 50 Conversations per page. Values above 100 are clamped to 100; a non-numeric or non-positive value falls back to 50.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "conversations": [
    {
      "conversationId": "conv_xyz789",
      "projectId": "proj_abc123",
      "projectName": "Support bot",
      "channel": "public",
      "source": "api_key",
      "preview": "What is your refund policy?",
      "messageCount": 4,
      "reviewStatus": "unresolved",
      "createdAt": "2026-06-30T10:00:00.000Z",
      "updatedAt": "2026-06-30T10:05:00.000Z"
    }
  ],
  "nextCursor": "MjAyNi0wNi0zMFQxMDowNTowMC4wMDBafGNvbnZfeHl6Nzg5"
}

Status codes

Status Meaning
200 Success.
400 cursor could not be decoded.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/conversations' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/conversations/export

Export the workspace's conversations as a CSV download.

Auth Cognito JWT member

Before you call it

  • text/csv, capped at 1,000 rows. The channel column is dashboard, public, or whatsapp; source is frontend, api_key, or whatsapp.

Path parameters

None.

Query parameters

Name Type Required Default Description
projectId string Optional — Narrow the result to one project. Omit to span the whole workspace.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
conversationId,projectId,channel,source,preview,messageCount,rating,reviewStatus,createdAt,updatedAt
conv_xyz789,proj_abc123,public,api_key,What is your refund policy?,4,good,resolved,2026-06-30T10:00:00.000Z,2026-06-30T10:05:00.000Z

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/conversations/export' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/conversations/{conversationId}

One conversation, with a page of its messages.

Auth Cognito JWT member

Before you call it

  • nextCursor is null once there are no earlier messages. Passing it back as cursor is what the dashboard's "Load earlier messages" does.
  • conversation.channel is dashboard, public, or whatsapp.

Path parameters

Name Type Required Description
conversationId string Required Conversation within the project.

Query parameters

Name Type Required Default Description
projectId string Optional — Which project to look in. Skips the workspace-wide scan when you already know it.
cursor string Optional — Opaque cursor from the previous response's nextCursor. Omit for the first page — see pagination. Pages through the conversation's messages, not through conversations.
limit number Optional 100 Messages per page. Values above 200 are clamped to 200; a non-numeric or non-positive value falls back to 100.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "conversation": { "conversationId": "conv_xyz789", "projectId": "proj_abc123", "preview": "What is your refund policy?" },
  "messages": [
    { "messageId": "msg_1", "role": "user", "content": "What is your refund policy?", "createdAt": "2026-06-30T10:00:00.000Z" }
  ],
  "nextCursor": null
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/conversations/{conversationId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
PATCH /v1/conversations/{conversationId}

Update a conversation's review status, rating, and internal notes.

Auth Cognito JWT member

Path parameters

Name Type Required Description
conversationId string Required Conversation within the project.

Query parameters

Name Type Required Default Description
projectId string Optional — Which project to look in. Skips the workspace-wide scan when you already know it.

Body parameters

Name Type Required Description
status "unreviewed" | "unresolved" | "resolved" Optional Review state. Drives the dashboard's conversation queue.
rating "good" | "bad" | null Optional Reviewer's own verdict on the answer. null clears it.
notes string Optional Internal note. Never shown to the visitor.

Request

JSON 
{
  "status": "resolved",
  "rating": "good",
  "notes": "Answer was accurate."
}

Response

200 Success

JSON 
{
  "conversation": {
    "conversationId": "conv_xyz789",
    "projectId": "proj_abc123",
    "reviewStatus": "resolved",
    "rating": "good"
  }
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X PATCH 'https://api.dev.oprag.ai/v1/conversations/{conversationId}' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"status": "resolved","rating": "good","notes": "Answer was accurate."}'
GET /v1/projects/{projectId}/conversations

List a project's conversations.

Auth Cognito JWT member

Before you call it

  • channel is dashboard, public, or whatsapp.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

Name Type Required Default Description
visitorId string Optional — Only conversations belonging to this visitor.
limit number Optional 50 Conversations per page. Values above 100 are clamped to 100; a non-numeric or non-positive value falls back to 50.

Body parameters

None.GET requests carry no body.

Response

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/conversations' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/conversations/{conversationId}

One of a project's conversations, with a page of its messages.

Auth Cognito JWT member

Before you call it

  • The response is a ConversationApiResponse: conversation, messages, and nextCursor.
  • nextCursor is null once there are no earlier messages; pass it back as cursor to page backwards.
  • conversation.channel is dashboard, public, or whatsapp.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
conversationId string Required Conversation within the project.

Query parameters

Name Type Required Default Description
cursor string Optional — Opaque cursor from the previous response's nextCursor. Omit for the first page — see pagination. Pages through the conversation's messages.
limit number Optional 100 Messages per page. Values above 200 are clamped to 200; a non-numeric or non-positive value falls back to 100.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "conversation": { "conversationId": "conv_xyz789", "projectId": "proj_abc123", "channel": "dashboard", "preview": "Summarize onboarding" },
  "messages": [],
  "nextCursor": null
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/conversations/{conversationId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/conversations/{conversationId}/escalate

Hand a public conversation to a human, over a webhook, an email, or both.

Auth Integration key

Before you call it

  • The project needs escalationWebhookUrl or escalationEmail in its settings; without one there is nowhere to escalate to.
  • On the Growth plan and above the escalation is also stored as a native ticket, and emits ticket.created.
  • When a webhook is configured, oprag POSTs the transcript to it over HTTPS with an X-Oprag-Signature: sha256=… header, including ticketId when one was created.
  • Email escalation needs SES_FROM_EMAIL configured.

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
conversationId string Required Conversation within the project.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
visitorId string Required The visitor asking for a human. Required.
subject string Optional Short summary line.
requesterEmail string Optional Email to reply to.
requesterName string Optional Name of the person asking.
message string Optional Body text.

Request

JSON 
{ "visitorId": "visitor_001", "message": "Need billing help" }

Response

200 Success

JSON 
{ "escalated": true, "ticketId": "tkt_abc123" }

Status codes

Status Meaning
200 Escalated. The body is { escalated: true, ticketId? }.
400 The request body failed validation.
401 Missing, revoked, or wrong-environment key.
403 Origin or IP not allowed for this project.
404 No such resource in this workspace.
409 This conversation has already been escalated.
429 Rate limited. See rate limits.
500 A webhook URL is configured but its signing secret is missing.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/conversations/{conversationId}/escalate' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "visitorId": "visitor_001", "message": "Need billing help" }'

SDK equivalent `oprag.conversations.escalate()`

Ready to ship?

Get started free