Create, update, list, and delete conversations, and manage their participants - join (PUT), leave (DELETE), and set access (ReadWrite/Read) and notification preferences. Includes marking conversations read/unread per user.
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