Implementing Talla's Beacon

The Talla Beacon provides one-click access to Talla. It appears as a floating widget within your intranet pages or your own internal web app.

When clicked, the widget expands to an overlay that lets the user search and interact with your knowledge base, smart wikis, and other Talla services.

Installation

Installing the Talla Beacon in your web app is easy. You'll be including a snippet of JavaScript that makes an init call to our API. The init process requires two parameters: an app_id provided by Talla, and a JWT or SAML token you'll need to generate.

Initializing Talla

Here is an example of initializing Talla via a Javascript call.

In the head section, the page includes a JS script provided by Talla. In the script section after the body, the client calls Talla.init, passing in a JWT authentication token and the app_id, which is a unique identifier provided by Talla.

<html>

<head>

<title>Your Title Here</title>

var appID = '[ app_id ]'

var token = "[ Customer Generated Token ]"

Talla.config = Talla.init(

appID,

Talla.OptionJWTCredentials(token)

)

var beacon = Talla.config.display(Talla.OptionQuickLoadBeacon)

</script>

</head>

<body>Your content here</body>

</html>

Authentication

Talla currently supports authentication via JWT.

Authenticating with SAML

In the SAML case, we currently support only OKTA and Microsoft Azure Active Directory as the SAML provider. Customers should contact Talla Support to set up the integration. Once that integration is complete, clients can generate signed SAML tokens to be used in the runtime call to Talla.init. Each of these SAML tokens should uniquely identify the user and provide the following attributes: first_name, last_name, email, user_id, nickname and timezone. Talla uses this data to identify users and user interactions across sessions. As in the JWT code example, the call to Talla.init should be made after the page load is complete.

Authenticating with JWT

If you are authenticating by calling Talla.init with a JWT token, that token should include the following attributes: first_name, last_name, email, user_id, nickname and timezone. As in the SAML case, Talla will use this data to identify users and user interactions across sessions.

How to Generate JWT Tokens Containing Your Attributes

JSON Web Token (JWT) is an open standard ( RFC 7519) for transmitting JSON objects in a secure and compact way. The information in the JSON object can be verified because it is digitally signed with a secret. For the purpose of authenticating the Talla Beacon, the JWT should be signed using a secret value provide by Talla, and contain the needed identification attributes (first_name, last_name, email, user_id and timezone) in encoded form.

More details and many open source implementations for the JWT standard can be found at ( https://jwt.io). The site includes instructions for downloading and installing the necessary libraries, gems, or packages in Java, Go, JS, Python, Ruby and other languages, as well as links to their repositories on GitHub. Most of these repositories also contain their own documentation and example code for generating JWT tokens and using them in a web app.

The call to generate the JWT token with all these attributes is straightforward. The code snippet below is Ruby, but in JavaScript and other languages the code would be similar:

Ruby:

JWT.encode({

:exp => 1.day.from_now.to_i,

:account => {

first_name: [a string],

last_name: [another string],

email: [email address],

uid: [a uuid string]}),

[the app secret string], #Secret is the APP_SECRET

'HS256')

Note: `exp` expiration date is in unix timestamp

Javascript:

let account = {

uid: md5("jdoe@example.com"),

first_name: "john",

last_name: "doe",

email: "jdoe@example.com",

}

let token = jwt.sign({account: account}, this.state.secret, {algorithm: 'HS256'})

Logo Dimensions

When configuring your Talla beacon, you can choose to add a logo to whitelable the solution to match your organization's branding!

Use:

Takka.config = Talla.init(

Talla.OptionOpenIcon("link_to_logo"), // This is the icon that lives in the beacon CTA (the question-mark on this page)

Talla.OptionBotIcon("link_to_logo") // This is the icon that will appear next to Talla in chat (our Talla logo once you open Talla on this page)

)

What logo file type is the best to use when configuring Talla?

SVG icons are the recommended format.

If you choose to use a different icon format (jpeg, png, etc) then the recommended dimensions are at least 128x128.