openapi: 3.0.1
info:
  title: TalkJS REST API
  description: >-
    The TalkJS REST API for managing users, conversations, participants, and
    messages, and for importing existing chat history. All requests are scoped
    to an application by appId in the path and authenticated with a Bearer
    token (a server-side secret key or a short-lived JWT with admin claims).
  termsOfService: https://talkjs.com/terms-of-service/
  contact:
    name: TalkJS Support
    url: https://talkjs.com/contact/
  version: '1.0'
servers:
  - url: https://api.talkjs.com/v1/{appId}
    description: TalkJS REST API, scoped to a single application.
    variables:
      appId:
        default: YOUR_APP_ID
        description: Your TalkJS application identifier from the dashboard.
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Create, update, retrieve, and list users; manage presence.
  - name: Conversations
    description: Create, update, list, and delete conversations.
  - name: Participants
    description: Add, update, and remove conversation participants.
  - name: Messages
    description: Send, list, fetch, edit, delete messages, and manage reactions.
  - name: Import
    description: Import messages with original timestamps.
paths:
  /users/{userId}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    put:
      operationId: createOrUpdateUser
      tags:
        - Users
      summary: Create or update a user
      description: >-
        Upserts a user. Only the subset of fields you send is updated
        (PATCH-style semantics).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: The user was created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      operationId: getUser
      tags:
        - Users
      summary: Retrieve a user
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List users
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: batchUpdateUsers
      tags:
        - Users
      summary: Batch create or update users
      description: Upserts up to 100 users in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/UserInput'
              description: Map of userId to user object.
      responses:
        '200':
          description: The users were created or updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /users/{userId}/conversations:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: listUserConversations
      tags:
        - Users
        - Conversations
      summary: List a user's conversations
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of conversations the user participates in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{userId}/presence:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserPresence
      tags:
        - Users
      summary: Get user presence
      responses:
        '200':
          description: The user's presence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Presence'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: setUserPresence
      tags:
        - Users
      summary: Set user presence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Presence'
      responses:
        '200':
          description: Presence updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /conversations:
    get:
      operationId: listConversations
      tags:
        - Conversations
      summary: List conversations
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of conversations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /conversations/{conversationId}:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
    get:
      operationId: getConversation
      tags:
        - Conversations
      summary: Retrieve a conversation
      responses:
        '200':
          description: The requested conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: createOrUpdateConversation
      tags:
        - Conversations
      summary: Create or update a conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationInput'
      responses:
        '200':
          description: The conversation was created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteConversation
      tags:
        - Conversations
      summary: Delete a conversation
      responses:
        '200':
          description: The conversation was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /conversations/{conversationId}/participants/{userId}:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/UserId'
    put:
      operationId: joinConversation
      tags:
        - Participants
      summary: Add or update a participant
      description: Adds a user to the conversation or updates their access and notify settings.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipationInput'
      responses:
        '200':
          description: The participant was added or updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: leaveConversation
      tags:
        - Participants
      summary: Remove a participant
      responses:
        '200':
          description: The participant was removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{userId}/conversations/{conversationId}:
    parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/ConversationId'
    patch:
      operationId: markConversationRead
      tags:
        - Conversations
        - Participants
      summary: Mark a conversation read or unread for a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                readUntil:
                  oneOf:
                    - type: integer
                      format: int64
                      description: Unix timestamp in ms up to which the user has read.
                    - type: string
                      enum:
                        - sent
                  description: Read marker, or "sent" to mark fully read.
      responses:
        '200':
          description: Read state updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /conversations/{conversationId}/messages:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
    get:
      operationId: listMessages
      tags:
        - Messages
      summary: List messages in a conversation
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: sendMessages
      tags:
        - Messages
      summary: Send messages
      description: Sends one or more messages. The request body is an array of message objects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SendMessageInput'
      responses:
        '200':
          description: The messages were sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /conversations/{conversationId}/messages/{messageId}:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/MessageId'
    get:
      operationId: getMessage
      tags:
        - Messages
      summary: Retrieve a message
      responses:
        '200':
          description: The requested message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: editMessage
      tags:
        - Messages
      summary: Edit a message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                custom:
                  $ref: '#/components/schemas/Custom'
      responses:
        '200':
          description: The message was edited.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteMessage
      tags:
        - Messages
      summary: Delete a message
      responses:
        '200':
          description: The message was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /conversations/{conversationId}/messages/{messageId}/reactions/{emoji}/{userId}:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
      - $ref: '#/components/parameters/MessageId'
      - name: emoji
        in: path
        required: true
        schema:
          type: string
        description: The emoji for the reaction.
      - $ref: '#/components/parameters/UserId'
    put:
      operationId: addReaction
      tags:
        - Messages
      summary: Add an emoji reaction
      responses:
        '200':
          description: The reaction was added.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeReaction
      tags:
        - Messages
      summary: Remove an emoji reaction
      responses:
        '200':
          description: The reaction was removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /import/conversations/{conversationId}/messages:
    parameters:
      - $ref: '#/components/parameters/ConversationId'
    post:
      operationId: importMessages
      tags:
        - Import
      summary: Import messages with timestamps
      description: >-
        Imports messages into a conversation preserving original createdAt
        timestamps. Import users and conversations with the normal endpoints
        first, then import their messages here.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ImportMessageInput'
      responses:
        '200':
          description: The messages were imported.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /batch:
    post:
      operationId: batchRequests
      tags:
        - Import
      summary: Execute a batch of API operations
      description: Executes multiple REST API operations in a single request (1 batch per second).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: The batch was processed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A TalkJS secret key or a short-lived JWT with admin claims, sent as
        "Authorization: Bearer <token>".
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: string
      description: The unique user identifier.
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
      description: The unique conversation identifier.
    MessageId:
      name: messageId
      in: path
      required: true
      schema:
        type: string
      description: The unique message identifier.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
      description: Maximum number of items to return per page.
    StartingAfter:
      name: startingAfter
      in: query
      required: false
      schema:
        type: string
      description: Pagination cursor; returns items after this id.
  responses:
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; the rate limit was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Custom:
      type: object
      additionalProperties:
        type: string
      description: Custom key-value metadata (string values).
    UserInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        email:
          type: array
          items:
            type: string
          nullable: true
        phone:
          type: array
          items:
            type: string
          nullable: true
        photoUrl:
          type: string
          nullable: true
        role:
          type: string
          nullable: true
        welcomeMessage:
          type: string
          nullable: true
        availabilityText:
          type: string
          nullable: true
        locale:
          type: string
          nullable: true
        custom:
          $ref: '#/components/schemas/Custom'
        pushTokens:
          type: object
          additionalProperties: true
          nullable: true
    User:
      allOf:
        - $ref: '#/components/schemas/UserInput'
        - type: object
          properties:
            id:
              type: string
            createdAt:
              type: integer
              format: int64
              description: Unix timestamp in milliseconds.
    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Presence:
      type: object
      properties:
        visible:
          type: boolean
        lastChanged:
          type: integer
          format: int64
        availability:
          type: string
          enum:
            - online
            - offline
    ParticipationInput:
      type: object
      properties:
        access:
          type: string
          enum:
            - ReadWrite
            - Read
        notify:
          oneOf:
            - type: boolean
            - type: string
              enum:
                - MentionsOnly
    Participant:
      type: object
      properties:
        access:
          type: string
          enum:
            - ReadWrite
            - Read
        notify:
          oneOf:
            - type: boolean
            - type: string
              enum:
                - MentionsOnly
        isUnread:
          type: boolean
        joinedAt:
          type: integer
          format: int64
        readUntil:
          type: integer
          format: int64
          nullable: true
    ConversationInput:
      type: object
      properties:
        subject:
          type: string
          nullable: true
        photoUrl:
          type: string
          nullable: true
        welcomeMessages:
          type: array
          items:
            type: string
          nullable: true
        custom:
          $ref: '#/components/schemas/Custom'
        participants:
          type: array
          items:
            type: string
          description: User ids to add as participants.
    Conversation:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
          nullable: true
        photoUrl:
          type: string
          nullable: true
        welcomeMessages:
          type: array
          items:
            type: string
          nullable: true
        custom:
          $ref: '#/components/schemas/Custom'
        topicId:
          type: string
          nullable: true
        lastMessage:
          $ref: '#/components/schemas/Message'
        participants:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Participant'
        createdAt:
          type: integer
          format: int64
        everyoneReadUntil:
          type: integer
          format: int64
          nullable: true
    ConversationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
    SendMessageInput:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - UserMessage
            - SystemMessage
        text:
          type: string
          description: The message text. Mutually exclusive with content.
        content:
          type: array
          items:
            type: object
          description: Rich content blocks. Mutually exclusive with text.
        sender:
          type: string
          description: Sender user id; required for UserMessage, omitted for SystemMessage.
        referencedMessageId:
          type: string
          nullable: true
        custom:
          $ref: '#/components/schemas/Custom'
        idempotencyKey:
          type: string
          description: Ensures exactly-once delivery for 24 hours.
    ImportMessageInput:
      allOf:
        - $ref: '#/components/schemas/SendMessageInput'
        - type: object
          properties:
            createdAt:
              type: integer
              format: int64
              description: Original Unix timestamp in milliseconds to preserve.
            readBy:
              type: array
              items:
                type: string
    Message:
      type: object
      properties:
        id:
          type: string
        conversationId:
          type: string
        senderId:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - UserMessage
            - SystemMessage
        origin:
          type: string
          enum:
            - rest
            - email
            - import
            - web
        text:
          type: string
          nullable: true
        attachment:
          type: object
          nullable: true
        location:
          type: array
          items:
            type: number
          nullable: true
        custom:
          $ref: '#/components/schemas/Custom'
        readBy:
          type: array
          items:
            type: string
        referencedMessageId:
          type: string
          nullable: true
        reactions:
          type: object
          additionalProperties: true
        createdAt:
          type: integer
          format: int64
        editedAt:
          type: integer
          format: int64
          nullable: true
    MessageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string