Embeddable read-only conversation

This UI mode is currently in public beta. Feedback on this new feature is appreciated.

This UI mode allows you to easily embed a single, read-only conversation which can be used to for several use cases, such as allowing non-authenticated users to view but not participant in conversations, or to allow privileged team members to review conversations.

Unlike the other UI modes, the embeddable read-only conversation doesn't require the JavaScript SDK. Instead the UI can be displayed by simply using an IFrame to a specific URL.

The URL also accepts three parameters:

  • auth_token - Required. This parameter is used to ensure that only authorised people have access to the conversation.
  • view_as - Optional. An ID of a User that the chat should be viewed as.
  • valid_until - Optional. A unix timestamp in milliseconds of how long the auth_token is valid for.

Generating the authentication token

In order to view the conversation, a valid auth_token must be passed as a parameter in the URL for security purposes; authentication tokens for this endpoint are generated the same way signatures are for authentication (identity verification), however the conversation_id is used instead of the user_id.

For additional security, the signatures can be generated in a way that allows them only to be valid for until a certain time. To make the signature valid for a certain amount of time, two things must be done:

  1. Firstly, the URL parameter valid_until needs to be added, along with a unix timestamp in milliseconds of a time in the future when the token should expire.
  2. The signature needs to be generated in a way that includes the same timestamp generated above in step 1.

Node.js example

1const crypto = require('crypto');
2

3const appId = 'your app_id';
4const secretKey = 'your secret key';
5const conversationId = 'your conversation id';
6

7// make the signature only valid for 1 hour
8const validUntil = new Date(new Date().getTime() + 60 * 60000).getTime();
9

10const authToken = crypto
11  .createHmac('sha256', secretKey)
12  .update(conversationId + '.' + validUntil)
13  .digest('hex');
14

15console.log(
16  `https://talkjs.com/embed/${appId}/${conversationId}?auth_token=${authToken}&valid_until=${validUntil}`
17);

Example URL:

https://talkjs.com/embed/{app_id}/{conversation_id}?auth_token={auth_token}&view_as={user_id}&valid_until={unix_timestamp}