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/<APP_ID>/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <YOUR_TOKEN>" \
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.

Get participant's inbound email address

TalkJS allows you to send emails that will appear in the conversation as being sent from a particular participant. This endpoint retrieves the email address to send emails to for that to happen.

Important: These email addresses are very sensitive since they allow you to impersonate other users.

Make sure only authorised users have access to their own inbound email addresses.

GET/v1/{appId}/conversations/{conversationId}/participants/{userId}/email
1{
2  "emailAddress": string
3}

Example request

1curl https://api.talkjs.com/v1/<APP_ID>/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <YOUR_TOKEN>" \
4-X GET

In this example we fetch the reply-to email address for user user_924772 in conversation order_391_fc. Any emails sent to the address specified in the response, will appear as messages sent by that user in that conversation.

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/<APP_ID>/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <YOUR_TOKEN>" \
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/<APP_ID>/conversations/order_391_fc/participants/user_924772 \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <YOUR_TOKEN>" \
4-X DELETE