> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/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
description: EU Node.js API server
- url: https://na-gcp-api.vg-stuff.com/v3
description: NA Node.js API server
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:
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:
type: string
enum:
- new
- engaged
- email_sent
- follow_up
- info_req
- demo_req
- demo_conf
- demo_done
- proposal
- negotiation
- trial
- won
- lost
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
countryCode:
type: string
origin: {}
whatsappPhoneNumberId:
type: string
whatsappBusinessNumber:
type: string
whatsappDisplayPhoneNumber:
type: string
whatsappBusinessAccountId:
type: string
voiceflowV4Session:
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
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:
type: string
enum:
- requested_chat
- human-chatting
- ai-chatting
- ended_chat
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
handoffHistory:
type: array
items:
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:
type: array
items:
type: string
description: Team IDs the agent who accepted belongs to
teamKeys:
type: array
items:
type: string
description: Team keys the agent who accepted belongs to
additionalProperties: false
description: Complete history of all handoffs for this conversation
isTyping:
type: boolean
description: >-
Indicates if the human agent is currently typing a
response
lastModified:
type: number
sessionsNum:
type: number
lang:
type: string
vapi:
type: object
properties:
cost:
type: number
callDuration:
type: number
recordingUrl:
type: string
callerPhoneNumber:
type: string
calleePhoneNumber:
type: string
callStatus:
type: string
callError:
type: string
additionalProperties: false
ratingFrom5:
type: number
totalUserInteractions:
type: number
isBlocked:
type: boolean
nodesInfo:
type: object
properties:
currentNode:
type: string
additionalProperties: false
capturedVariables: {}
campaignCalls:
type: array
sessions:
type: array
endReason:
type: string
isTest:
type: boolean
metrics:
type: array
notifyToUserId:
type: string
averageLatency:
type: number
voice:
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
detailedCost:
type: object
properties:
totalCreditsConsumed:
type: number
speechGenCost:
type: number
transcriberCost:
type: number
twilioCost:
type: number
llmCost:
type: number
additionalProperties: false
summary:
type: string
description: >-
This is the summary of the conversation that is
generated by the AI.
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
note:
type: string
assignedTo:
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
hotScore:
type: number
hotLabel:
type: string
enum:
- hot
- warm
- cold
crmActivities:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
type:
type: string
enum:
- Message
- Call
- Email
- Demo
- Meeting
- Follow-Up
- Note
- Stage Change
- Handoff
- System
date:
anyOf:
- type: string
- type: number
dueDate:
anyOf:
- type: string
- type: number
completed:
type: boolean
responded:
type: boolean
firstChannel:
type: string
enum:
- LinkedIn
- WhatsApp
- Instagram
- Facebook
- Email
- Phone/Call
- Zoom/Video
- In Person
- Referral
- Web Chat
- Unknown
firstEngaged:
type: boolean
secondChannel:
type: string
enum:
- LinkedIn
- WhatsApp
- Instagram
- Facebook
- Email
- Phone/Call
- Zoom/Video
- In Person
- Referral
- Web Chat
- Unknown
secondEngaged:
type: boolean
note:
type: string
notesHistory:
type: array
items:
type: object
properties:
agentId:
type: string
agentName:
type: string
text:
type: string
timestamp:
anyOf:
- type: string
- type: number
required:
- text
additionalProperties: false
metadata:
type: object
additionalProperties: {}
required:
- type
additionalProperties: false
crmAlerts:
type: object
properties:
overdueECD:
type: boolean
overdueActivity:
type: boolean
staleLead:
type: boolean
responded:
type: boolean
newHandoffAssigned:
type: boolean
additionalProperties: false
contactIdentityId:
type: string
linkedChannels:
type: array
items:
type: string
crossChannelContext:
type: string
leadScore:
type: number
default: 0
description: Current lead score (0-100)
funnelStepsMatched:
type: array
items:
type: string
default: []
description: Array of matched funnel step IDs
funnelScoreHistory:
type: array
items:
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
default: []
description: History of score changes
funnelNotificationSent:
type: boolean
default: false
description: Whether notification email has been sent
funnelLastEvaluated:
type: number
description: Unix timestamp of last funnel evaluation
funnelExtractedData:
type: object
additionalProperties: {}
description: Extracted business data from conversations
funnelSummary:
type: string
description: >-
AI-generated conversation summary for email
notifications
tokenUsage:
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:
type: object
additionalProperties:
type: object
properties:
modelId:
type: string
inputTokens:
type: number
outputTokens:
type: number
totalTokens:
type: number
usd:
type: number
lastUsedTs:
type: number
additionalProperties: false
additionalProperties: false
description: >-
Cumulative + last-turn LLM token usage for this
conversation
inboundEngagementState:
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.
title:
type: string
lastMessage:
type: string
additionalProperties: false
required:
- success
- message
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````