Conversations
Sessions between visitors and the agent, with their messages.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
List conversations, newest first
GET /conversations
Scope: conversations:read. Operation id: listConversations.
Sessions the team started from the dashboard are excluded.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
limit | query | integer | Page size, 1 to 200. Default 50. |
cursor | query | string | The nextCursor from the previous page. Opaque; never build one. |
visitorId | query | string (uuid) | |
agentId | query | string (uuid) |
Example request
curl "https://api.showpilot.com/v1/conversations?limit=50" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
One page of conversations.
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of Conversation | yes | |
nextCursor | NextCursor | yes |
Conversation
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
agentId | string (uuid) | yes | |
visitorId | string or null (uuid) | yes | |
channel | chat · voice | yes | |
pageUrl | string or null (uri) | yes | |
referrer | string or null | yes | |
startedAt | string (date-time) | yes | |
lastMessageAt | string or null (date-time) | yes | |
endedAt | string or null (date-time) | yes |
NextCursor
Pass as cursor for the next page; null on the last page.
Errors
| Status | When |
|---|---|
| 400 | A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code invalid-request. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
One conversation with its messages
GET /conversations/{id}
Scope: conversations:read. Operation id: getConversation.
What the visitor asked and what the agent answered. With conversations:read the content comes back with the PEOPLE MASKED — email addresses, phone numbers, card and account numbers, and the visitor's own name are replaced by [email], [phone] and the like, wherever they appear. What was said is left alone. The redaction field then says how many of each were masked. Add the separate conversations:transcripts scope to a key to read them verbatim; it is never granted implicitly, including to an organization admin's connected client.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string (uuid) |
Example request
curl "https://api.showpilot.com/v1/conversations/c0000001-0000-4000-8000-000000000000" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
The conversation and its messages.
Every field of Conversation, plus:
| Field | Type | Always | Meaning |
|---|---|---|---|
messages | array of Message | yes | In order, up to 500. |
redaction | object | yes | Null when nothing was masked, or when the key holds conversations:transcripts. |
Conversation
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
agentId | string (uuid) | yes | |
visitorId | string or null (uuid) | yes | |
channel | chat · voice | yes | |
pageUrl | string or null (uri) | yes | |
referrer | string or null | yes | |
startedAt | string (date-time) | yes | |
lastMessageAt | string or null (date-time) | yes | |
endedAt | string or null (date-time) | yes |
Message
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string | yes | |
role | user · assistant · tool · system | yes | |
authorKind | string | yes | visitor, agent, rep or widget. |
content | string | yes | What was said. Identities are masked unless the key holds conversations:transcripts. |
redacted | boolean | no | True when something in this message was masked. Absent on a verbatim read. |
createdAt | string (date-time) | yes |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |