Participant

A participant is a part of a Conversation. It holds user preferences at the scope of the conversation, such as the access rights, notification toggle.

All calls on this page are idempotent operations and can be called multiple times in a row.

Join conversation

You can add any user to a conversation with the Join call. When you add a new user to a conversation, that user will have access to all of the chat history including any chat history created before they joined. This also applies to a user that was removed and added again later. The Join call expects a payload as specified in the reference. It always overwrites values set before.

PUT/v1/{appId}/conversations/{conversationId}/participants/{userId}
1{
2  notify?: boolean | "MentionsOnly",
3  access?: "ReadWrite" | "Read"
4}

Example request

1curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer YOUR_SECRET_KEY" \
4-X PUT
5-d '{ "access": "Read", "notify": true }'

If you don't pass anything it will fallback to the following defaults:

1{
2    "access": "ReadWrite",
3    "notify": true
4}

Group chats are limited to 100 participants per chat on the Basic plan and 300 participants per chat on the Growth plan. On the Enterprise plan, the limit is customisable to fit your needs.

Modify participation

If a user is already a participant of the conversation then you can toggle sending notifications, or modify their writing rights. The payload structure is the same as for the Join call. This call will only update fields given in the payload, leaving the old ones as they were.

PATCH/v1/{appId}/conversations/{conversationId}/participants/{userId}
1{
2  notify?: boolean | "MentionsOnly",
3  access?: "ReadWrite" | "Read" | "None"
4}

Example request

1curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer YOUR_SECRET_KEY" \
4-X PATCH
5-d '{ "access": "ReadWrite", "notify": false }'

Leave conversation

When a user leaves a conversation they will no longer be listed as a participant in the conversation and the user will not be able to see any new messages sent to the conversation.

DELETE/v1/{appId}/conversations/{conversationId}/participants/{userId}

  • Since version 2021-07-30:

    Removing a user from the conversation removes it completely from their conversation list, they won't be able to look at any old messages. To get the old behaviour, you can modify the participation with access field set to "None"

  • Initial version (2021-01-01):

    After the user has left, the conversation will still appear in their list of conversations in the inbox UI and when the user's conversations are fetched via the REST API. The user will be able to look through old messages and see who was part of the conversation before they left.

Example request

1curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer YOUR_SECRET_KEY" \
4-X DELETE