Embeddable Read-only Conversation
Tuesday, June 2, 2020 6:22 AMNote: 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 paremeters:
-
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 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:
- 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. - The signature needs to be generated in a way that includes the same timestamp generated above in step 1.
// Pseudo-code example
signature = hmac(secret_key, conversation_id + "." + valid_until)
// Node.js example
const crypto = require('crypto');
const secretKey = "your secrey key";
const conversationId = "the conversation id";
// make the signature only valid for 1 hour
const validUntil = new Date() + 60 * 60;
const auth_token = crypto.createHmac('sha256', secretKey)
.update(conversationId + "." + validUntil)
.digest('hex');
Example URL:
https://talkjs.com/embed/{app_id}/{conversation_id}?auth_token={auth_token}&view_as={user_id}&valid_until={unix_timestamp}