> ## 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. # Create Conversation > Creates a new conversation for the specified agent, using the V3 [endpoints](/api-reference/v3/intro). ## Example Request ```json theme={null} { "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 ```json theme={null} { "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: | Field | Type | Description | | ---------------- | --------- | ------------------------------------------ | | `userName` | string | User's full name | | `userEmail` | string | User's email address | | `userPhone` | string | User's phone number | | `userAddress` | string | User's physical address | | `userCompany` | string | User's company name | | `userWebsite` | string | User's website URL | | `notes` | string | Internal notes about the conversation/lead | | `userProfilePic` | string | URL to user's profile picture | | `tags` | string\[] | Array of tags for categorization | ## OpenAPI ````yaml POST /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: post: tags: - Conversations summary: Create Conversation description: Creates a new conversation for the specified agent operationId: conversationRouter-createAgentConvo parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: conversation: 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 default: 0 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 required: - ts additionalProperties: false required: - conversation additionalProperties: false 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 - 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 ````