api-schema.yml

openapi: 3.0.3
info:
  title: Dimagi Chatbots
  version: '1'
  description: Experiments with AI, GPT and LLMs
paths:
  /api/chat/{session_id}/{task_id}/poll/:
    get:
      operationId: chat_poll_task_response
      summary: Poll for task updates
      parameters:
      - in: path
        name: session_id
        schema:
          type: string
        description: Session ID
        required: true
      - in: path
        name: task_id
        schema:
          type: string
        description: Check on the status of a specific task
        required: true
      tags:
      - Chat
      security:
      - cookieAuth: []
      - embedKeyAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatTaskPoll'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatTaskPollUserError'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatTaskPollError'
          description: ''
  /api/chat/{session_id}/message/:
    post:
      operationId: chat_send_message
      description: Send a message to a chat session
      summary: Send a message to a chat session
      parameters:
      - in: path
        name: session_id
        schema:
          type: string
        description: Session ID
        required: true
      tags:
      - Chat
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatSendMessageRequestWithAttachments'
            examples:
              SendMessage:
                value:
                  message: Hello, how can you help me?
                summary: Send a message to the bot
              SendMessageWithAttachments:
                value:
                  message: Please review these documents
                  attachment_ids:
                  - 123
                  - 124
                summary: Send a message with file attachments
        required: true
      security:
      - cookieAuth: []
      - embedKeyAuth: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSendMessageResponse'
          description: ''
  /api/chat/{session_id}/poll/:
    get:
      operationId: chat_poll_response
      description: Poll for new messages in a chat session
      summary: Poll for new messages in a chat session. Do not poll more than once
        every 30 seconds
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
        description: 'Maximum number of messages to return (default: 50)'
      - in: path
        name: session_id
        schema:
          type: string
        description: Session ID
        required: true
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: Only return messages after this timestamp
      tags:
      - Chat
      security:
      - cookieAuth: []
      - embedKeyAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatPollResponse'
          description: ''
  /api/chat/{session_id}/upload/:
    post:
      operationId: chat_upload_file
      summary: Upload files for a chat message
      parameters:
      - in: path
        name: session_id
        schema:
          type: string
        description: Session ID
        required: true
      tags:
      - Chat
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ChatUploadFileRequest'
        required: true
      security:
      - cookieAuth: []
      - embedKeyAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatUploadFileResponse'
          description: ''
  /api/chat/start/:
    post:
      operationId: chat_start_session
      description: Start a new chat session - supports both authenticated users and
        embedded widgets
      summary: Start a new chat session for a widget
      tags:
      - Chat
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatStartSessionRequest'
            examples:
              StartSessionPublishedVersion:
                value:
                  chatbot_id: 123e4567-e89b-12d3-a456-426614174000
                  session_data:
                    source: widget
                    page_url: https://example.com
                  participant_remote_id: abc
                  participant_name: participant_name
                summary: Start session with published version
              StartSessionSpecificVersion:
                value:
                  chatbot_id: 123e4567-e89b-12d3-a456-426614174000
                  version_number: 2
                  participant_remote_id: abc
                  participant_name: participant_name
                summary: Start session with specific version (requires auth)
        required: true
      security:
      - cookieAuth: []
      - embedKeyAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatStartSessionResponse'
              examples:
                StartSessionPublishedVersionResponse:
                  value:
                    session_id: 123e4567-e89b-12d3-a456-426614174000
                    chatbot:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      name: Example Bot
                      version_number: 0
                      versions: []
                      url: https://example.com/api/experiments/123e4567-e89b-12d3-a456-426614174000/
                    participant:
                      identifier: abc
                      remote_id: abc
                  summary: Session started with published version
                StartSessionSpecificVersionResponse:
                  value:
                    session_id: 123e4567-e89b-12d3-a456-426614174000
                    chatbot:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      name: Example Bot
                      version_number: 2
                      versions: []
                      url: https://example.com/api/experiments/123e4567-e89b-12d3-a456-426614174000/
                    participant:
                      identifier: abc
                      remote_id: abc
                  summary: Session started with specific version
          description: ''
  /api/experiments/:
    get:
      operationId: experiment_list
      summary: List Chatbots
      parameters:
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      tags:
      - Experiments
      security:
      - OAuth2:
        - chatbots:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExperimentList'
          description: ''
  /api/experiments/{id}/:
    get:
      operationId: experiment_retrieve
      summary: Retrieve Chatbot
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - Experiments
      security:
      - OAuth2:
        - chatbots:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
          description: ''
  /api/files/{id}/content:
    get:
      operationId: file_content
      summary: Download File Content
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Files
      security:
      - OAuth2:
        - files:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: ''
  /api/openai/{experiment_id}/chat/completions:
    post:
      operationId: openai_chat_completions
      description: |2

        Use OpenAI's client to send messages to the experiment and get responses. This will
        create a new session in the experiment with all the provided messages
        and return the response from the experiment.

        The last message must be a 'user' message.

        Example (Python):

        ```python
        experiment_id = "your experiment ID"

        client = OpenAI(
            api_key="your API key",
            base_url=f"https://chatbots.dimagi.com/api/openai/{experiment_id}",
        )

        completion = client.chat.completions.create(
            model="anything",
            messages=[
                {"role": "assistant", "content": "How can I help you today?"},
                {"role": "user", "content": "I need help with something."},
            ],
        )

        reply = completion.choices[0].message
        ```
      summary: Chat Completions API for Experiments
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - OpenAI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
        required: true
      security:
      - OAuth2:
        - chatbots:interact
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
          description: ''
  /api/openai/{experiment_id}/v{version}/chat/completions:
    post:
      operationId: openai_chat_completions_versioned
      description: |2

        Use OpenAI's client to send messages to the experiment and get responses. This will
        create a new session in the experiment with all the provided messages
        and return the response from the experiment.

        The last message must be a 'user' message.

        Example (Python):

        ```python
        experiment_id = "your experiment ID"

        client = OpenAI(
            api_key="your API key",
            base_url=f"https://chatbots.dimagi.com/api/openai/{experiment_id}/v{version}",
        )

        completion = client.chat.completions.create(
            model="anything",
            messages=[
                {"role": "assistant", "content": "How can I help you today?"},
                {"role": "user", "content": "I need help with something."},
            ],
        )

        reply = completion.choices[0].message
        ```
      summary: Versioned Chat Completions API for Experiments
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      - in: path
        name: version
        schema:
          type: integer
        required: true
      - in: query
        name: version
        schema:
          type: string
        description: Version of experiment
      tags:
      - OpenAI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
        required: true
      security:
      - OAuth2:
        - chatbots:interact
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
          description: ''
  /api/participants:
    get:
      operationId: list_participants
      description: 'GET: list participants for the team. POST: update/create participant
        data.'
      summary: List Participants
      parameters:
      - in: query
        name: chatbot
        schema:
          type: string
          format: uuid
        description: Filter by chatbot public id; returns participants that have data
          for the chatbot.
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: identifier
        schema:
          type: string
        description: Filter by participant identifier
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: platform
        schema:
          type: string
        description: Filter by platform (e.g. api, telegram, whatsapp)
      tags:
      - Participants
      security:
      - OAuth2:
        - participants:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedParticipantDetailList'
              examples:
                ListParticipants:
                  value:
                    next: http://api.example.org/accounts/?cursor=cD00ODY%3D"
                    previous: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
                    results:
                    - id: e172ff63-2469-419f-a828-783fc9291bc7
                      identifier: part1
                      name: John
                      platform: api
                      remote_id: ''
                      data:
                      - chatbot: Support Bot
                        chatbot_id: 815e7ef4-3479-4689-ae6c-29ca1a04ca8e
                        data:
                          name: John
                          timezone: Africa/Johannesburg
                  summary: A participant with their chatbot data
          description: ''
    post:
      operationId: update_participant_data
      description: 'GET: list participants for the team. POST: update/create participant
        data.'
      summary: Update Participant Data
      tags:
      - Participants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantDataUpdateRequest'
            examples:
              CreateParticipantData:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    data:
                      name: John
                  - experiment: exp2
                    data:
                      name: Doe
                    schedules:
                    - id: sched1
                      name: Schedule 1
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt 1
                summary: Create participant data for multiple experiments
              UpdateParticipantSchedules:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    schedules:
                    - id: sched1
                      name: Schedule 1 updated
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt updated
                    - id: sched2
                      delete: true
                summary: Update and delete participant schedules
        required: true
      security:
      - OAuth2:
        - participants:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          description: No response body
  /api/participants/:
    get:
      operationId: list_participants_2
      description: 'GET: list participants for the team. POST: update/create participant
        data.'
      summary: List Participants
      parameters:
      - in: query
        name: chatbot
        schema:
          type: string
          format: uuid
        description: Filter by chatbot public id; returns participants that have data
          for the chatbot.
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: identifier
        schema:
          type: string
        description: Filter by participant identifier
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: platform
        schema:
          type: string
        description: Filter by platform (e.g. api, telegram, whatsapp)
      tags:
      - Participants
      security:
      - OAuth2:
        - participants:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedParticipantDetailList'
              examples:
                ListParticipants:
                  value:
                    next: http://api.example.org/accounts/?cursor=cD00ODY%3D"
                    previous: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
                    results:
                    - id: e172ff63-2469-419f-a828-783fc9291bc7
                      identifier: part1
                      name: John
                      platform: api
                      remote_id: ''
                      data:
                      - chatbot: Support Bot
                        chatbot_id: 815e7ef4-3479-4689-ae6c-29ca1a04ca8e
                        data:
                          name: John
                          timezone: Africa/Johannesburg
                  summary: A participant with their chatbot data
          description: ''
    post:
      operationId: update_participant_data_2
      description: 'GET: list participants for the team. POST: update/create participant
        data.'
      summary: Update Participant Data
      tags:
      - Participants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantDataUpdateRequest'
            examples:
              CreateParticipantData:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    data:
                      name: John
                  - experiment: exp2
                    data:
                      name: Doe
                    schedules:
                    - id: sched1
                      name: Schedule 1
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt 1
                summary: Create participant data for multiple experiments
              UpdateParticipantSchedules:
                value:
                  identifier: part1
                  platform: api
                  data:
                  - experiment: exp1
                    schedules:
                    - id: sched1
                      name: Schedule 1 updated
                      date: '2022-01-01T00:00:00Z'
                      prompt: Prompt updated
                    - id: sched2
                      delete: true
                summary: Update and delete participant schedules
        required: true
      security:
      - OAuth2:
        - participants:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          description: No response body
  /api/sessions/:
    get:
      operationId: session_list
      summary: List Chatbot Sessions
      parameters:
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: experiment
        schema:
          type: string
        description: Experiment ID to filter sessions by
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: tags
        schema:
          type: string
        description: A list of session tags (comma separated) to filter the results
          by
      - in: query
        name: versions
        schema:
          type: string
        description: Experiment versions (comma separated) to filter sessions by
      tags:
      - Experiment Sessions
      security:
      - OAuth2:
        - sessions:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExperimentSessionList'
          description: ''
    post:
      operationId: session_create
      summary: Create Chatbot Session
      tags:
      - Experiment Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperimentSessionCreate'
        required: true
      security:
      - OAuth2:
        - sessions:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentSession'
          description: ''
  /api/sessions/{id}/:
    get:
      operationId: session_retrieve
      description: |2

        Retrieve the details of an session. This includes the messages exchanged during the session ordered
        by the creation date.
      summary: Retrieve Chatbot Session
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      security:
      - OAuth2:
        - sessions:read
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentSessionWithMessages'
          description: ''
  /api/sessions/{id}/end_experiment_session/:
    post:
      operationId: session_end
      summary: End Chatbot Session
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      security:
      - OAuth2:
        - sessions:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          description: No response body
  /api/sessions/{id}/tags/:
    post:
      operationId: session_add_tags
      description: Add tags to a session. Tags are automatically created if they don't
        exist.
      summary: Add Tags to Session
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tags_request_serializer'
        required: true
      security:
      - OAuth2:
        - sessions:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tags_response_serializer'
          description: ''
    delete:
      operationId: session_remove_tags
      description: Remove tags from a session.
      summary: Remove Tags from Session
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      security:
      - OAuth2:
        - sessions:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tags_response_serializer'
          description: ''
  /api/sessions/{id}/update_state/:
    patch:
      operationId: session_update_state
      summary: Update Chatbot Session State
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: ID of the session
        required: true
      tags:
      - Experiment Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Patchedupdate_state_serializer'
      security:
      - OAuth2:
        - sessions:write
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_state_response'
          description: ''
  /api/trigger_bot:
    post:
      operationId: trigger_bot_message
      description: |-
        Trigger the bot to send a message to the user, or deliver a message directly.

        Provide either ``prompt_text`` (routes through the LLM/bot pipeline) or ``message_text``
        (sends the exact text to the participant without any LLM processing). Exactly one is required.
      summary: Trigger the bot to send a message to the user, or deliver a message
        directly
      tags:
      - Channels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerBotMessageRequest'
            examples:
              GenerateBotMessageAndSend:
                value:
                  identifier: '+15556793'
                  experiment: exp1
                  platform: whatsapp
                  prompt_text: Tell the user to do something
                  session_data:
                    key: value
                  participant_data:
                    key: value
                summary: Generates a bot message and sends it to the user (auto-creates
                  participant if needed).
              SendMessageDirectly:
                value:
                  identifier: '+15556793'
                  experiment: exp1
                  platform: whatsapp
                  message_text: Your appointment is confirmed for tomorrow at 10am.
                  session_data:
                    key: value
                  participant_data:
                    key: value
                summary: Send a pre-written message directly to the participant, bypassing
                  the bot/LLM.
              ExperimentChannelNotFound:
                value:
                  detail: Experiment cannot send messages on the connect_messaging
                    channel
                summary: Experiment cannot send messages on the specified channel
              ConsentNotGiven:
                value:
                  detail: User has not given consent
                summary: User has not given consent
        required: true
      security:
      - OAuth2:
        - chatbots:interact
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                description: Bad Request
              examples:
                ConsentNotGiven:
                  value:
                    detail: User has not given consent
                  summary: User has not given consent
          description: ''
        '404':
          content:
            application/json:
              schema:
                description: Not Found
              examples:
                ExperimentChannelNotFound:
                  value:
                    detail: Experiment cannot send messages on the connect_messaging
                      channel
                  summary: Experiment cannot send messages on the specified channel
          description: ''
  /channels/api/{experiment_id}/incoming_message:
    post:
      operationId: new_api_message
      summary: New API Message
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      tags:
      - Channels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiMessage'
        required: true
      security:
      - OAuth2:
        - chatbots:interact
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMessage'
          description: ''
  /channels/api/{experiment_id}/v{version}/incoming_message:
    post:
      operationId: new_api_message_versioned
      summary: New API Message Versioned
      parameters:
      - in: path
        name: experiment_id
        schema:
          type: string
        description: Experiment ID
        required: true
      - in: path
        name: version
        schema:
          type: integer
        required: true
      - in: query
        name: version
        schema:
          type: string
        description: Version of experiment
      tags:
      - Channels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiMessage'
        required: true
      security:
      - OAuth2:
        - chatbots:interact
      - apiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMessage'
          description: ''
components:
  schemas:
    ApiMessage:
      type: object
      properties:
        message:
          type: string
          title: User message
        session:
          type: string
          title: Optional session ID
      required:
      - message
    ApiResponseAttachment:
      type: object
      properties:
        file_name:
          type: string
        link:
          type: string
      required:
      - file_name
      - link
    ApiResponseMessage:
      type: object
      properties:
        response:
          type: string
          title: AI response
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ApiResponseAttachment'
          title: List of file URLs
      required:
      - attachments
      - response
    ChatCompletionResponseChoices:
      type: object
      properties:
        finish_reason:
          type: string
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatCompletionResponseMessage'
      required:
      - finish_reason
      - index
      - message
    ChatCompletionResponseMessage:
      type: object
      properties:
        role:
          $ref: '#/components/schemas/ChatCompletionResponseMessageRoleEnum'
        content:
          type: string
      required:
      - content
      - role
    ChatCompletionResponseMessageRoleEnum:
      enum:
      - assistant
      type: string
      description: '* `assistant` - assistant'
    ChatPollResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          title: New messages since last poll
        has_more:
          type: boolean
          title: Whether there are more messages to fetch
        session_status:
          allOf:
          - $ref: '#/components/schemas/SessionStatusEnum'
          title: Current session status
      required:
      - has_more
      - messages
      - session_status
    ChatSendMessageRequestWithAttachments:
      type: object
      properties:
        message:
          type: string
          title: Message content
        context:
          type: object
          additionalProperties: {}
          description: Additional context data to include with the message such as
            details about the page the user is on or the action they are trying to
            perform. This is stored in the session state under the `remote_context`
            key.
        attachment_ids:
          type: array
          items:
            type: integer
          description: List of file IDs from prior upload
        version_number:
          type: integer
          nullable: true
          description: Optional version number of the chatbot to use. Requires authentication.
      required:
      - message
    ChatSendMessageResponse:
      type: object
      properties:
        task_id:
          type: string
          description: The ID of the task that is processing the message
        status:
          allOf:
          - $ref: '#/components/schemas/ChatSendMessageResponseStatusEnum'
          title: Processing status
        error:
          type: string
          title: Error message
      required:
      - status
      - task_id
    ChatSendMessageResponseStatusEnum:
      enum:
      - processing
      - completed
      - error
      type: string
      description: |-
        * `processing` - Processing
        * `completed` - Completed
        * `error` - Error
    ChatStartSessionRequest:
      type: object
      properties:
        chatbot_id:
          type: string
          format: uuid
        version_number:
          type: integer
          nullable: true
          description: Optional version number of the chatbot to use. Requires authentication.
        session_data:
          type: object
          additionalProperties: {}
          title: Initial session data
          description: Optional initial state data for the session. This field will
            be ignored if the request is not authenticated.
        participant_remote_id:
          type: string
          default: ''
          description: Optional ID for the participant from remote systems
        participant_name:
          type: string
          title: Paricipant Name
          description: Optional participant name
      required:
      - chatbot_id
    ChatStartSessionResponse:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        chatbot:
          allOf:
          - $ref: '#/components/schemas/Experiment'
          readOnly: true
        participant:
          allOf:
          - $ref: '#/components/schemas/Participant'
          readOnly: true
      required:
      - chatbot
      - participant
      - session_id
    ChatTaskPoll:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
        status:
          $ref: '#/components/schemas/ChatTaskPollStatusEnum'
    ChatTaskPollError:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
      required:
      - status
    ChatTaskPollStatusEnum:
      enum:
      - processing
      - complete
      type: string
      description: |-
        * `processing` - processing
        * `complete` - complete
    ChatTaskPollUserError:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
      required:
      - status
    ChatUploadFileRequest:
      type: object
      properties:
        files:
          type: array
          items:
            type: string
            format: uri
          description: Files to upload (max 50MB each, 50MB total)
      required:
      - files
    ChatUploadFileResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/UploadedFile'
      required:
      - files
    CreateChatCompletionRequest:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
      - messages
    CreateChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionResponseChoices'
        created:
          type: integer
        model:
          type: string
        object:
          $ref: '#/components/schemas/ObjectEnum'
      required:
      - choices
      - created
      - id
      - model
      - object
    Experiment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 128
        url:
          type: string
          format: uri
          readOnly: true
          title: API URL
        version_number:
          type: integer
          maximum: 2147483647
          minimum: 0
        versions:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentVersion'
      required:
      - id
      - name
      - url
      - versions
    ExperimentSession:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          readOnly: true
        team:
          allOf:
          - $ref: '#/components/schemas/Team'
          readOnly: true
        experiment:
          allOf:
          - $ref: '#/components/schemas/Experiment'
          readOnly: true
        participant:
          allOf:
          - $ref: '#/components/schemas/Participant'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        tags:
          type: array
          items:
            type: string
      required:
      - created_at
      - experiment
      - id
      - participant
      - tags
      - team
      - updated_at
      - url
    ExperimentSessionCreate:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        experiment:
          type: string
          format: uuid
          title: Experiment ID
        participant:
          type: string
          title: Participant identifier
          description: Channel specific participant identifier
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        state: {}
      required:
      - experiment
      - url
    ExperimentSessionWithMessages:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          readOnly: true
        team:
          allOf:
          - $ref: '#/components/schemas/Team'
          readOnly: true
        experiment:
          allOf:
          - $ref: '#/components/schemas/Experiment'
          readOnly: true
        participant:
          allOf:
          - $ref: '#/components/schemas/Participant'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          readOnly: true
        tags:
          type: array
          items:
            type: string
      required:
      - created_at
      - experiment
      - id
      - messages
      - participant
      - tags
      - team
      - updated_at
      - url
    ExperimentVersion:
      type: object
      properties:
        name:
          type: string
          maxLength: 128
        version_number:
          type: integer
          maximum: 2147483647
          minimum: 0
        is_default_version:
          type: boolean
        version_description:
          type: string
      required:
      - name
    File:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
        content_type:
          type: string
        size:
          type: integer
        content_url:
          type: string
          format: uri
          readOnly: true
      required:
      - content_url
      - name
      - size
    Message:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        role:
          $ref: '#/components/schemas/MessageRoleEnum'
        content:
          type: string
        metadata:
          readOnly: true
          description: |2

            Metadata for the message. Currently documented keys:
              * `compression_marker`: Slug that marks this message as a checkpoint for session history compression
        tags:
          type: array
          items:
            type: string
          readOnly: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/File'
          readOnly: true
      required:
      - attachments
      - content
      - created_at
      - metadata
      - role
      - tags
    MessageRoleEnum:
      enum:
      - system
      - user
      - assistant
      type: string
      description: |-
        * `system` - system
        * `user` - user
        * `assistant` - assistant
    ObjectEnum:
      enum:
      - chat.completion
      type: string
      description: '* `chat.completion` - chat.completion'
    PaginatedExperimentList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/Experiment'
    PaginatedExperimentSessionList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentSession'
    PaginatedParticipantDetailList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantDetail'
    Participant:
      type: object
      properties:
        identifier:
          type: string
          maxLength: 320
        remote_id:
          type: string
          maxLength: 255
    ParticipantDataEntry:
      type: object
      properties:
        chatbot:
          type: string
          readOnly: true
        chatbot_id:
          type: string
          format: uuid
          readOnly: true
        data: {}
      required:
      - chatbot
      - chatbot_id
    ParticipantDataUpdateRequest:
      type: object
      properties:
        identifier:
          type: string
          title: Participant Identifier
        name:
          type: string
          title: Participant Name
        platform:
          allOf:
          - $ref: '#/components/schemas/PlatformEnum'
          default: api
          title: Participant Platform
        data:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantExperimentData'
      required:
      - data
      - identifier
    ParticipantDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        identifier:
          type: string
          maxLength: 320
        name:
          type: string
          maxLength: 320
        platform:
          type: string
          maxLength: 32
        remote_id:
          type: string
          maxLength: 255
        data:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantDataEntry'
          readOnly: true
      required:
      - data
      - id
      - platform
    ParticipantExperimentData:
      type: object
      properties:
        experiment:
          type: string
          format: uuid
          title: Experiment ID
        data:
          type: object
          additionalProperties: {}
          title: Participant Data
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantSchedule'
      required:
      - experiment
    ParticipantSchedule:
      type: object
      properties:
        id:
          type: string
          title: Schedule ID
          maxLength: 32
        name:
          type: string
          title: Schedule Name
        prompt:
          type: string
          title: Prompt to send to bot
        date:
          type: string
          format: date-time
          title: Schedule Date
        delete:
          type: boolean
          default: false
          title: Delete Schedule
    Patchedupdate_state_serializer:
      type: object
      properties:
        state: {}
    PlatformEnum:
      enum:
      - telegram
      - web
      - whatsapp
      - facebook
      - sureadhere
      - api
      - slack
      - commcare_connect
      - evaluations
      - embedded_widget
      - email
      type: string
      description: |-
        * `telegram` - Telegram
        * `web` - Web
        * `whatsapp` - WhatsApp
        * `facebook` - Facebook
        * `sureadhere` - SureAdhere
        * `api` - API
        * `slack` - Slack
        * `commcare_connect` - CommCare Connect
        * `evaluations` - Evaluations
        * `embedded_widget` - Embedded Widget
        * `email` - Email
    SessionStatusEnum:
      enum:
      - active
      - ended
      type: string
      description: |-
        * `active` - Active
        * `ended` - Ended
    Team:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        slug:
          type: string
          maxLength: 50
          pattern: ^[-a-zA-Z0-9_]+$
      required:
      - name
      - slug
    TriggerBotMessageRequest:
      type: object
      properties:
        identifier:
          type: string
          title: Participant Identifier
        platform:
          allOf:
          - $ref: '#/components/schemas/PlatformEnum'
          title: Participant Platform
        experiment:
          type: string
          format: uuid
          title: Experiment ID
        prompt_text:
          type: string
          nullable: true
          title: Prompt to go to bot
        message_text:
          type: string
          nullable: true
          title: Message to send directly to participant (bypasses bot/LLM)
        start_new_session:
          type: boolean
          default: false
          title: Starts a new session
        session_data:
          type: object
          additionalProperties: {}
          description: Update session data. This will be merged with existing session
            data
        participant_data:
          type: object
          additionalProperties: {}
          description: Update Participant data. This will be merged with existing
            participant data
      required:
      - experiment
      - identifier
      - platform
    UploadedFile:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        size:
          type: integer
        content_type:
          type: string
      required:
      - content_type
      - id
      - name
      - size
    tags_request_serializer:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
      required:
      - tags
    tags_response_serializer:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
      required:
      - tags
    update_state_response:
      type: object
      properties:
        success:
          type: boolean
        state: {}
      required:
      - state
      - success
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /o/authorize/
          tokenUrl: /o/token/
          scopes:
            chatbots:read: List and Retrieve Chatbot Data
            chatbots:interact: Converse with a Chatbot and trigger bot messages
            sessions:read: List and Read Sessions
            sessions:write: Manage Sessions
            files:read: Download file content
            participants:read: Read Participant Data
            participants:write: Update Participant Data
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-api-key
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    embedKeyAuth:
      type: apiKey
      in: header
      name: X-Embed-Key
      description: Embedded widget authentication token. Validates the widget token
        for the channel configuration and authenticates embedded widget requests.
    tokenAuth:
      type: http
      scheme: bearer
tags:
- name: Chat
  description: "\n                The Chat API is designed to be used for integrating
    chatbots into external systems.\n            "