A single conversation

GET returns a single Conversation or an HTTP 404 status if no conversation exists for the given conversation ID.

PUT creates or updates a conversation.

Path: /v1/{appId}/conversations/{conversationId}
Methods:GET, PUT

Example url: /v1/q3k1pa9d/conversations/order_fc_491731

Setting conversation data

PUT can be used to create a conversation or to update (a subset of) its attributes:

PUT https://api.talkjs.com/v1/{appId}/conversations/{conversationId}

  "participants": Array<string>,
  "subject": string,
  "welcomeMessages": Array<string>,
  "custom": Map<string, string>,
  "photoUrl": string

Example payload:

  "participants": ["123456", "654321"],
  "subject": "Black leather boots",
  "welcomeMessages": ["Hello there!", "I'm currently out of town, leave a message and I'll respond ASAP. :)"],
  "custom": {
    "productId": "454545"
  "photoUrl": "https://example.com/productpictures/454545.png"

Note: PUT merges data with existing data, if any. For example, you cannot remove participants from a conversation by PUTing a list of participants that excludes some existing participants. If you want to remove participants from a conersation, use the Participation endpoint.

Getting created conversations

After you successfully create or update a conversation, you can fetch it back with a GET REST call.

GET https://api.talkjs.com/v1/{appId}/conversations/{conversationId}

The interface for this resource is the following:

type UnixMilliseconds = number;

type Conversation = {
  id: ConversationId;
  subject?: string;
  topicId?: string;
  photoUrl?: string;
  welcomeMessages?: string[];
  custom?: {[name: string]: string };
  participants: {
    [id: UserId]: {access: "ReadWrite" | "Read", notify: boolean}
  createdAt: UnixMilliseconds;

Listing all conversations in the application

You can list all conversations ever created in your TalkJS application. The structure of the response is explained here.

GET https://api.talkjs.com/v1/{appId}/conversations
Limits and pagination

Similarly to other list requests, pagination and limits are applicable to listing conversations.


If you want to filter conversations you have the following options:

  • last message in the conversation was send before or/and after an arbitrary date. lastMessageBefore and lastMessageAfter are Unix timestamps expressed in milliseconds. Filters can be combined together with limits and cursors.
GET https://api.talkjs.com/v1/{appId}/conversations
GET https://api.talkjs.com/v1/{appId}/conversations?lastMessageBefore=1521522849308&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/conversations?limit=50&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/conversations?startingAfter=c_21

Deprecated: Conversation without a unique identifier

Path: /v1/{appId}/conversations/participants={userIds}
Methods:GET, PUT

Note: Do not use this endpoint in new projects. Instead, choose an appropriate conversation ID for your situation.

If your JavaScript code uses the getOrStartConversation method to start converstions then you need to use this endpoint. getOrStartConversation generates an internal conversation ID and this endpoint allows you to find (or create) a conversation without specifying this ID.

For this endpoint, conversations are uniquely identified by the following set of parameters: participants and an optional topic, which must match the parameters that were sent to getOrStartConversation {userIds} is a comma-separated list of user IDs. Include a {topicId} if you uniquely identify conversations per topic, omit it otherwise.

Example url: /v1/q3k1pa9d/conversations/participants=42,98;topic=612

Note that this endpoint only works if you create conversations using getOrCreateConversation, which we do not recommend. It is not a general way to look up conversations that have two particular participants.