openapi: 3.0.1
info:
  title: TalkJS REST Conversations Messages 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: Messages
  description: Send, list, fetch, edit, delete messages, and manage reactions.
paths:
  /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'
components:
  schemas:
    MessageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Custom:
      type: object
      additionalProperties:
        type: string
      description: Custom key-value metadata (string values).
    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
    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.
  responses:
    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'
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    MessageId:
      name: messageId
      in: path
      required: true
      schema:
        type: string
      description: The unique message identifier.
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: string
      description: The unique user identifier.
    StartingAfter:
      name: startingAfter
      in: query
      required: false
      schema:
        type: string
      description: Pagination cursor; returns items after this id.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
      description: Maximum number of items to return per page.
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
      description: The unique conversation identifier.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A TalkJS secret key or a short-lived JWT with admin claims, sent as "Authorization: Bearer <token>".'