> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Single Conversation
> Retrieves details of a specific conversation for the specified agent, using the V3 [endpoints](/api-reference/v3/intro).
Returns full conversation metadata including lead information. You must own the agent to access its conversations.
Use this endpoint to fetch conversation details before exporting or to check user feedback status.
## Example Response
```json theme={null}
{
"success": true,
"message": "Conversation retrieved successfully",
"data": {
"ID": "agent123_convo456",
"userID": "agent123_convo456",
"ts": 1699999999,
"messagesNum": 5,
"userName": "John Doe",
"userEmail": "john@example.com",
"userPhone": "+1234567890",
"userCompany": "Acme Corp",
"userAddress": "123 Main St, City, State",
"userWebsite": "https://acme.com",
"notes": "Customer interested in premium plan, follow up next week",
"tags": ["new-lead", "high-priority"],
"origin": "web-chat",
"state": "ai-chatting",
"firstMessageTS": 1699999000,
"lastMessageTS": 1699999999,
"lastModified": 1699999999
}
}
```
## Response Fields
The response includes all conversation metadata:
### Lead Information
* `userName`, `userEmail`, `userPhone` - Contact information
* `userAddress`, `userCompany`, `userWebsite` - Additional details
* `notes` - Internal notes about the conversation/lead
* `userProfilePic` - Profile picture URL
### Conversation Data
* `ID`, `userID` - Identifiers
* `messagesNum` - Number of messages exchanged
* `tags` - Categorization tags
* `state` - Current conversation state
* `origin` - Channel (e.g., "web-chat", "whatsapp")
* Timestamps: `ts`, `firstMessageTS`, `lastMessageTS`, `lastModified`
## OpenAPI
````yaml GET /agents/{agentId}/convos/{convoId}
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
security: []
paths:
/agents/{agentId}/convos/{convoId}:
get:
tags:
- Conversations
summary: Get Single Conversation
description: Retrieves details of a specific conversation for the specified agent
operationId: conversationRouter-getAgentConvo
parameters:
- name: agentId
in: path
required: true
schema:
type: string
- name: convoId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/object_d0bce89d'
required:
- success
- message
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
schemas:
object_d0bce89d:
type: object
properties:
userEmail:
type: string
userName:
type: string
userPhone:
type: string
userAddress:
type: string
userCompany:
type: string
userWebsite:
type: string
notes:
type: string
userProfilePic:
type: string
stage:
$ref: '#/components/schemas/string_015e8ef8'
value:
anyOf:
- type: number
- type: string
currency:
type: string
expectedCloseDate:
type: string
subIndustry:
type: string
source:
type: string
language:
type: string
linkedIn:
type: string
facebook:
type: string
instagram:
type: string
demoDate:
type: string
demoTime:
type: string
demoLink:
type: string
lostReason:
type: string
lastActivityDate:
anyOf:
- type: string
- type: number
ID:
type: string
userID:
type: string
description: >-
UserID/ConvoID it is the phone number of the user if it is a call
and is NOT unique for every individual call/conversation.
campaignId:
type: string
description: The campaign id that the call may belong to.
userImage:
type: string
description: >-
This is the image of the user that is used to display in the lead
card.
socialHandle:
type: string
isFollowingBusiness:
type: boolean
socialVerified:
type: boolean
userOs:
type: string
userBrowser:
type: string
ipAddress:
type: string
browserTimezone:
type: string
description: >-
IANA timezone auto-detected from the visitor's browser
(Intl.DateTimeFormat), used to skip asking for timezone on
calendar/scheduling flows.
countryCode:
type: string
origin: {}
whatsappPhoneNumberId:
type: string
whatsappBusinessNumber:
type: string
whatsappDisplayPhoneNumber:
type: string
whatsappBusinessAccountId:
type: string
voiceflowV4Session:
$ref: >-
#/components/schemas/sessionKey_projectId_environmentAlias_updatedAt_8d33a7
messagesNum:
type: number
interactionsNum:
type: number
ts:
type: number
tags:
type: array
items:
type: string
convoTimeSeconds:
type: number
firstMessageTS:
type: number
lastMessageTS:
type: number
userPlatform:
type: string
state:
$ref: '#/components/schemas/string_ce724de6'
smbContact:
type: boolean
smbContactName:
type: string
smbContactRemovedAt:
type: number
smbLastSeenAt:
type: number
humanClaimedAt:
type: number
nullable: true
humanLastRepliedAt:
type: number
nullable: true
pendingAiReplyAt:
type: number
nullable: true
chatAssignedTo:
type: string
chatAssignedToIds:
type: array
items:
type: string
assignedToUsers:
type: array
items:
$ref: '#/components/schemas/object_ea6297dc'
handoffHistory:
$ref: '#/components/schemas/array_514028d6'
isTyping:
type: boolean
description: Indicates if the human agent is currently typing a response
lastModified:
type: number
sessionsNum:
type: number
lang:
type: string
vapi:
$ref: '#/components/schemas/object_c0b635a3'
ratingFrom5:
type: number
totalUserInteractions:
type: number
isBlocked:
type: boolean
nodesInfo:
$ref: '#/components/schemas/currentNode_f37652'
capturedVariables: {}
campaignCalls:
type: array
items: {}
sessions:
type: array
items: {}
endReason:
type: string
isTest:
type: boolean
metrics:
type: array
items: {}
notifyToUserId:
type: string
averageLatency:
type: number
voice:
$ref: '#/components/schemas/latestSessionId_listenUrl_listenUrlUNIX_d762bb'
detailedCost:
$ref: >-
#/components/schemas/totalCreditsConsumed_speechGenCost_transcriberCost_twilioCost_8e1967
summary:
type: string
description: This is the summary of the conversation that is generated by the AI.
shortSummary:
type: string
description: >-
Web-chat only: 3-4 word sidebar title generated with the long AI
summary.
requestedTeamKey:
type: string
delegatedBy:
type: string
description: ID of the user who delegated this chat
delegatedAt:
type: number
description: Unix timestamp when the chat was delegated
lastViewed:
type: number
description: Unix timestamp when the conversation was last viewed/opened
isArchived:
type: boolean
description: Whether the conversation has been moved to the archive
archivedAt:
type: number
description: Unix timestamp when the conversation was archived
archivedBy:
type: string
description: Email or uid of the user who archived the conversation
isResolved:
type: boolean
description: >-
Whether a human marked this conversation resolved (and passed back
to AI)
resolvedAt:
type: number
description: Unix ms when the conversation was resolved
resolvedBy:
type: string
description: Client ID of the human who clicked Resolve
resolvedByEmail:
type: string
description: Email of the human who resolved (for display/tags)
lastResolvedAssigneeId:
type: string
description: Stable assignee to notify if the chat is reopened
reopenedAt:
type: number
description: Unix ms when a resolved chat was reopened
reopenReason:
type: string
description: Short reason from AI when auto-reopening after customer reply
csat:
$ref: >-
#/components/schemas/satisfaction10_ease10_comment_submittedAt_6270d3
note:
type: string
assignedTo:
$ref: '#/components/schemas/object_ea6297dc'
hotScore:
type: number
hotLabel:
type: string
enum:
- hot
- warm
- cold
crmActivities:
type: array
items:
$ref: '#/components/schemas/object_dc83268b'
crmAlerts:
$ref: >-
#/components/schemas/overdueECD_overdueActivity_staleLead_responded_9dc18b
contactIdentityId:
type: string
linkedChannels:
type: array
items:
type: string
crossChannelContext:
type: string
leadScore:
type: number
default: 0
description: Current lead score (0-100)
funnelStepsMatched:
$ref: '#/components/schemas/array_b2ca0742'
funnelScoreHistory:
$ref: '#/components/schemas/array_ab56e734'
funnelNotificationSent:
$ref: '#/components/schemas/boolean_b29b0a71'
funnelLastEvaluated:
type: number
description: Unix timestamp of last funnel evaluation
funnelExtractedData:
$ref: '#/components/schemas/object_302324ac'
funnelSummary:
type: string
description: AI-generated conversation summary for email notifications
tokenUsage:
$ref: '#/components/schemas/object_c0a62c0b'
inboundEngagementState:
$ref: '#/components/schemas/object_54e6261a'
title:
type: string
lastMessage:
type: string
additionalProperties: false
string_015e8ef8:
type: string
enum:
- new
- engaged
- email_sent
- follow_up
- info_req
- demo_req
- demo_conf
- demo_done
- proposal
- negotiation
- trial
- won
- lost
sessionKey_projectId_environmentAlias_updatedAt_8d33a7:
type: object
properties:
sessionKey:
type: string
projectId:
type: string
environmentAlias:
type: string
updatedAt:
type: number
resolvedRuntime:
type: string
enum:
- legacy
- v4
required:
- sessionKey
- projectId
additionalProperties: false
description: >-
Voiceflow v4 session key persisted on the chat/convo doc for
cross-request continuity
string_ce724de6:
type: string
enum:
- requested_chat
- human-chatting
- ai-chatting
- ended_chat
object_ea6297dc:
type: object
properties:
userId:
type: string
name:
type: string
email:
type: string
photoUrl:
type: string
note:
type: string
assignedAt:
anyOf:
- type: string
- type: number
status:
type: string
enum:
- pending
- accepted
- done
required:
- userId
additionalProperties: false
array_514028d6:
type: array
items:
$ref: '#/components/schemas/object_d4f753e9'
description: Complete history of all handoffs for this conversation
object_c0b635a3:
type: object
properties:
cost:
type: number
callDuration:
type: number
recordingUrl:
type: string
syncRecordingUrl:
type: string
callerPhoneNumber:
type: string
calleePhoneNumber:
type: string
callStatus:
type: string
callError:
type: string
additionalProperties: false
currentNode_f37652:
type: object
properties:
currentNode:
type: string
additionalProperties: false
latestSessionId_listenUrl_listenUrlUNIX_d762bb:
type: object
properties:
latestSessionId:
type: string
listenUrl:
type: string
description: This is the url that is used to listen to the call in realtime.
listenUrlUNIX:
type: number
additionalProperties: false
totalCreditsConsumed_speechGenCost_transcriberCost_twilioCost_8e1967:
type: object
properties:
totalCreditsConsumed:
type: number
speechGenCost:
type: number
transcriberCost:
type: number
twilioCost:
type: number
llmCost:
type: number
additionalProperties: false
satisfaction10_ease10_comment_submittedAt_6270d3:
type: object
properties:
satisfaction10:
type: number
minimum: 1
maximum: 10
ease10:
type: number
minimum: 1
maximum: 10
comment:
type: string
submittedAt:
type: number
channel:
type: string
surveyVersion:
type: number
additionalProperties: false
description: Post-resolve CSAT scores (1-10), separate from ratingFrom5
object_dc83268b:
type: object
properties:
id:
type: string
title:
type: string
type:
$ref: '#/components/schemas/string_3f503ce4'
date:
anyOf:
- type: string
- type: number
dueDate:
anyOf:
- type: string
- type: number
completed:
type: boolean
responded:
type: boolean
firstChannel:
$ref: '#/components/schemas/string_24adc72c'
firstEngaged:
type: boolean
secondChannel:
$ref: '#/components/schemas/string_24adc72c'
secondEngaged:
type: boolean
note:
type: string
notesHistory:
$ref: '#/components/schemas/array_a78409b8'
metadata:
type: object
additionalProperties: {}
required:
- type
additionalProperties: false
overdueECD_overdueActivity_staleLead_responded_9dc18b:
type: object
properties:
overdueECD:
type: boolean
overdueActivity:
type: boolean
staleLead:
type: boolean
responded:
type: boolean
newHandoffAssigned:
type: boolean
additionalProperties: false
array_b2ca0742:
type: array
items:
type: string
default: []
description: Array of matched funnel step IDs
array_ab56e734:
type: array
items:
$ref: '#/components/schemas/object_b7a75c76'
default: []
description: History of score changes
boolean_b29b0a71:
type: boolean
default: false
description: Whether notification email has been sent
object_302324ac:
type: object
additionalProperties: {}
description: Extracted business data from conversations
object_c0a62c0b:
type: object
properties:
cumulativeInputTokens:
type: number
cumulativeOutputTokens:
type: number
cumulativeTotalTokens:
type: number
cumulativeUsd:
type: number
lastTurnInputTokens:
type: number
lastTurnOutputTokens:
type: number
lastTurnTotalTokens:
type: number
lastTurnUsd:
type: number
lastTurnModelId:
type: string
lastTurnContextWindow:
type: number
lastTurnInputUsdPer1k:
type: number
lastTurnOutputUsdPer1k:
type: number
lastTurnTs:
type: number
usagePerModel:
$ref: '#/components/schemas/object_9fd4236e'
additionalProperties: false
description: Cumulative + last-turn LLM token usage for this conversation
object_54e6261a:
type: object
properties:
firstDecisionAt:
type: number
firstDecisionShouldReply:
type: boolean
lastDecisionAt:
type: number
lastDecisionShouldReply:
type: boolean
lastDecisionReason:
type: string
aiOwnedThread:
type: boolean
ignoreThread:
type: boolean
lastTriggeredBy:
type: string
enum:
- phrase
- ai_rule
- ownership
additionalProperties: false
description: >-
Per-thread state for inbound engagement decisions, ownership, and
persistent ignore/reply behavior.
message_11569e:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
object_d4f753e9:
type: object
properties:
requestedAt:
type: number
acceptedAt:
type: number
completedAt:
type: number
acceptedBy:
type: string
description: Agent ID who accepted
organizationId:
type: string
description: >-
Organization ID that accepted the handoff. Set to "convocore" for
main dashboard, or the org ID for specific organizations
requestedTeamKey:
type: string
teamIds:
$ref: '#/components/schemas/array_1a29d528'
teamKeys:
$ref: '#/components/schemas/array_fa08fae4'
additionalProperties: false
string_3f503ce4:
type: string
enum:
- Message
- Call
- Email
- Demo
- Meeting
- Follow-Up
- Note
- Stage Change
- Handoff
- System
string_24adc72c:
type: string
enum:
- LinkedIn
- WhatsApp
- Instagram
- Facebook
- Email
- Phone/Call
- Zoom/Video
- In Person
- Referral
- Web Chat
- Unknown
array_a78409b8:
type: array
items:
$ref: '#/components/schemas/agentId_agentName_text_timestamp_53e777'
object_b7a75c76:
type: object
properties:
timestamp:
type: number
stepId:
type: string
stepName:
type: string
pointsAdded:
type: number
newScore:
type: number
extractedData:
type: object
additionalProperties: {}
messageContext:
type: string
required:
- timestamp
- stepId
- stepName
- pointsAdded
- newScore
additionalProperties: false
object_9fd4236e:
type: object
additionalProperties:
$ref: >-
#/components/schemas/modelId_inputTokens_outputTokens_totalTokens_99d4fb
array_1a29d528:
type: array
items:
type: string
description: Team IDs the agent who accepted belongs to
array_fa08fae4:
type: array
items:
type: string
description: Team keys the agent who accepted belongs to
agentId_agentName_text_timestamp_53e777:
type: object
properties:
agentId:
type: string
agentName:
type: string
text:
type: string
timestamp:
anyOf:
- type: string
- type: number
required:
- text
additionalProperties: false
modelId_inputTokens_outputTokens_totalTokens_99d4fb:
type: object
properties:
modelId:
type: string
inputTokens:
type: number
outputTokens:
type: number
totalTokens:
type: number
usd:
type: number
lastUsedTs:
type: number
additionalProperties: false
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
$ref: '#/components/schemas/message_11569e'
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````