A participation is a part of a Conversation. It holds user preferences at the scope of the conversation (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.

Path: /v1/{appId}/conversations/{conversationId}/participants/{userId}
Methods:PUT
Payload: { notify?: boolean, access?: "ReadWrite" | "Read" }

Example request:

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

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

{
    "access": "ReadWrite",
    "notify": true
}

Note: Group chats are limited to 10, 20 and 40 participants per chat on the Lite, Standard and Premium plans respectively.

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.

Path: /v1/{appId}/conversations/{conversationId}/participants/{userId}
Methods:PATCH
Payload: { notify?: boolean, access?: "ReadWrite" | "Read" }

Example request:

curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/participants/user_924772 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X PATCH
-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. However, 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.

Path: /v1/{appId}/conversations/{conversationId}/participants/{userId}
Methods:DELETE
curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/participants/user_924772 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X DELETE