> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Chatbot Message

> Send one user message and wait for the full reply. The session follows the chatbot's workflow on its own: forms and choices are answered from plain text, so no step IDs are needed. Send `data.text` back to the user.



## OpenAPI

````yaml post /external/chatbots/{chatbot_id}/messages
openapi: 3.1.0
info:
  title: Shieldbase External API
  description: Public API for Shieldbase AI integration
  version: 1.0.0
servers:
  - url: https://api.shieldbase.ai
    description: Production
  - url: http://localhost:8000
    description: Development
security:
  - ClientID: []
    APIKey: []
    Secret: []
paths:
  /external/chatbots/{chatbot_id}/messages:
    post:
      tags:
        - Chatbots
      summary: Send Chatbot Message
      description: >-
        Send one user message and wait for the full reply. The session follows
        the chatbot's workflow on its own: forms and choices are answered from
        plain text, so no step IDs are needed. Send `data.text` back to the
        user.
      parameters:
        - $ref: '#/components/parameters/TenantID'
        - name: chatbot_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatbotMessageRequest'
      responses:
        '200':
          description: Turn result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ChatbotTurnResult'
        '400':
          description: Empty message
        '402':
          description: Credit limit reached
        '403':
          description: Invalid API credentials
        '404':
          description: Chatbot not found or not accessible
        '409':
          description: A previous message in this session is still being processed
        '503':
          description: AI service temporarily unavailable
components:
  parameters:
    TenantID:
      name: X-Tenant-ID
      in: header
      required: false
      description: >-
        Optional tenant selector for multitenant accounts. The API key owner
        must have access to the selected tenant.
      schema:
        type: string
  schemas:
    ChatbotMessageRequest:
      type: object
      properties:
        message:
          type: string
          description: >-
            What the user typed. Form and choice answers are understood from
            plain text.
        session_key:
          type: string
          maxLength: 200
          description: >-
            Your stable conversation key, e.g. `telegram:12345` or `wa:+628123`.
            Reuse it to continue a conversation. Omit to start a new one; the
            generated key is returned.
        file_urls:
          type: array
          items:
            type: string
          description: URLs of uploaded files (see `/external/upload`)
        form_values:
          type: object
          additionalProperties: true
          description: >-
            Optional structured form answers keyed by
            `next_step.form_fields[].field`
        reset:
          type: boolean
          default: false
          description: Forget the workflow position and partial answers before this message
        executor_timezone:
          type: integer
          description: Client UTC offset in minutes, e.g. 420 for UTC+7
        timeout_seconds:
          type: integer
          default: 300
          minimum: 1
          maximum: 1800
          description: Max wait for the reply. The turn keeps running after a timeout.
      example:
        session_key: wa:+628123456789
        message: Hi, I'm Budi
    ChatbotTurnResult:
      type: object
      properties:
        chatbot_id:
          type: string
        session_key:
          type: string
        session_id:
          type: string
        status:
          type: string
          enum:
            - awaiting_input
            - completed
            - processing
            - human_agent
            - failed
          description: >-
            `processing` means the reply was not ready within `timeout_seconds`;
            the turn keeps running and can be read later from the transcript
            endpoint.
        mode:
          type: string
          enum:
            - ai
            - cs
        text:
          type: string
          description: >-
            All replies plus the next question in one string. Send it to the
            user as-is.
        prompt:
          type:
            - string
            - 'null'
          description: >-
            The pending form question or numbered choices, when not already part
            of `messages`.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatbotReplyMessage'
        next_step:
          $ref: '#/components/schemas/ChatbotStep'
        error:
          type:
            - object
            - 'null'
          properties:
            status_code:
              type: integer
            code:
              type: string
            message:
              type: string
    ChatbotReplyMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - assistant
            - cs
            - system
        message:
          type: string
        step_id:
          type:
            - string
            - 'null'
        step_type:
          type:
            - string
            - 'null'
        file_url:
          type: string
          description: Present when the step produced a file
    ChatbotStep:
      type:
        - object
        - 'null'
      description: >-
        The workflow step waiting for the next message. Informational only: you
        never need to send its ID back.
      properties:
        id:
          type: string
        type:
          type: string
        description:
          type: string
        expects:
          type: string
          enum:
            - message
            - form
            - choice
            - file
        form_fields:
          type: array
          description: Present when `expects` is `form`
          items:
            type: object
            properties:
              field:
                type: string
              description:
                type: string
              type:
                type: string
              required:
                type: boolean
              options: {}
        prompt:
          type: string
          description: Question for a choice step
        options:
          type: array
          items:
            type: string
          description: Present when `expects` is `choice`
  securitySchemes:
    ClientID:
      type: apiKey
      in: header
      name: X-Client-ID
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
    Secret:
      type: apiKey
      in: header
      name: X-Secret

````

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