Conversations
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.
Example url: /v1/q3k1pa9d/conversations/order_fc_491731
PUT can be used to create a conversation or to update (a subset of) its attributes:
{"participants": Array<string>,"subject": string,"welcomeMessages": Array<string>,"custom": Map<string, string>,"photoUrl": string}
{"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"}
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 conversation, use the Participation endpoint.
After you successfully create or update a conversation, you can fetch it back with a GET REST call.
type ConversationId = string;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;};
{"createdAt": 1623926680929,"custom": {},"id": "87d70908d90cee5d12bd","lastMessage": {"attachment": null,"conversationId": "87d70908d90cee5d12bd","createdAt": 1632919967033,"editedAt": null,"custom": {},"id": "msg_0UQbqdxnQWkoIw7Db7fZHK","location": null,"origin": "web","readBy": [],"senderId": "432156789","text": "Hey, I'm in London","type": "UserMessage","referencedMessageId": null},"participants": {"123456789": {"access": "ReadWrite","notify": true},"432156789": {"access": "ReadWrite","notify": true}},"photoUrl": null,"subject": "Random conversation","topicId": null,"welcomeMessages": null}
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:
- All messages in the conversation will be deleted.
- Participants will not be a part of the conversation anymore.
- All the conversation metadata will be erased.
- Active UIs will display a "Chat not found" screen (which is localized).
- The conversation gets removed from all (former) participants' Inbox feeds.
NOTE: Users that take part in the conversation WILL NOT be deleted.
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.
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.
{"data": Array<Conversation>}
{"data": [{"createdAt": 1623926680929,"custom": {},"id": "87d70908d90cee5d12bd","lastMessage": {"attachment": null,"conversationId": "87d70908d90cee5d12bd","createdAt": 1630326385720,"editedAt": null,"custom": {},"id": "msg_7HtvCJLjdZoRsYE2nCXp2n","location": null,"origin": "web","readBy": ["123456789"],"senderId": "432156789","text": "it","type": "UserMessage","referencedMessageId": null},"participants": {"123456789": {"access": "ReadWrite","notify": true},"432156789": {"access": "ReadWrite","notify": true}},"photoUrl": null,"subject": "Random conversation","topicId": null,"welcomeMessages": null},{...}]}
Ordering is available since API version 2021-02-09
Default order in versions before 2021-02-09
is createdAt DESC
and cannot be changed
By default, conversations are returned in the order of the last activity in them, latest first. You can change the order by using orderBy
and orderDirection
query parameters. Conversations can either be sorted on a creation date or on the last activity in that conversation. Ordering conversations by the creation date can be useful when you want stable sorting.
Following values are accepted in orderBy
query parameter:
lastActivity
(default): sort by last activity timestampcreatedAt
: sort by date of creation
Following values are accepted in orderDirection
query parameter:
DESC
(default): descending orderASC
: ascending order
offsetTs
is available since API version2021-02-09
Conversations can be paginated, as any other listing handle.
Using startingAfter
requires passing in a conversation ID, whereby results will start with the conversation right after the selected one in the current sort order. It works with all currently supported sorting options.
Another option is to use offsetTs
which accepts a timestamp and offsets the results according to the sort order. This might be more useful when used in conjunction with lastActivity
sorting since conversations can move to the front of the list as new messages come, and using one of the conversations as a pointer can yield unexpected results.
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.
TalkJS also supports filtering by custom
fields. The filter interface is precisely the same as the JavaScript SDK's Conversation 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}/conversationsGET https://api.talkjs.com/v1/{appId}/conversations?lastMessageBefore=1521522849308&lastMessageAfter=1421522849732GET https://api.talkjs.com/v1/{appId}/conversations?limit=50&lastMessageAfter=1421522849732GET 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
The Users resource lets you list the conversations a specific user is a part of.
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 getOrStartConversation
, which we do not recommend. It is not a general way to look up conversations that have two particular participants.