> ## 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 Agent Conversations
> Retrieves all conversations associated with a specific agent, using the V3 [endpoints](/api-reference/v3/intro).
Returns conversations sorted by timestamp (newest first). Empty conversations without essential data are filtered out.
Use `page` and `limit` query parameters to paginate large conversation lists efficiently.
## Query Parameters
| Parameter | Type | Default | Description |
| --------- | ------ | ------- | -------------------------------- |
| `page` | number | 1 | Page number for pagination |
| `limit` | number | 20 | Number of conversations per page |
## Example Response
```json theme={null}
{
"success": true,
"message": "Conversations 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",
"notes": "Customer interested in premium plan",
"tags": ["new-lead"],
"origin": "web-chat",
"firstMessageTS": 1699999000,
"lastMessageTS": 1699999999
}
]
}
```
## Response Fields
Each conversation in the array includes:
### Lead Information
* `userName`, `userEmail`, `userPhone` - Contact details
* `userAddress`, `userCompany`, `userWebsite` - Additional information
* `notes` - Internal notes about the lead
* `userProfilePic` - Profile picture URL
### Conversation Metadata
* `ID`, `userID` - Identifiers
* `messagesNum` - Message count
* `tags` - Categorization tags
* `origin` - Channel (e.g., "web-chat", "whatsapp")
* Timestamps: `ts`, `firstMessageTS`, `lastMessageTS`
## OpenAPI
````yaml GET /agents/{agentId}/convos
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:
get:
tags:
- Conversations
summary: Get Agent Conversations
description: Retrieves all conversations associated with a specific agent
operationId: conversationRouter-getAgentConvos
parameters:
- name: agentId
in: path
required: true
schema:
type: string
- name: page
in: query
required: false
schema:
anyOf:
- not: {}
- type: number
default: 1
- name: limit
in: query
required: false
schema:
anyOf:
- not: {}
- type: number
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: array
items:
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
- data
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
````