TalkJS

TalkJS Conversations API

Create, update, list, and delete conversations.

Documentation GitHub OpenAPI

Operations 6

GET /users/{userId}/conversations List a user's conversations #

GET /conversations List conversations #

GET /conversations/{conversationId} Retrieve a conversation #

PUT /conversations/{conversationId} Create or update a conversation #

DELETE /conversations/{conversationId} Delete a conversation #

PATCH /users/{userId}/conversations/{conversationId} Mark a conversation read or unread for a user #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/talkjs-conversations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: TalkJS REST Conversations 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: Conversations
  description: Create, update, list, and delete conversations.
paths:
  /users/{userId}/conversations:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: listUserConversations
      tags:
      - 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'
  /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'
  /users/{userId}/conversations/{conversationId}:
    parameters:
    - $ref: '#/components/parameters/UserId'
    - $ref: '#/components/parameters/ConversationId'
    patch:
      operationId: markConversationRead
      tags:
      - Conversations
      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'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
      description: Maximum number of items to return per page.
    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.
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
      description: The unique conversation identifier.
  schemas:
    ConversationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
    ConversationInput:
      type: object
      properties:
        subject:
          type:
          - string
          - 'null'
        photoUrl:
          type:
          - string
          - 'null'
        welcomeMessages:
          type:
          - array
          - 'null'
          items:
            type: string
        custom:
          $ref: '#/components/schemas/Custom'
        participants:
          type: array
          items:
            type: string
          description: User ids to add as participants.
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Custom:
      type: object
      additionalProperties:
        type: string
      description: Custom key-value metadata (string values).
    Conversation:
      type: object
      properties:
        id:
          type: string
        subject:
          type:
          - string
          - 'null'
        photoUrl:
          type:
          - string
          - 'null'
        welcomeMessages:
          type:
          - array
          - 'null'
          items:
            type: string
        custom:
          $ref: '#/components/schemas/Custom'
        topicId:
          type:
          - string
          - 'null'
        lastMessage:
          $ref: '#/components/schemas/Message'
        participants:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Participant'
        createdAt:
          type: integer
          format: int64
        everyoneReadUntil:
          type:
          - integer
          - 'null'
          format: int64
    Message:
      type: object
      properties:
        id:
          type: string
        conversationId:
          type: string
        senderId:
          type:
          - string
          - 'null'
        type:
          type: string
          enum:
          - UserMessage
          - SystemMessage
        origin:
          type: string
          enum:
          - rest
          - email
          - import
          - web
        text:
          type:
          - string
          - 'null'
        attachment:
          type:
          - object
          - 'null'
        location:
          type:
          - array
          - 'null'
          items:
            type: number
        custom:
          $ref: '#/components/schemas/Custom'
        readBy:
          type: array
          items:
            type: string
        referencedMessageId:
          type:
          - string
          - 'null'
        reactions:
          type: object
          additionalProperties: true
        createdAt:
          type: integer
          format: int64
        editedAt:
          type:
          - integer
          - 'null'
          format: int64
    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
          - 'null'
          format: int64
  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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A TalkJS secret key or a short-lived JWT with admin claims, sent as "Authorization: Bearer <token>".'