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 };
  lastMessage?: Message;
  participants: {
    [id: UserId]: {access: "ReadWrite" | "Read", notify: boolean}
  };
  createdAt: UnixMilliseconds;
}

Deleting a conversation

Use this endpoint to irrevocably delete data for a certain conversationId. All the data and metadata linked to the conversation will be deleted. Here is the list of things that will happen:

1. All messages in the conversation will be deleted.
2. Participants will not be a part of the conversation anymore.
3. All the conversation metadata will be erased.
4. Active UIs will display a "Chat not found" screen (which is localized).
5. The conversation gets removed from all (former) participants' Inbox feeds.

NOTE: Users that take part in the conversation WILL NOT be deleted.

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

Marking a conversation as read

This endpoint is used to mark a conversation as read for a specific user. Doing so will also mark any messages within the conversation as read by that user.

POST https://api.talkjs.com/v1/{appId}/conversations/{conversationId}/readBy/{userId}

Listing all conversations in the application

This lists all conversations ever created in your TalkJS application. This request is paginated as explained here. The response has a data field with an array of Conversation objects as described above.

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

{
  data: [
    { 
      id: "conv_12345",
      subject: "Nice shoes"
      ...
    },
    ...
  ]
}

Filtering conversations

By the last message's timestamp

It is possible to filter conversations by when the last message was sent to the conversation using the lastMessageBefore and lastMessageAfter filters.

lastMessageBefore and lastMessageAfter should be Unix timestamps expressed in milliseconds.

By custom fields.

TalkJS also supports filtering by custom fields. The filter interface is precisely the same as the JavaScript SDK's Conversation Filter, excluding the oneOf filter. In order to filter conversations by a custom field you need to URLencoded the JSON formatted filter.

You can use your favorite programming language to generate the conversation filter in the required JSON structure.

NodeJS example:

const filter = {custom: {category: ["==", "shoes"]}};
const encodedFilter = encodeURIComponent(JSON.stringify(filter));
const res = await fetch(`https://api.talkjs.com/v1/${appId}/conversations?filter=${encodedFilter}`);
const conversations = await res.json();

Filters can be combined together with limits and cursors.

Examples

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

// URL encoded version of the filter {"custom":{"category":["==","shoes"]}
GET https://api.talkjs.com/v1/{appId}/conversations?filter=%7B%22custom%22%3A%7B%22category%22%3A%5B%22%3D%3D%22%2C%22shoes%22%5D%7D

Limits and pagination

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

Filtering by user

The Users resource lets you list the conversations a specific user is a part of.