Skip to main content
GET
/
agents
/
{agentId}
/
convos
Get Agent Conversations
curl --request GET \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "<string>",
  "data": [
    {
      "ID": "<string>",
      "ts": 123,
      "messagesNum": 123,
      "title": "<string>",
      "state": "open",
      "origin": "web",
      "userID": "<string>",
      "tags": [
        "<string>"
      ],
      "user": {},
      "feedback": {}
    }
  ]
}
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

ParameterTypeDefaultDescription
pagenumber1Page number for pagination
limitnumber20Number of conversations per page

​
Example Response

{
  "success": true,
  "message": "Conversations retrieved successfully",
  "data": [
    {
      "ID": "agent123_convo456",
      "userID": "agent123_convo456",
      "ts": 1699999999,
      "messagesNum": 5,
      "userName": "John Doe",
      "userEmail": "[email protected]",
      "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

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agentId
string
required

The unique identifier of the agent

Query Parameters

​
page
integer
default:1

Page number for pagination

Required range: x >= 1
​
limit
integer
default:20

Number of conversations per page (max 100)

Required range: x >= 1

Response

Conversations retrieved successfully

​
success
boolean
required

Indicates if the request was successful

​
message
string
required

Response message

​
data
object[]
required

Array of conversation objects