{ "openapi": "3.0.1", "info": { "title": "ChatDash API Documentation", "description": "API Documentation for the ChatDash Server", "version": "2.0.0" }, "servers": [ { "url": "https://api.chat-dash.com/v1/public" } ], "paths": { "/agents/{agentId}/conversations": { "get": { "tags": ["Conversations"], "summary": "Fetch Agent Conversations", "description": "Fetch conversations for a agent with optional filtering. By default, conversations that have the 'record' and 'interacted' fields set to true will be returned (i.e. conversations that are being recorded and have user interaction).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)", "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "description": "Date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)", "schema": { "type": "string" } }, { "name": "record", "in": "query", "description": "Whether to return conversations that are set to be recorded", "schema": { "type": "boolean" } }, { "name": "interacted", "in": "query", "description": "Whether to return conversations that have user interaction", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } }, "500": { "description": "Internal Server Error", "content": {} } } }, "post": { "tags": ["Conversations"], "summary": "Create Conversation", "description": "Create a new conversation for a agent. For best results, fill in as many of the fields as possible when creating a conversation object.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platformId": { "type": "string", "description": "The conversation ID on the original platform" }, "leadId": { "type": "string", "description": "The lead associated with the conversation" }, "name": { "type": "string", "description": "The name of the user who created the conversation" }, "read": { "type": "boolean", "description": "Whether the conversation has been read", "default": false }, "endedAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation ended" }, "browser": { "type": "string", "description": "The browser used for the conversation" }, "device": { "type": "string", "description": "The device used for the conversation" }, "os": { "type": "string", "description": "The operating system used for the conversation" }, "countryCode": { "type": "string", "description": "The country code associated with the user's location (ISO 3166-1 alpha-2)" }, "ipAddress": { "type": "string", "description": "The IP address of the User" }, "record": { "type": "boolean", "description": "Whether to record the conversation", "default": false }, "interacted": { "type": "boolean", "description": "Whether the conversation has user interaction", "default": false }, "channel": { "type": "string", "description": "The channel where the conversation took place" }, "phone": { "type": "string", "description": "The phone number associated with the conversation (FROM number for Retell, CUSTOMER number for Vapi and ElevenLabs)" }, "phoneSecondary": { "type": "string", "description": "The TO phone number for retell, AGENT number for Vapi and ElevenLabs)" }, "instagramId": { "type": "string", "description": "The Instagram ID of the user for Instagram conversations" }, "instagramUsername": { "type": "string", "description": "The Instagram username of the user for Instagram conversations" }, "cost": { "type": "number", "description": "The cost of the conversation (voice ai calls)" }, "duration": { "type": "number", "description": "The duration of the conversation in minutes (voice ai calls)" }, "url": { "type": "string", "description": "The URL of the conversation (recording URL for voice ai)" }, "endedReason": { "type": "string", "description": "The reason the conversation ended (voice ai)" }, "noAnswer": { "type": "boolean", "description": "If the call was not answered (voice ai)" }, "status": { "type": "string", "enum": ["ai", "pending", "human"], "default": "ai", "description": "The status of the conversation" }, "liveAgentName": { "type": "string", "description": "Name of the live agent handling the conversation" }, "liveAgentId": { "type": "string", "description": "ID of the live agent that handled the conversation" }, "isLive": { "type": "boolean", "description": "Whether the conversation is live", "default": false }, "note": { "type": "string", "description": "A note about the conversation" }, "topic": { "type": "string", "description": "The topic associated with the conversation" }, "subtopic": { "type": "string", "description": "The subtopic associated with the conversation" }, "summary": { "type": "string", "description": "Summary of the conversation" }, "evaluation": { "type": "object", "properties": { "isSuccess": { "type": "boolean", "description": "Whether the conversation was successful" }, "reason": { "type": "string", "description": "Reason for the evaluation" } } }, "mistunderstoodQueries": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The misunderstood question" } } } }, "customAnalysis": { "type": "object", "description": "Custom analysis data being imported in from platforms (just voice agents for now)" }, "metadata": { "type": "object", "description": "Metadata associated with the conversation (e.g., custom fields from platforms)" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation added successfully" }, "conversation": { "$ref": "#/components/schemas/Conversation" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}": { "get": { "tags": ["Conversations"], "summary": "Fetch Single Conversation", "description": "Fetch a single conversation by its ID for a specific agent", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent", "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "description": "The ID of the conversation", "schema": { "type": "string" } }, { "name": "isPlatformId", "in": "query", "required": false, "description": "Whether the conversationId provided in the path is the original platform ID from the agent's platform (conversation.platformId) instead of ChatDash's ID for the conversations (conversation._id). Default is false.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "put": { "tags": ["Conversations"], "summary": "Update Conversation", "description": "Update a conversation's read, endedAt, record, interacted, and isLive fields", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent", "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "description": "The ID of the conversation", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platformId": { "type": "string", "description": "The conversation ID on the original platform" }, "leadId": { "type": "string", "description": "The lead associated with the conversation" }, "name": { "type": "string", "description": "The name of the user who created the conversation" }, "read": { "type": "boolean", "description": "Whether the conversation has been read", "default": false }, "endedAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation ended" }, "browser": { "type": "string", "description": "The browser used for the conversation" }, "device": { "type": "string", "description": "The device used for the conversation" }, "os": { "type": "string", "description": "The operating system used for the conversation" }, "countryCode": { "type": "string", "description": "The country code associated with the user's location (ISO 3166-1 alpha-2)" }, "ipAddress": { "type": "string", "description": "The IP address of the User" }, "record": { "type": "boolean", "description": "Whether to record the conversation", "default": false }, "interacted": { "type": "boolean", "description": "Whether the conversation has user interaction", "default": false }, "channel": { "type": "string", "description": "The channel where the conversation took place" }, "phone": { "type": "string", "description": "The phone number associated with the conversation (FROM number for Retell, CUSTOMER number for Vapi and ElevenLabs)" }, "phoneSecondary": { "type": "string", "description": "The TO phone number for retell, AGENT number for Vapi and ElevenLabs)" }, "instagramId": { "type": "string", "description": "The Instagram ID of the user for Instagram conversations" }, "instagramUsername": { "type": "string", "description": "The Instagram username of the user for Instagram conversations" }, "cost": { "type": "number", "description": "The cost of the conversation (voice ai calls)" }, "duration": { "type": "number", "description": "The duration of the conversation in minutes (voice ai calls)" }, "url": { "type": "string", "description": "The URL of the conversation (recording URL for voice ai)" }, "endedReason": { "type": "string", "description": "The reason the conversation ended (voice ai)" }, "noAnswer": { "type": "boolean", "description": "If the call was not answered (voice ai)" }, "status": { "type": "string", "enum": ["ai", "pending", "human"], "default": "ai", "description": "The status of the conversation" }, "liveAgentName": { "type": "string", "description": "Name of the live agent handling the conversation" }, "liveAgentId": { "type": "string", "description": "ID of the live agent that handled the conversation" }, "isLive": { "type": "boolean", "description": "Whether the conversation is live", "default": false }, "note": { "type": "string", "description": "A note about the conversation" }, "topic": { "type": "string", "description": "The topic associated with the conversation" }, "subtopic": { "type": "string", "description": "The subtopic associated with the conversation" }, "summary": { "type": "string", "description": "Summary of the conversation" }, "evaluation": { "type": "object", "properties": { "isSuccess": { "type": "boolean", "description": "Whether the conversation was successful" }, "reason": { "type": "string", "description": "Reason for the evaluation" } } }, "mistunderstoodQueries": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The misunderstood question" } } } }, "customAnalysis": { "type": "object", "description": "Custom analysis data being imported in from platforms (just voice agents for now)" }, "metadata": { "type": "object", "description": "Metadata associated with the conversation (e.g., custom fields from platforms)" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation updated successfully" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "delete": { "tags": ["Conversations"], "summary": "Delete Conversation", "description": "Delete a conversation and its associated messages", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent", "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "description": "The ID of the conversation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation deleted successfully" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } } }, "components": { "schemas": { "Conversation": { "type": "object", "properties": { "_id": { "type": "string", "description": "The ID of the conversation" }, "agentId": { "type": "string", "description": "The agent that the conversations belongs to" }, "platformId": { "type": "string", "description": "The conversation ID on the original platform" }, "leadId": { "type": "string", "description": "The lead associated with the conversation" }, "campaignId": { "type": "string", "description": "The campaign associated with the conversation" }, "name": { "type": "string", "description": "The name of the user who created the conversation" }, "read": { "type": "boolean", "description": "Whether the conversation has been read", "default": false }, "endedAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation ended" }, "browser": { "type": "string", "description": "The browser used for the conversation" }, "device": { "type": "string", "description": "The device used for the conversation" }, "os": { "type": "string", "description": "The operating system used for the conversation" }, "countryCode": { "type": "string", "description": "The country code associated with the user's location (ISO 3166-1 alpha-2)" }, "ipAddress": { "type": "string", "description": "The IP address of the User" }, "record": { "type": "boolean", "description": "Whether the conversation is being recorded", "default": false }, "interacted": { "type": "boolean", "description": "Whether the conversation has been interacted with by a user", "default": false }, "channel": { "type": "string", "description": "The channel where the conversation took place" }, "phone": { "type": "string", "description": "The phone number associated with the conversation (FROM number for Retell, CUSTOMER number for Vapi and ElevenLabs)" }, "phoneSecondary": { "type": "string", "description": "The TO phone number for retell, AGENT number for Vapi and ElevenLabs)" }, "instagramId": { "type": "string", "description": "The Instagram ID of the user for Instagram conversations" }, "instagramUsername": { "type": "string", "description": "The Instagram username of the user for Instagram conversations" }, "cost": { "type": "number", "description": "The cost of the conversation (voice ai calls)" }, "duration": { "type": "number", "description": "The duration of the conversation in minutes (voice ai calls)" }, "url": { "type": "string", "description": "The URL of the conversation (recording URL for voice ai)" }, "endedReason": { "type": "string", "description": "The reason the conversation ended (voice ai)" }, "noAnswer": { "type": "boolean", "description": "If the call was not answered (voice ai)" }, "status": { "type": "string", "enum": ["ai", "pending", "human"], "default": "ai", "description": "The status of the conversation" }, "liveAgentName": { "type": "string", "description": "Name of the live agent handling the conversation" }, "liveAgentId": { "type": "string", "description": "ID of the live agent that handled the conversation" }, "isLive": { "type": "boolean", "description": "Whether the conversation is live", "default": false }, "note": { "type": "string", "description": "A note about the conversation" }, "topic": { "type": "string", "description": "The topic associated with the conversation" }, "subtopic": { "type": "string", "description": "The subtopic associated with the conversation" }, "summary": { "type": "string", "description": "Summary of the conversation" }, "evaluation": { "type": "object", "properties": { "isSuccess": { "type": "boolean", "description": "Whether the conversation was successful" }, "reason": { "type": "string", "description": "Reason for the evaluation" } } }, "mistunderstoodQueries": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The misunderstood question" } } } }, "customAnalysis": { "type": "object", "description": "Custom analysis data being imported in from platforms (just voice agents for now)" }, "metadata": { "type": "object", "description": "Metadata associated with the conversation (e.g., custom fields from platforms)" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation was last updated" } } } } }, "x-original-swagger-version": "2.0" }