> ## Documentation Index > Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run conversation action > Run a bulk conversation action. Required scope: `conversations:write`. On success, `data` contains: `action`, `conversations`. ## OpenAPI ````yaml https://sitegpt.ai/api/v2/openapi.json post /api/v2/chatbots/{chatbotId}/conversations/bulk openapi: 3.1.0 info: title: SiteGPT Agent API version: 2.0.0 description: >- Agent-facing API for managing SiteGPT chatbots, dashboard summaries, appearance media, knowledge, settings, conversations, leads, members, account profiles, usage, billing reads, and API tokens. servers: - url: https://sitegpt.ai security: - bearerAuth: [] tags: - name: Discovery - name: Onboarding - name: Account - name: Billing - name: Tokens - name: Chatbots - name: Knowledge - name: Knowledge Sync Jobs - name: Knowledge Sources - name: Custom Responses - name: Personas - name: Instructions - name: Settings - name: Conversation Starters - name: Conversation Followups - name: Members - name: Leads - name: Conversations - name: Messages - name: Tags paths: /api/v2/chatbots/{chatbotId}/conversations/bulk: post: tags: - Conversations summary: Run conversation action description: |- Run a bulk conversation action. Required scope: `conversations:write`. On success, `data` contains: `action`, `conversations`. operationId: runConversationAction parameters: - name: chatbotId in: path required: true description: Chatbot ID. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - action - threadIds additionalProperties: false properties: action: type: string enum: - delete - mark-read - mark-unread - resolve - star - unresolve - unstar threadIds: type: array minItems: 1 items: type: string confirm: type: boolean description: Required true for bulk delete. example: action: mark-read threadIds: - thread-id responses: '200': description: Successful SiteGPT API v2 response. content: application/json: schema: type: object required: - ok - data - meta properties: ok: type: boolean const: true data: type: object additionalProperties: true properties: action: type: string conversations: type: array items: $ref: '#/components/schemas/Conversation' meta: $ref: '#/components/schemas/AgentResponseMeta' additionalProperties: false example: ok: true data: action: star conversations: - id: conversation-id name: Example conversation createdAt: '2026-05-13T00:00:00.000Z' meta: requestId: request-id '400': $ref: '#/components/responses/AgentError' '401': $ref: '#/components/responses/AgentError' '403': $ref: '#/components/responses/AgentError' '404': $ref: '#/components/responses/AgentError' '405': $ref: '#/components/responses/AgentError' security: - bearerAuth: - conversations:write components: schemas: Conversation: type: object description: A conversation thread between a visitor and the chatbot. additionalProperties: true properties: threadId: type: string chatbotId: type: string mode: type: string enum: - AI - AGENT description: AI answers automatically; AGENT means human takeover. startedAt: type: string format: date-time updatedAt: type: string format: date-time endedAt: type: - string - 'null' format: date-time escalated: type: boolean important: type: boolean resolved: type: boolean title: type: - string - 'null' tagIds: type: array items: type: string sessionId: type: - string - 'null' ipAddress: type: - string - 'null' pageUrl: type: - string - 'null' webhookUrl: type: - string - 'null' webhookTokenConfigured: type: boolean chatUserId: type: - string - 'null' chatUser: anyOf: - $ref: '#/components/schemas/ChatUser' - type: 'null' lead: anyOf: - $ref: '#/components/schemas/Lead' - type: 'null' totalMessages: type: integer totalPositiveMessages: type: integer totalNegativeMessages: type: integer totalGpt4MessagesCount: type: integer totalMessagesRead: type: integer totalMessagesReadByUser: type: integer unreadMessages: type: integer lastMessage: anyOf: - $ref: '#/components/schemas/Message' - type: 'null' messages: type: array items: $ref: '#/components/schemas/Message' description: >- Full message list; present on single-conversation reads and bulk action results, absent from list endpoints. AgentResponseMeta: type: object required: - requestId properties: requestId: type: string warnings: type: array items: type: string nextCursor: type: - string - 'null' additionalProperties: true ChatUser: type: object description: A website visitor identified through the chat widget. additionalProperties: true properties: id: type: string name: type: string email: type: string phone: type: string verified: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time Lead: type: object description: >- A captured lead. The top-level email convenience field is present on lead endpoints; conversation payloads embed the same record without it. additionalProperties: true properties: id: type: string chatbotId: type: string chatUser: $ref: '#/components/schemas/ChatUser' name: type: string phone: type: string email: type: string description: Convenience copy of chatUser.email. tags: type: array items: type: string customData: $ref: '#/components/schemas/GenericObject' description: Custom lead-form fields collected by the widget. important: type: boolean archived: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time Message: type: object description: >- One stored conversation turn. NORMAL_MESSAGE carries the visitor question plus the AI answer; USER_MESSAGE and AGENT_MESSAGE carry one side of a human conversation; SYSTEM_MESSAGE records events such as escalation. additionalProperties: true properties: messageId: type: string messageType: type: string description: NORMAL_MESSAGE, USER_MESSAGE, AGENT_MESSAGE, or SYSTEM_MESSAGE. systemMessageType: type: - string - 'null' description: Set on SYSTEM_MESSAGE rows; null otherwise. question: anyOf: - type: object additionalProperties: true properties: text: type: string timestamp: type: string - type: 'null' answer: anyOf: - type: object additionalProperties: true properties: text: type: string timestamp: type: string - type: 'null' reaction: type: string enum: - POSITIVE - NEGATIVE - NEUTRAL gptModel: type: - string - 'null' description: Public model label for AI answers; null on human turns. sources: type: array items: type: string description: Source URLs cited by the AI answer. agentId: type: - string - 'null' agentName: type: - string - 'null' iconUrl: type: - string - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time AgentError: type: object required: - ok - error - meta properties: ok: type: boolean const: false error: type: object required: - code - message properties: code: type: string message: type: string details: {} additionalProperties: false meta: type: object required: - requestId properties: requestId: type: string additionalProperties: true additionalProperties: false GenericObject: type: object additionalProperties: true responses: AgentError: description: SiteGPT agent API error response. content: application/json: schema: $ref: '#/components/schemas/AgentError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: SiteGPT API token ````