> ## 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.

# Send message

> Send a visitor message to an existing conversation.

Required scope: `conversations:write`.

On success, `data` contains: `message`, `awayMessage`.



## OpenAPI

````yaml https://sitegpt.ai/api/v2/openapi.json post /api/v2/chatbots/{chatbotId}/conversations/{threadId}/messages
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/{threadId}/messages:
    post:
      tags:
        - Messages
      summary: Send message
      description: |-
        Send a visitor message to an existing conversation.

        Required scope: `conversations:write`.

        On success, `data` contains: `message`, `awayMessage`.
      operationId: sendConversationMessage
      parameters:
        - name: chatbotId
          in: path
          required: true
          description: Chatbot ID.
          schema:
            type: string
        - name: threadId
          in: path
          required: true
          description: Conversation thread ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              additionalProperties: false
              properties:
                message:
                  type: string
                  minLength: 1
                pageUrl:
                  type:
                    - string
                    - 'null'
                  format: uri
            example:
              message: I have one more question.
      responses:
        '201':
          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:
                      message:
                        $ref: '#/components/schemas/Message'
                      awayMessage:
                        anyOf:
                          - $ref: '#/components/schemas/Message'
                          - type: 'null'
                        description: >-
                          The away message this message got: set when the
                          conversation is held by the team, outside the working
                          hours of the chatbot, with an away message. Show its
                          answer text to the visitor. Each conversation gets it
                          one time, so later messages return null.
                  meta:
                    $ref: '#/components/schemas/AgentResponseMeta'
                additionalProperties: false
              example:
                ok: true
                data:
                  message:
                    id: message-id
                    name: Example message
                    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'
        '409':
          $ref: '#/components/responses/AgentError'
        '429':
          $ref: '#/components/responses/AgentError'
        '503':
          $ref: '#/components/responses/AgentError'
      security:
        - bearerAuth:
            - conversations:write
components:
  schemas:
    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: >-
            The page URL of each knowledge passage the AI was given for this
            answer, in retrieval order (best match first). A page with several
            passages appears several times. Answers sent through this API keep
            an empty string for each passage from uploaded files or text;
            answers from the chat widget leave those out.
        agentId:
          type:
            - string
            - 'null'
        agentName:
          type:
            - string
            - 'null'
        iconUrl:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AgentResponseMeta:
      type: object
      required:
        - requestId
      properties:
        requestId:
          type: string
        warnings:
          type: array
          items:
            type: string
        nextCursor:
          type:
            - string
            - 'null'
      additionalProperties: true
    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
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.