Skip to main content
POST
/
agents
/
{agentId}
/
convos
Create Conversation
curl --request POST \
  --url https://eu-cloudflare.vg-stuff.com/agents/{agentId}/convos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "ts": 123,
    "userEmail": "<string>",
    "userName": "<string>",
    "userPhone": "<string>",
    "userAddress": "<string>",
    "userCompany": "<string>",
    "userWebsite": "<string>",
    "notes": "<string>",
    "userProfilePic": "<string>",
    "ID": "<string>",
    "userID": "<string>",
    "campaignId": "<string>",
    "userImage": "<string>",
    "socialHandle": "<string>",
    "isFollowingBusiness": true,
    "socialVerified": true,
    "userOs": "<string>",
    "userBrowser": "<string>",
    "origin": "<unknown>",
    "whatsappPhoneNumberId": "<string>",
    "whatsappBusinessNumber": "<string>",
    "whatsappDisplayPhoneNumber": "<string>",
    "whatsappBusinessAccountId": "<string>",
    "messagesNum": 0,
    "interactionsNum": 123,
    "tags": [
      "<string>"
    ],
    "convoTimeSeconds": 123,
    "firstMessageTS": 123,
    "lastMessageTS": 123,
    "userPlatform": "<string>",
    "state": "requested_chat",
    "chatAssignedTo": "<string>",
    "handoffHistory": [
      {
        "requestedAt": 123,
        "acceptedAt": 123,
        "completedAt": 123,
        "acceptedBy": "<string>",
        "organizationId": "<string>",
        "requestedTeamKey": "<string>",
        "teamIds": [
          "<string>"
        ],
        "teamKeys": [
          "<string>"
        ]
      }
    ],
    "isTyping": true,
    "lastModified": 123,
    "sessionsNum": 123,
    "lang": "<string>",
    "vapi": {
      "cost": 123,
      "callDuration": 123,
      "recordingUrl": "<string>",
      "callerPhoneNumber": "<string>",
      "calleePhoneNumber": "<string>",
      "callStatus": "<string>",
      "callError": "<string>"
    },
    "ratingFrom5": 123,
    "totalUserInteractions": 123,
    "isBlocked": true,
    "nodesInfo": {
      "currentNode": "<string>"
    },
    "capturedVariables": "<unknown>",
    "campaignCalls": "<array>",
    "sessions": "<array>",
    "endReason": "<string>",
    "isTest": true,
    "metrics": "<array>",
    "notifyToUserId": "<string>",
    "averageLatency": 123,
    "voice": {
      "latestSessionId": "<string>",
      "listenUrl": "<string>",
      "listenUrlUNIX": 123
    },
    "detailedCost": {
      "totalCreditsConsumed": 123,
      "speechGenCost": 123,
      "transcriberCost": 123,
      "twilioCost": 123,
      "llmCost": 123
    },
    "summary": "<string>",
    "requestedTeamKey": "<string>",
    "delegatedBy": "<string>",
    "delegatedAt": 123,
    "lastViewed": 123,
    "note": "<string>",
    "leadScore": 0,
    "funnelStepsMatched": [],
    "funnelScoreHistory": [],
    "funnelNotificationSent": false,
    "funnelLastEvaluated": 123,
    "funnelExtractedData": {},
    "funnelSummary": "<string>",
    "title": "<string>",
    "lastMessage": "<string>"
  }
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "userEmail": "<string>",
    "userName": "<string>",
    "userPhone": "<string>",
    "userAddress": "<string>",
    "userCompany": "<string>",
    "userWebsite": "<string>",
    "notes": "<string>",
    "userProfilePic": "<string>",
    "ID": "<string>",
    "userID": "<string>",
    "campaignId": "<string>",
    "userImage": "<string>",
    "socialHandle": "<string>",
    "isFollowingBusiness": true,
    "socialVerified": true,
    "userOs": "<string>",
    "userBrowser": "<string>",
    "origin": "<unknown>",
    "whatsappPhoneNumberId": "<string>",
    "whatsappBusinessNumber": "<string>",
    "whatsappDisplayPhoneNumber": "<string>",
    "whatsappBusinessAccountId": "<string>",
    "messagesNum": 123,
    "interactionsNum": 123,
    "ts": 123,
    "tags": [
      "<string>"
    ],
    "convoTimeSeconds": 123,
    "firstMessageTS": 123,
    "lastMessageTS": 123,
    "userPlatform": "<string>",
    "state": "requested_chat",
    "chatAssignedTo": "<string>",
    "handoffHistory": [
      {
        "requestedAt": 123,
        "acceptedAt": 123,
        "completedAt": 123,
        "acceptedBy": "<string>",
        "organizationId": "<string>",
        "requestedTeamKey": "<string>",
        "teamIds": [
          "<string>"
        ],
        "teamKeys": [
          "<string>"
        ]
      }
    ],
    "isTyping": true,
    "lastModified": 123,
    "sessionsNum": 123,
    "lang": "<string>",
    "vapi": {
      "cost": 123,
      "callDuration": 123,
      "recordingUrl": "<string>",
      "callerPhoneNumber": "<string>",
      "calleePhoneNumber": "<string>",
      "callStatus": "<string>",
      "callError": "<string>"
    },
    "ratingFrom5": 123,
    "totalUserInteractions": 123,
    "isBlocked": true,
    "nodesInfo": {
      "currentNode": "<string>"
    },
    "capturedVariables": "<unknown>",
    "campaignCalls": "<array>",
    "sessions": "<array>",
    "endReason": "<string>",
    "isTest": true,
    "metrics": "<array>",
    "notifyToUserId": "<string>",
    "averageLatency": 123,
    "voice": {
      "latestSessionId": "<string>",
      "listenUrl": "<string>",
      "listenUrlUNIX": 123
    },
    "detailedCost": {
      "totalCreditsConsumed": 123,
      "speechGenCost": 123,
      "transcriberCost": 123,
      "twilioCost": 123,
      "llmCost": 123
    },
    "summary": "<string>",
    "requestedTeamKey": "<string>",
    "delegatedBy": "<string>",
    "delegatedAt": 123,
    "lastViewed": 123,
    "note": "<string>",
    "leadScore": 0,
    "funnelStepsMatched": [],
    "funnelScoreHistory": [],
    "funnelNotificationSent": false,
    "funnelLastEvaluated": 123,
    "funnelExtractedData": {},
    "funnelSummary": "<string>",
    "title": "<string>",
    "lastMessage": "<string>"
  }
}

​
Example Request

{
  "conversation": {
    "ts": 1699999999,
    "messagesNum": 0,
    "userName": "John Doe",
    "userEmail": "john@example.com",
    "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": "john@example.com",
    "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

Body

application/json
​
conversation
object
required

Response

Successful response

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