# Create an agent Source: https://api.livechatai.com/api-reference-v2/agents/create post /api/v2/agents Create a new AI agent in your workspace # Delete an agent Source: https://api.livechatai.com/api-reference-v2/agents/delete delete /api/v2/agents/{agentId} Delete an agent permanently # List agents Source: https://api.livechatai.com/api-reference-v2/agents/list get /api/v2/agents List all agents in your workspace. Supports pagination to help manage large datasets efficiently. # Retrieve an agent Source: https://api.livechatai.com/api-reference-v2/agents/retrieve get /api/v2/agents/{agentId} Retrieve a specific agent by ID or slug # Delete AI Suggestion Source: https://api.livechatai.com/api-reference-v2/ai-suggestions/delete delete /api/v2/ai-suggestions/{suggestionId} Delete (dismiss) an AI suggestion. This marks the suggestion as ignored and it will no longer appear in the suggestions list. # List AI Suggestions Source: https://api.livechatai.com/api-reference-v2/ai-suggestions/list get /api/v2/ai-suggestions List AI suggestions for a specific agent. AI suggestions are automatically generated improvement suggestions based on conversations where the AI response may have been incomplete, out of context, or lacking depth. # Retrieve AI Suggestion Source: https://api.livechatai.com/api-reference-v2/ai-suggestions/retrieve get /api/v2/ai-suggestions/{suggestionId} Get detailed information about a specific AI suggestion including the user message, AI response, evaluation tag, potential gap, and suggested improvement. # Get agent analytics Source: https://api.livechatai.com/api-reference-v2/analytics/agent get /api/v2/analytics/agent Get agent performance analytics including conversation counts, response times, and messages per conversation # Get AI function analytics Source: https://api.livechatai.com/api-reference-v2/analytics/ai-functions get /api/v2/analytics/ai-functions Get AI function/action call analytics including success rates and per-function breakdown # Get CSAT analytics Source: https://api.livechatai.com/api-reference-v2/analytics/csat get /api/v2/analytics/csat Get CSAT (Customer Satisfaction) analytics including average scores, total responses, individual feedback entries with pagination, and period-over-period comparison # Get main analytics Source: https://api.livechatai.com/api-reference-v2/analytics/main get /api/v2/analytics Get main analytics data for a chatbot including conversations, resolutions, responses, and daily breakdown # Get resolution analytics Source: https://api.livechatai.com/api-reference-v2/analytics/resolutions get /api/v2/analytics/resolutions Post-close judgement of whether conversations actually solved the customer's problem, broken down by verdict (RESOLVED / UNRESOLVED) and by who carried the conversation (AI / HUMAN_AGENT / NONE). Conversations are bucketed by their **creation date**, not their close or analysis date, matching the other analytics endpoints. Only conversations that are currently closed and have been analysed are counted; a conversation that was reopened leaves the metric until it is closed again. Requires the resolution analysis add-on. Without it every count is 0. # Get sentiment analytics Source: https://api.livechatai.com/api-reference-v2/analytics/sentiments get /api/v2/analytics/sentiments Get sentiment analysis breakdown with daily data for positive, negative, neutral, and unspecified sentiments # Get topics analytics Source: https://api.livechatai.com/api-reference-v2/analytics/topics get /api/v2/analytics/topics Get conversation topics analysis with daily breakdown showing top discussion topics # Create or update a contact Source: https://api.livechatai.com/api-reference-v2/contacts/create post /api/v2/contacts Create or update a contact for a specific agent. This endpoint allows you to identify users and associate them with chat sessions, enabling personalized experiences and contact tracking. # List contacts Source: https://api.livechatai.com/api-reference-v2/contacts/list get /api/v2/contacts List all contacts for a specific agent. This endpoint supports pagination and filtering to help manage customer interactions efficiently. # List conversations for a contact Source: https://api.livechatai.com/api-reference-v2/contacts/list-conversations get /api/v2/contacts/{contactId}/conversations List conversations for a specific contact with pagination and filtering options. Mirrors the response shape of `GET /api/v2/conversations`, scoped to a single contact. # Retrieve a contact Source: https://api.livechatai.com/api-reference-v2/contacts/retrieve get /api/v2/contacts/{contactId} Retrieve detailed information about a specific contact, including their attributes and conversation history. # Upload an attachment Source: https://api.livechatai.com/api-reference-v2/conversations/attachment-presign post /api/v2/conversations/{conversationId}/attachments/presign Returns a short-lived presigned S3 POST (expires in 5 minutes / 300 seconds). Submit a multipart/form-data request to `uploadUrl` with every `fields` entry followed by the `file` field last; the `Content-Type` you send must match the one in `fields`, and S3 enforces the size limit server-side. Then reference the returned `fileUrl`/metadata in the `attachments` array of a reply or conversation message. Supported types and max sizes: images png/jpg/jpeg/webp (10 MB), documents pdf/docx/xlsx/pptx (25 MB), text txt/csv (25 MB), video mp4/3gpp/webm/mpeg (50 MB), audio mp3/wav/ogg/mpeg (50 MB). Other types — including svg, html and javascript — are rejected. ## Overview Attachments are **not** uploaded through this API directly. Instead you exchange the file's metadata for a short-lived, pre-signed Amazon S3 upload, push the file straight to S3, and then reference the returned URL when you send a message. This keeps large files off our servers and lets uploads scale. The flow has **three steps**: Call this endpoint with the file's `mimeType`, `size` and a `fileName`. You get back an `uploadUrl`, a set of `fields`, and the final `fileUrl`. The conversation's chatbot is resolved server-side from the `conversationId` — you don't pass a `chatbotId`. Send a `multipart/form-data` POST to `uploadUrl` containing every entry in `fields` **first**, then the `file` **last**. Call [Send message](/api-reference-v2/conversations/send-message) or [Reply to a conversation](/api-reference-v2/conversations/reply) with an `attachments` array that references the `fileUrl` and metadata. The conversation must already exist. The `conversationId` is validated against your workspace, so you can only upload into your own conversations. ## Step 1 — Request a pre-signed upload ```bash theme={null} curl -X POST \ 'https://api.popupsmart.com/api/v2/conversations/{conversationId}/attachments/presign' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "fileName": "report.pdf", "mimeType": "application/pdf", "size": 248213 }' ``` Response: ```json theme={null} { "status": "success", "data": { "uploadUrl": "https://cdn.example.com", "fields": { "key": "clx123.../chat/chat_123/messages/9f8e7d.pdf", "Content-Type": "application/pdf", "Content-Disposition": "attachment", "acl": "public-read", "policy": "eyJ...", "x-amz-signature": "a1b2c3..." }, "fileUrl": "https://cdn.example.com/clx123.../chat/chat_123/messages/9f8e7d.pdf", "name": "report.pdf", "mimeType": "application/pdf", "size": 248213, "category": "doc" } } ``` The pre-signed upload expires in **5 minutes (300 seconds)**. Upload the file promptly, or request a new one. ## Step 2 — Upload the file to S3 POST the file to `uploadUrl` as `multipart/form-data`. **Append every key from `fields` in order, then append the `file` field last** — S3 ignores any field that comes after `file`. ```bash theme={null} curl -X POST 'https://cdn.example.com' \ -F 'key=clx123.../chat/chat_123/messages/9f8e7d.pdf' \ -F 'Content-Type=application/pdf' \ -F 'Content-Disposition=attachment' \ -F 'acl=public-read' \ -F 'policy=eyJ...' \ -F 'x-amz-signature=a1b2c3...' \ -F 'file=@report.pdf' ``` A successful upload returns `204 No Content`. The `Content-Type` you send **must match** the `Content-Type` in `fields`, and the file size must be within the [per-category limit](#allowed-types-and-size-limits) — S3 rejects the upload otherwise, even if step 1 succeeded. In a browser, build a `FormData` object: append each `fields` entry with `formData.append(key, value)`, then `formData.append('file', file)` last, and `fetch(uploadUrl, { method: 'POST', body: formData })`. ## Step 3 — Send the message with the attachment Reference the `fileUrl` and metadata in the `attachments` array. The message type is resolved automatically (a single image → `IMAGE`, anything else → `FILE`). ```bash theme={null} curl -X POST \ 'https://api.popupsmart.com/api/v2/conversations/{conversationId}/reply' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "userId": "user_1234567890", "message": "Here is the report you asked for.", "attachments": [ { "url": "https://cdn.example.com/clx123.../chat/chat_123/messages/9f8e7d.pdf", "name": "report.pdf", "mimeType": "application/pdf", "size": 248213 } ] }' ``` Every attachment is re-validated server-side before it is stored; invalid entries are dropped. The stored attachment is returned with an `id` and a resolved `category` (`image` | `video` | `audio` | `doc` | `text`). ## Allowed types and size limits Only the MIME types below are accepted. Anything else — including `image/svg+xml`, `text/html`, and JavaScript types — is rejected for security. | Category | MIME types | Max size | | -------- | ------------------------------------------------------------------ | -------- | | `image` | `image/png`, `image/jpg`, `image/jpeg`, `image/webp` | 10 MB | | `doc` | `application/pdf`, `.docx`, `.xlsx`, `.pptx` (Office Open XML) | 25 MB | | `text` | `text/plain`, `text/csv` | 25 MB | | `video` | `video/mp4`, `video/3gpp`, `video/webm`, `video/mpeg` | 50 MB | | `audio` | `audio/mp3`, `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/ogg` | 50 MB | ## Errors | Status | When | | ------ | --------------------------------------------------------------------------------------------------------- | | `400` | Missing `fileName`/`mimeType`/`size`, an unsupported MIME type, or a file larger than the category limit. | | `401` | Missing or invalid API key. | | `404` | The conversation does not exist or does not belong to your workspace. | # Create a conversation Source: https://api.livechatai.com/api-reference-v2/conversations/create post /api/v2/conversations/create Create a new conversation without sending a message. This is a lightweight endpoint that only creates a contact and chat record, skipping AI processing, similarity search, and smart tag processing. Ideal for integrations that need a conversation ID quickly. # End a conversation Source: https://api.livechatai.com/api-reference-v2/conversations/end post /api/v2/conversations/{conversationId}/end End a conversation. This endpoint allows agents to mark a conversation as resolved. If userId is not provided, the system will use the agent assigned to the chat, or if no agent is assigned, it will use the workspace owner associated with the API token. # List conversations Source: https://api.livechatai.com/api-reference-v2/conversations/list get /api/v2/conversations List conversations for an agent, with pagination and filtering options. This endpoint supports various filters including date range, agent assignment, and conversation status. # List conversation views Source: https://api.livechatai.com/api-reference-v2/conversations/list-views get /api/v2/conversations/views List all saved views for filtering conversations. Views are filter configurations created from the dashboard that can be used to filter conversations via the viewId parameter in the list conversations endpoint. # Reply to a conversation Source: https://api.livechatai.com/api-reference-v2/conversations/reply post /api/v2/conversations/{conversationId}/reply Send a reply message as an agent to a specific conversation. This endpoint allows agents to respond to customer messages and automatically updates conversation status. # Retrieve a conversation Source: https://api.livechatai.com/api-reference-v2/conversations/retrieve get /api/v2/conversations/{conversationId} Retrieve details of a specific conversation including messages # Send a message Source: https://api.livechatai.com/api-reference-v2/conversations/send-message post /api/v2/conversations Send a message to start or continue a conversation with an agent # Send an "agent is typing" indicator Source: https://api.livechatai.com/api-reference-v2/conversations/typing post /api/v2/conversations/{conversationId}/typing Broadcast an ephemeral "agent is typing" indicator to the live chat widget for a specific conversation. Use this to show a typing animation in the messenger while your agent composes a reply in your own interface. The signal is not persisted: send it with isTyping=true while the agent is typing and isTyping=false when they stop or send a message. To avoid noise, send true at most once every ~5 seconds. The indicator is hidden automatically after 10 seconds without a fresh signal, so a missed false is self-healing. userId is optional — omit it to attribute the typing to the workspace owner. # Create a file data source Source: https://api.livechatai.com/api-reference-v2/data-sources/create-file post /api/v2/data-sources/file Add file content (PDF, DOCX, or Image) as a data source to train your agent. The content should be pre-extracted from the file. # Create a Q&A data source Source: https://api.livechatai.com/api-reference-v2/data-sources/create-qa post /api/v2/data-sources/qa Add a question and answer pair to train your agent. Q&A data sources are perfect for handling specific, frequently asked questions. # Create a text data source Source: https://api.livechatai.com/api-reference-v2/data-sources/create-text post /api/v2/data-sources/text Add a text-based data source to train your agent. Text data sources are useful for adding custom content, documentation, or knowledge base articles. # Create a URL data source Source: https://api.livechatai.com/api-reference-v2/data-sources/create-url post /api/v2/data-sources/url Add a website URL as a data source to train your agent. The system will crawl and extract content from the provided URL. # Delete data sources Source: https://api.livechatai.com/api-reference-v2/data-sources/delete delete /api/v2/data-sources Delete one or more data sources from an agent. This endpoint supports both single and bulk deletion operations. # List data sources Source: https://api.livechatai.com/api-reference-v2/data-sources/list get /api/v2/data-sources List all data sources for an agent. This endpoint provides a unified view of all training data sources including websites, text, Q&A pairs, and uploaded files. It supports pagination, filtering, and search to help manage large datasets efficiently. # Update a Q&A data source Source: https://api.livechatai.com/api-reference-v2/data-sources/update-qa put /api/v2/data-sources/qa Update an existing Q&A data source. # Introduction Source: https://api.livechatai.com/api-reference-v2/introduction Welcome to LiveChatAI API v2 - Build powerful AI-powered customer support experiences # Introduction This is documentation for **version 2.0** of the LiveChatAI REST API. * All changes to version 2.0 can be viewed in the [Changelog](/api-reference-v2/changelog). * To change your version, see our [versioning page](/api-reference-v2/versioning). This version of our API reference is auto-generated from an OpenAPI specification. It is also interactive, which means you can now make calls to the LiveChatAI API directly from the docs, using Node, Ruby, PHP, Java, Python, and other languages. If you'd like to chat with other LiveChatAI customers who are integrating with our API, you can ask a question in the [LiveChatAI Community](https://discord.com/invite/X2WwkMVKt5). For more information about LiveChatAI products, you can visit our [product documentation](https://help.livechatai.com/). ## API Overview The LiveChatAI API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ### Base URL All API requests should be made to: ``` https://app.livechatai.com/api/v2/ ``` ### Authentication The LiveChatAI API uses API keys to authenticate requests. You can view and manage your API keys in the [LiveChatAI Dashboard](https://app.livechatai.com/dashboard/profile/personal). Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so on. Authentication to the API is performed via HTTP Bearer Authentication. Provide your API key as the bearer token value: ```bash theme={null} curl https://app.livechatai.com/api/v2/chatbots \ -H "Authorization: Bearer YOUR_API_KEY" ``` All API requests must be made over HTTPS. Calls made over plain HTTP will fail. ### Response Format All responses are returned in JSON format with the following structure: ```json theme={null} { "status": "success", "data": { // Response data } } ``` Error responses follow this format: ```json theme={null} { "status": "error", "message": "Error description", "code": "error_code" } ``` ### HTTP Status Codes LiveChatAI uses conventional HTTP response codes to indicate the success or failure of an API request: * `200` - OK: Everything worked as expected * `400` - Bad Request: The request was unacceptable * `401` - Unauthorized: No valid API key provided * `403` - Forbidden: The API key doesn't have the required permissions * `404` - Not Found: The requested resource doesn't exist * `429` - Too Many Requests: Too many requests hit the API too quickly * `500` - Server Error: Something went wrong on our end ## API Reference * [Chatbots](/api-reference-v2/chatbots) - Create and manage AI chatbots * [Conversations](/api-reference-v2/conversations) - Handle chat conversations and messages * [Contacts](/api-reference-v2/contacts) - Manage visitor contacts and their data * [Data Sources](/api-reference-v2/data-sources) - Train your chatbot with knowledge base content * [Messages](/api-reference-v2/messages) - Send and receive messages ## Support If you need help with the API or have questions: * **Email**: [support@livechatai.com](mailto:support@livechatai.com) * **Discord**: [Join our community](https://discord.com/invite/X2WwkMVKt5) * **Documentation**: [help.livechatai.com](https://help.livechatai.com/) *** Start by creating your first chatbot: [Create a Chatbot](/api-reference-v2/chatbots/create) # Add a language Source: https://api.livechatai.com/api-reference-v2/translations/add-language post /api/v2/chatbots/{chatbotId}/translations/languages Add a language to the chatbot's supportedLanguages. Optionally seeds initial translation overrides for the new language. Fails with 409 if the language is already the default or already in supportedLanguages. # Reset a translation key Source: https://api.livechatai.com/api-reference-v2/translations/delete-key delete /api/v2/chatbots/{chatbotId}/translations/{language}/{key} Reset a single translation key to its language default. Removes the override row from the database and re-syncs the settings mirror. # Remove a language Source: https://api.livechatai.com/api-reference-v2/translations/delete-language delete /api/v2/chatbots/{chatbotId}/translations/languages/{language} Remove a language from the chatbot. Drops all translation overrides for the language, removes it from supportedLanguages, and clears it from the settings mirror. The default language cannot be removed. # Get chatbot translations Source: https://api.livechatai.com/api-reference-v2/translations/list get /api/v2/chatbots/{chatbotId}/translations Retrieve the full localization state for a chatbot, including the default language, supported languages, auto-translation flag, the static `availableKeys` catalogue listing every translation key the system recognises, and the merged translation fields (defaults + custom overrides) for every active language. # List available languages Source: https://api.livechatai.com/api-reference-v2/translations/list-languages get /api/v2/chatbots/{chatbotId}/translations/languages List all languages available for a chatbot. Returns predefined languages plus any custom languages that have translation overrides in the database. # Bulk update translations Source: https://api.livechatai.com/api-reference-v2/translations/update-bulk put /api/v2/chatbots/{chatbotId}/translations/{language} Bulk upsert translations for a single language using merge semantics — only supplied keys are touched. Values equal to the language's default are removed from the database to keep storage clean (mirrors UI behavior). # Update a translation key Source: https://api.livechatai.com/api-reference-v2/translations/update-key patch /api/v2/chatbots/{chatbotId}/translations/{language}/{key} Update a single translation key for a single language. If the supplied value matches the language's default, the override is removed from the database (mirrors UI behavior). # Update localization settings Source: https://api.livechatai.com/api-reference-v2/translations/update-settings patch /api/v2/chatbots/{chatbotId}/translations/settings Update the chatbot's localization settings — default language, the supported-languages list, and the auto-translation flag. Any subset of fields may be provided; only supplied keys are touched. # Crawl websites to discover internal links Source: https://api.livechatai.com/api-reference/endpoint/chatbot/crawl-websites-to-discover-internal-links post /api/aibot/scrape **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Crawl websites to discover internal links # Create a new chatbot Source: https://api.livechatai.com/api-reference/endpoint/chatbot/create-a-new-chatbot post /api/aibot/create **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Create a new chatbot # Delete chatbot Source: https://api.livechatai.com/api-reference/endpoint/chatbot/delete-chatbot delete /api/aibot/delete **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Delete chatbot # Get chat detail (public) Source: https://api.livechatai.com/api-reference/endpoint/chatbot/get-chat-detail-public get /api/aibot/chat/detail **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Get chat detail # Get chatbot detail (public) Source: https://api.livechatai.com/api-reference/endpoint/chatbot/get-chatbot-detail-public get /api/aibot/detail **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Get chatbot detail # Get contact agents (public) Source: https://api.livechatai.com/api-reference/endpoint/chatbot/get-contact-agents-public get /api/aibot/contact/agent **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Get contact agents # Get user's chatbot Source: https://api.livechatai.com/api-reference/endpoint/chatbot/get-users-chatbot get /api/aibot/list **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Get user's chatbot # Message a Chatbot (public) Source: https://api.livechatai.com/api-reference/endpoint/chatbot/message-a-chatbot-public post /api/aibot/reply **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Message a Chatbot # Add pdf data-source to chatbot Source: https://api.livechatai.com/api-reference/endpoint/data-source/add-pdf-data-source-to-chatbot post /api/aibot/data-source/pdf **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Add pdf data-source to chatbot # Add Q&A data-source to chatbot Source: https://api.livechatai.com/api-reference/endpoint/data-source/add-q&a-data-source-to-chatbot post /api/aibot/data-source/qa **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Add Q&A data-source to chatbot # Add text data-source to chatbot Source: https://api.livechatai.com/api-reference/endpoint/data-source/add-text-data-source-to-chatbot post /api/aibot/data-source/text **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Add text data-source to chatbot # Add url data-source to chatbot Source: https://api.livechatai.com/api-reference/endpoint/data-source/add-url-data-source-to-chatbot post /api/aibot/data-source/url **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Add url data-source to chatbot # Delete data-source from chatbot Source: https://api.livechatai.com/api-reference/endpoint/data-source/delete-data-source-from-chatbot post /api/aibot/data-source/delete **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Delete data-source from chatbot # Get chatbot data-source items Source: https://api.livechatai.com/api-reference/endpoint/data-source/get-chatbot-data-source-items get /api/aibot/data-source/items **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Get chatbot data-source items # Update Q&A data-source Source: https://api.livechatai.com/api-reference/endpoint/data-source/update-q&a-data-source put /api/aibot/data-source/qa **DEPRECATED:** This endpoint will be deprecated on August 1st, 2025. Please use the v1 API endpoints instead. Update Q&A data-source # Introduction to LiveChatAI - DEPRECATED August 1, 2025 Source: https://api.livechatai.com/api-reference/introduction Enhance your website with intelligent conversational AI - This API version is deprecated **DEPRECATED API VERSION** - This API version is deprecated as of August 1st, 2025. Please migrate to the [new v1 API](/api-reference-v1/introduction) for improved performance, security, and features. The legacy endpoints will be discontinued on December 1st, 2025. [**Migrate to v1 API →**](/api-reference-v1/introduction) ## Welcome to LiveChatAI LiveChatAI is a powerful conversational AI platform designed to elevate your website's customer engagement. Our intelligent chatbot seamlessly integrates with your site to provide 24/7 support, answer queries, and guide visitors through your products or services. ### Key Features * Natural language processing for human-like conversations * Easy integration with popular website platforms * Customizable chatbot personality and knowledge base * Analytics dashboard to track engagement metrics * Seamless handoff to human agents when needed Migrate to v1 API for continued service and enhanced features ## How It Works LiveChatAI uses advanced machine learning algorithms to understand user intent and provide relevant responses. The AI is continuously trained on your specific business data to improve accuracy over time. ```json theme={null} { "input": "User query", "processing": "Natural language understanding", "output": "Intelligent, contextual response" } ``` **Important:** This documentation is for the legacy API. For new implementations, please use the [v1 API documentation](/api-reference-v1/introduction).