Skip to main content
POST
/
agents
/
{agentId}
/
convos
Create Conversation
curl --request POST \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "ts": 123,
    "messagesNum": 0,
    "title": "<string>",
    "userID": "<string>"
  }
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "ID": "<string>",
    "ts": 123,
    "messagesNum": 123,
    "title": "<string>",
    "state": "open",
    "origin": "web",
    "userID": "<string>",
    "tags": [
      "<string>"
    ],
    "user": {},
    "feedback": {}
  }
}

​
Example Request

{
  "conversation": {
    "ts": 1699999999,
    "messagesNum": 0,
    "userName": "John Doe",
    "userEmail": "[email protected]",
    "userPhone": "+1234567890",
    "userCompany": "Acme Corp",
    "notes": "Customer interested in premium plan, follow up next week",
    "tags": ["new-lead"]
  }
}

​
Example Response

{
  "success": true,
  "message": "Successfully created conversation: agent123_convo456",
  "data": {
    "ID": "agent123_convo456",
    "userID": "agent123_convo456",
    "ts": 1699999999,
    "messagesNum": 0,
    "userName": "John Doe",
    "userEmail": "[email protected]",
    "userPhone": "+1234567890",
    "userCompany": "Acme Corp",
    "notes": "Customer interested in premium plan, follow up next week",
    "tags": ["new-lead"],
    "lastModified": 1699999999
  }
}

​
Notes

  • A unique conversation ID is auto-generated
  • The ts field (timestamp) is required
  • You must own the agent to create conversations for it

​
Available Lead Fields

The conversation object supports the following optional lead fields:
FieldTypeDescription
userNamestringUser’s full name
userEmailstringUser’s email address
userPhonestringUser’s phone number
userAddressstringUser’s physical address
userCompanystringUser’s company name
userWebsitestringUser’s website URL
notesstringInternal notes about the conversation/lead
userProfilePicstringURL to user’s profile picture
tagsstring[]Array of tags for categorization

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

Body

application/json
​
conversation
object
required

Response

Conversation created successfully

​
success
boolean
required
​
message
string
required
​
data
object
required

Conversation object with full details