sitegpt-ai Chatbot Messages API

openapi: 3.2.0
info:
  title: SiteGPT API Collection Chatbot Messages API
  description: 'This collection contains the documentation of all the API endpoints.

    ## Getting started guide

    To start using the SiteGPT APIs, you need to

    - You must use a valid API Key to send requests to the API endpoints. You can get your API key from SiteGPT''s billing dashboard. If you don''t see it there, contact admin to generate one for you.

    - The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.


    ## Authentication

    SiteGPT uses API keys for authentication. You can generate a SiteGPT API key in the billing dashboard.


    You must include an API key in each request to the Postman API with the Authorization request header.


    Header Name : Authorization


    Header Value : Bearer {{your-api-key}}


    ### Authentication error response

    If an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.


    ## Need some help?

    In case you have any questions, feel free to contact us.'
  license:
    name: SiteGPT Terms and Conditions
    url: https://sitegpt.ai/terms
  version: 1.0.0
  contact:
    name: Bhanu Teja P
    email: bhanu@sitegpt.ai
    url: mailto:bhanu@sitegpt.ai
servers:
- url: https://sitegpt.ai/api
security:
- bearerAuth: []
tags:
- name: Chatbot Messages
  x-displayName: Messages
  description: APIs to send a message to a particular thread or start a new conversation with in a particular chatbot.
  x-mint:
    icon: messages
paths:
  /v0/chatbots/{chatbotId}/message:
    parameters:
    - schema:
        type: string
      name: chatbotId
      in: path
      required: true
      description: Id of the chatbot
    post:
      summary: Send Message
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request Body
              properties:
                threadId:
                  type: string
                  description: If provided, message will be sent to the thread with this threadId. Otherwise, message will be sent to a new thread. This is mandatory when from is AGENT.
                message:
                  type: string
                  description: Actual text containing the message
                from:
                  $ref: '#/components/schemas/ChatFrom'
                iconUrl:
                  type: string
                  description: Icon url to be associated with the message in the conversation thread
                agentName:
                  type: string
                  description: Agent name to be associated with the message in the conversation thread
                prompts:
                  type: array
                  description: Prompts should be provided only when from is AGENT. This provides user list of options to choose from after the message is sent.
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Title of the prompt, this will be shown to the user in the chatbot after the message
                      description:
                        type: string
                        description: Description of the prompt, this will be sent to the chatbot when user clicks on any one of the options provided by the prompts
                includeSmartPrompts:
                  type: boolean
                  default: false
                  description: Flag to decide whether to return smart followup questions based on the AI response.
              required:
              - message
            examples:
              New Thread:
                value:
                  message: What can you do ?
                  from: USER
              Existing Thread:
                value:
                  threadId: xyz
                  message: What can you do ?
                  from: AGENT
                  iconUrl: https://sitegpt.ai/images/chat-icon.png
                  agentName: Test Agent
                  prompts:
                  - title: Contact us
                    description: How to contact you ?
                  - title: Query
                    description: What information do you want ?
        description: Request body to send a message to a particular thread or start a new thread
      parameters:
      - name: chatbotId
        description: Id of the chatbot
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                type: object
                description: Sucess Response
                properties:
                  success:
                    type: boolean
                    description: Indicates whether this is success response or error response
                  message:
                    type: string
                    description: Overall message regarding the operation performed
                  data:
                    type: object
                    description: Data returned from the server
                    properties:
                      message:
                        type: object
                        description: Message object
                        properties:
                          id:
                            type: string
                            description: Id of the message
                          chatbotId:
                            type: string
                            description: Id of the chatbot
                          threadId:
                            type: string
                            description: Id of the thread this message has been sent to
                          question:
                            $ref: '#/components/schemas/ChatQuestionAnswer'
                          answer:
                            $ref: '#/components/schemas/ChatQuestionAnswer'
                          sources:
                            type: array
                            description: Sources referred to provide the above answer
                            items:
                              type: string
                          gptModel:
                            $ref: '#/components/schemas/GPTModel'
                          messageType:
                            $ref: '#/components/schemas/MessageType'
                          iconUrl:
                            type:
                            - string
                            - 'null'
                            description: Icon url associated with the message in the conversation thread
                          agentName:
                            type:
                            - string
                            - 'null'
                            description: Agent name associated with the message in the conversation thread
                          prompts:
                            type: array
                            description: List of prompts of this message
                            items:
                              $ref: '#/components/schemas/QuickPrompt'
                          smartPrompts:
                            type: array
                            description: Smart followup questions based on the AI response. Only returned when includeSmartPrompts is true and from is USER in the request.
                            items:
                              type: string
                          reaction:
                            $ref: '#/components/schemas/MessageReaction'
                      awayMessage:
                        type: object
                        description: Present only when this message was sent to a conversation held by the team, outside the chatbot's working hours, and the chatbot sends an away message. Show its answer text to the visitor. Each conversation gets the away message one time.
                        properties:
                          id:
                            type: string
                            description: Id of the away message
                          chatbotId:
                            type: string
                            description: Id of the chatbot
                          threadId:
                            type: string
                            description: Id of the thread
                          answer:
                            $ref: '#/components/schemas/ChatQuestionAnswer'
                          messageType:
                            $ref: '#/components/schemas/MessageType'
                          systemMessageType:
                            $ref: '#/components/schemas/SystemMessageType'
              examples:
                Success:
                  value:
                    success: true
                    message: Sent the message successfully
                    data:
                      message:
                        id: '376290410396385873'
                        question:
                          text: This is user!!
                          timestamp: '2023-08-03T11:43:52.037718Z'
                        answer:
                          text: This is agent!!
                          timestamp: '2023-08-03T11:19:19.041469Z'
                        sources: []
                        gptModel: gpt-3.5-turbo
                        reaction: NEUTRAL
                        threadId: 06b3b43c-5651-49a2-b618-d7f24667c1b6
                        messageType: AGENT_MESSAGE
                        iconUrl: https://avatars.githubusercontent.com/u/17903466?s=48&v=4
                        agentName: Test Agent
                        prompts:
                        - id: 17e23880-386e-492f-960c-4394baec2977
                          title: Prompt 1
                          description: This is the prompt1 description
                        - id: ab0ba301-90c9-4ef2-8ca8-fa579a104386
                          title: Prompt 2
                          description: This is the prompt2 description
                        smartPrompts:
                        - First smart prompt
                        - Second smart prompt
                        - Third smart prompt
                        chatbotId: '365062873485935184'
        '400':
          description: Bad Request
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: REQUEST_BODY_INVALID
                      message: AGENT cannot start a new thread. threadId field is required when from is AGENT
                      details: null
                Invalid Request Body:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: Request body is not valid
                      details:
                      - path:
                        - from
                        message: Invalid enum value. Expected `USER` | `AGENT`, received `X`
        '401':
          description: Unauthorized
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authentication Error:
                  value:
                    success: false
                    message: Failed to send the message
                    error:
                      code: API_KEY_NOT_VALID
                      message: Authorization header does not contain valid API key
                      details: null
        '403':
          description: Forbidden
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: SEND_MESSAGE_FORBIDDEN
                      message: You are not authorized to send message to this chatbot thread
                      details: null
                Account Inactive Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: ACCOUNT_INACTIVE
                      message: This account has no active plan.
                      details: null
        '404':
          description: Not Found
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Not Found Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: CHATBOT_THREAD_NOT_FOUND
                      message: Chatbot thread does not exist for threadId=1234567890
                      details: null
        '405':
          description: Method Not Allowed
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Method Not Allowed Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: REQUEST_METHOD_NOT_ALLOWED
                      message: PATCH request method is not allowed
                      details: null
        '409':
          description: Conflict
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Conversation Closed Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: CONVERSATION_CLOSED
                      message: This conversation has been closed.
                      details: null
        '500':
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Server Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: SEND_MESSAGE_FAILED
                      message: Some technical error has occurred !!
                      details: null
                Messages Limit Reached Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: CHATBOT_MESSAGES_LIMIT_REACHED
                      message: Normal messages limit reached for the chatbot. You cannot send any more normal messages
                GPT4 Messages Limit Reached Error:
                  value:
                    success: false
                    message: Failed to send the message
                    data: null
                    error:
                      code: CHATBOT_GPT4_MESSAGES_LIMIT_REACHED
                      message: GPT-4.1 messages limit reached for the chatbot. You cannot send any more GPT-4.1 messages
      tags:
      - Chatbot Messages
      operationId: send-message
      description: Send message to a particular thread or start a new thread
  /v0/chatbots/{chatbotId}/messages/{messageId}:
    parameters:
    - schema:
        type: string
      name: chatbotId
      in: path
      required: true
      description: Id of the chatbot that the message belong to
    - schema:
        type: string
      name: messageId
      in: path
      required: true
      description: Id of the message that has to be updated
    patch:
      summary: Update Message
      operationId: update-message
      description: Update message that belongs to a particular thread. You can only add reaction to the message for now.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request Body
              properties:
                threadId:
                  type: string
                  description: Id of the thread that the message belongs to
                reaction:
                  $ref: '#/components/schemas/MessageReaction'
            examples:
              Request Body:
                value:
                  threadId: dd56a3d0-dba7-4df0-b62b-58513230b053
                  reaction: POSITIVE
        description: Request Body to update message
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                type: object
                description: Success Response
                properties:
                  success:
                    type: boolean
                    description: Indicates whether this is success response or error response
                  message:
                    type: string
                    description: Overall message regarding the operation performed
                  data:
                    type:
                    - object
                    - 'null'
                    description: Data returned from the server
              examples:
                Success:
                  value:
                    success: true
                    message: Updated the message successfully
                    data: null
        '400':
          description: Bad Request
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation Error:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: REQUEST_BODY_INVALID
                      message: chatbotId is requried
                      details: null
                Validation Error - 2:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: Request body is not valid
                      details:
                      - path:
                        - reaction
                        message: Required
        '401':
          description: Unauthorized
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authentication Error:
                  value:
                    success: false
                    message: Failed to update the message
                    error:
                      code: API_KEY_NOT_VALID
                      message: Authorization header does not contain valid API key
                      details: null
        '403':
          description: Forbidden
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Error:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: UPDATE_MESSAGE_FORBIDDEN
                      message: You are not authorized to update message of this chatbot thread
                      details: null
        '404':
          description: Not Found
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Not Found Error:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: MESSAGE_NOT_FOUND
                      message: Message does not exist for the given chatbot and thread
                      details: null
        '405':
          description: Method Not Allowed
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Method Not Allowed Error:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: REQUEST_METHOD_NOT_ALLOWED
                      message: POST request method is not allowed
                      details: null
        '500':
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
              description: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Server Error:
                  value:
                    success: false
                    message: Failed to update the message
                    data: null
                    error:
                      code: UPDATE_MESSAGE_FAILED
                      message: Some technical error has occurred !!
                      details: null
      tags:
      - Chatbot Messages
components:
  schemas:
    ChatFrom:
      title: Chat-From
      enum:
      - USER
      - AGENT
      description: Indicates who all can send messages to the chat threads
    SystemMessageType:
      title: System-Message-Type
      description: Type of the message if type of the message is SYSTEM_MESSAGE
      enum:
      - CONVERSATION_ESCALATED
      - EXCEEDED_USAGE_LIMITS
      - EMAIL_VERIFIED
      - ENTERED_WRONG_OTP
      - PROVIDED_EMAIL
      - PERSONA_SELECTED
      - PROBLEMS_WITH_UPSTREAM_PROVIDER
      - COLLECT_LEAD
      - CONVERSATION_SWITCHED_TO_AI
      - MODERATION_FLAGGED
      - HUMAN_SUPPORT_CONFIRMATION
      - HUMAN_TOOK_OVER
      - AWAY_MESSAGE
    GPTModel:
      title: GPT-Model
      enum:
      - gpt-3.5-turbo
      - gpt-4
      description: All available GPT models
    ChatQuestionAnswer:
      title: Chat-Question-Answer
      type:
      - object
      - 'null'
      description: Model for question/answer in the chat
      properties:
        text:
          type: string
          description: Text containing either question or the answer
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the question asked or answer replied
    MessageType:
      title: Message-Type
      description: Type of the message in the thread
      enum:
      - NORMAL_MESSAGE
      - USER_MESSAGE
      - AGENT_MESSAGE
      - SYSTEM_MESSAGE
    QuickPrompt:
      type: object
      description: Chatbot Conversation Starter
      properties:
        id:
          type: string
          description: Id of the conversation-starter
        title:
          type: string
          description: Title of the conversation-starter. This is the text that is shown as button in the chatbot.
        link:
          type:
          - string
          - 'null'
          description: Link of the conversation starter. If this link is not null, then when you click on the conversation starter in the chatbot, this link will be opened instead of sending a message to the chatbot.
        description:
          type: string
          description: Description of the conversation-starter. This is the message that will be sent to the chatbot when you click on the conversation-starter inside the chatbot.
    ErrorResponse:
      type: object
      description: Error Response
      properties:
        success:
          type: boolean
          description: Indicates that this is error response
        message:
          type: string
          description: Overall error message regarding the operation performed
        data:
          type:
          - object
          - 'null'
          description: Data returned from the API. This will be `null` for errors
        error:
          type: object
          description: Object with the error details
          properties:
            code:
              type: string
              description: Based on this error code, you can identify what is the error
            message:
              type: string
              description: The message indicating the reason for the error
            details:
              type:
              - array
              - 'null'
              description: More details on the error. Applicable only for Validation errors
              items:
                type: object
                properties:
                  path:
                    type: array
                    description: Specifies the path in request body where error occurred. If the error field is nexted, then this array length will be more than 1.
                    items:
                      oneOf:
                      - type: string
                        description: Specifies the name of the field
                      - type: integer
                        description: Specifies the position in an array
                  message:
                    type: string
                    description: Reason for the error of the path mentioned before
    MessageReaction:
      title: Message-Reaction
      description: User's reaction to the message
      enum:
      - POSITIVE
      - NEGATIVE
      - NEUTRAL
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer