SDK Javascript

You take the SDK, you stay in Wonderland.

The SDK Javascript will indicate you how to add more advanced code. Nevertheless, for more simple How to install FROGED manually? with an script  

After starting a Froged trial, just copy the code snippet under "Manual code installation" on the settings - install menu.

This snippet is pre-populated with your unique workspace ID:

window.frogedSettings = { appId: "workspace_id" }; 
There are other properties that can be included in the settings object to modify the appearance or behavior of the widget.

// frogedSettings can include several options
frogedSettings: {
    appId: string,            // Froged Workspace id
    onlyTracking: boolean,    // Optional: Froged only track. No widget. Default false
    languageCode: string,     // Optional: Override browser language forcing a custom localization. Default ''
    kbTags: [string],         // Optional: An array of documents tags visibles in widget. By default [] (all public documents are visible)
   // Optional: Override froged settings
    settings: {
        hidden: boolean,
        position: 'left' | 'right',
        colorMain: string,
        colorAccent: string,
        colorBubble: string,
        defaultLanguage: string,
        logoLayout: boolean,
        logoURL: string,
        moduleChatDisabled: boolean,
        moduleDocumentsDisabled: boolean,
        moduleUpdatesDisabled: boolean,
        requestEmail: 'Always' | 'No online agents' | 'Never',
        qualificationFormActive: boolean,
        gdpr_chat: boolean,
        gdpr_privacyPolicy: string,


With them we can execute actions in the SDK.


This function will initiate the script call and connect to the server. Note: This function does not need to be included for normal operation, because it is already included in the installation script


Will save a cookie in the browser that later let to auto-connect. It will return a session id that will be automatically saved in the cookie. The next time that visitor (anonymous so far) enters the web, he will be identified with cookie. If the application has already been initialized, a new call will be ignored.


With this function disconnect the session from the server and delete the browser cookie. Automatically create a new anonymous session. It is very useful when the user logs out of the application. In this way, all the information, conversations, ... will not be accessible to new visitors from that same computer, who will be identified as anonymous until they are identified.



Not only disconnects the session (deleting the session cookie), but it disconnects from the server (eliminating the cookie from the app) so that tracking is stopped. If the browser is reloaded, nothing will be tracked until you call boot function. It is useful when we do not want to track visitors, but only logged customers



Variable. It allows to know the state in which the script is located. If the boot function was executed, the state that will return us will be true, if not, or make a call to shutdown, the status it will return will be false

Froged('connected'): boolean


Returns the information of the current session
Froged('auth'): { sessionId: string, email: string, userId: string, verified: boolean }


With this function the visitor information is updated. To do this, the script must be connected. We can verify this by using the variable connected. Attributes userId and email are especially important with these attributes the merge is made between a visitor and a contact

Froged('set', { 
    avatar?,                      // IMG URL title?,
    lat?,                         // Latitude (number) 
    lon?,                         // Longitude (number) 
    newsletter,                   //bool
    whatsappNumber, //Whatsapp Number format E.164 ([+][country code][number])

This method accepts predefined attributes (those listed above and available on Froged) as well as custom attributes previously defined in the app.


Froged('set', { 
    email: '',
    name: 'John Smith',
    company: 'Acme'

Predefined attributes

Attribute nameTypeDescription
userIdstringUnique contact id
emailstringContact email
namestringFull name of the contact
usernamestringNick or username of contact
firstnamestringContact's firstname
lastnamestringContact's lastname
genderoptionmale | female
birthdatedateContact birthdate
streetstringStreet and number
postalcodestringPostal code / ZIP
phonestringPhone number
companystringCompany where contact works
whatsappNumber stringWhatsapp Number format E.164 ([+][country code][number])
descriptionstringRole description
accountobjectCurrent contact's account info: More info below
newsletterbooleanContact is suscribed

Account Object
Learn more about accounts from What are Accounts?.

Froged('set', {
        userId: 'userIdInYourSystem',
        email :'userEmail',
        account: {
                accountId: 'accountIdInYourSystem'                
Note: To add attributes to accounts you can use our REST API


With this function you can track user events in the application.

Froged('track', eventName: string, { parameters... });

Note: the event must have been previously defined on app.

In Froged we have a list of predefined events you can use. Visit events section: Events


Froged('track','on_search', { search_term: 'install'});


Open the widget. Depending on the parameter that is passed, it will open a certain route.

// Open the widget on the last route where it was 
// Open the widget on the initialscreen 
Froged('open', 'home');  
// Open the widget in chats inbox
// Open the widget for a newconversation 
// Open the widget in documents 
// Open the widget in updates 

Open a specific conversation

Open the widget and show a specific conversation.


You can add a modal finder in your web like this:

Of course, you have to be active your knowledge base. All you need to do is call this method: 
// Show knowledge base finder
You can also open the finder with a search phrase to give more context to the user
// Show knowledge base finder with a search phrase
Froged('find','search text');
If you want simplify things, you can simplify things by adding froged_finder to the classes of an HTML element. So, when you click on this element, the finder will appear on the screen.
<!-- METHOD 1 -->
<span class="froged_finder">Click here to show finder</span>

<!-- METHOD 2 (using javascript) -->
<span onclick="Froged('find')">Click here to show finder</span>

Filter documents

You can select which documents will be shown in your widget - you can set different levels of accessibility. To do this, you will have to tag the documents and folders that you want to be visible and use these same tags in your code snippet.

In this example, only public documents tagged with 'level1' or 'level2' will be visible. If you do not specify a value for Tags, an empty list is set to kbTags which means that all public documents will be visible.
frogedSettings: {

    // Other Froged settings

    kbTags: ['level1', 'level2'],

    // Other Froged settings


For more information on how add different tags to your folders and documents, click on Filter documents by type of user and use case.

Show automessage

Show a specific automessage. You must create this automessage before and then you can call it from Froged SDK

// An automessage will be showed to the contact / visitor 
Froged('automessage', automessageId);

Show flow
Show a specific flow. You must create this flow before and then you can call it from Froged SDK
// A flow will be showed to the contact / visitor 
Froged('flow', flowId);

Send message

Sometimes you need to send your support agent a message on behalf of your website user on some custom user action. This method is right for it
// The widget will be opened and a message will be automatically  
// sent on behalf of the user of your website 
Froged('message', "text_message");

You may be interested in relating a conversation to an order, a ticket, or tracking code,... so that all communications regarding it are in the same conversation. For that, you just have to use ticket.

When calling this method, it will search for a conversation that is associated with that ticket_id and if it does not find it, it will create a new one using the starting message that you send.

Different contacts can't share the same ticket_id.
Froged('ticket', 'ticket_id', 'Starting message');

Show document

Show a document in full modal view.

// A modal will be opened with the document 
// that we want to show our visitor
Froged('doc', documentId);
There are a few important points to keep in mind. First, the documentId should be obtained from the last part of the URL, specifically the numbers following the last "/". This ensures that you are referencing the correct document for display.
Additionally, it's crucial to note that the article you want to show must be set to public in order for it to be accessible through the SDK.
The "Show document" command automatically detects the language preferences of the user's browser. This means that the article will be displayed in the language that corresponds to the user's browser settings


Close the widget



It allows you to know the status (open / closed) of the widget

Froged('opened');  // Return true or false


Switches the widget



By default, our widget will always start. Froged has features to manage the GDPR. You can activate these features in the widget settings.

  • Request cookie & tracking permission
    If this option is active, a message will be displayed asking visitors if they want to be tracked. The chat widget will also be displayed.
    • If visitors click on the Accept cookies button, they will not be asked again
    • If visitors click on the Decline cookies button, the chat widget will be hidden and they will not be asked again
  • Use a customized "allow cookies" button
    This setting allows you to customize your "allow cookies" user interface. So, if it is active, the chat widget will be displayed but visitors will not be asked. It will be you who has to show them that message. In this case, your users will still have two options: accept or decline cookies. So, we offer a method for each one:
// ---------------------------------------------------------------
// These two methods work the same as in the 
// option "Request cookie & tracking permission"
// ---------------------------------------------------------------

// Visitor accepts cookies

// Visitor declines cookies


With this you can execute code when something specific happens in the SDK

// It is executed when the bubble connects to the server.
Froged('hook', 'onConnect', (auth: { sessionId, email, userId, verified }) => {
    // Right at this point the value of froged.connected is true
    console.log("SDK connected");
    // The callback offers information about session (id, email, userId, verified)
    console.log({ auth });

// It is executed when session info changes (for example, a user logins)
Froged('hook', 'onAuth', (auth: { sessionId, email, userId, verified }) => {
    // You can get session info updated
    console.log({ auth });

// It is executed when the bubble disconnects from server.
Froged('hook', 'onDisconnect', () => {
   // Right at this point the value of froged.connected is false
   console.log("SDK disconnected");

// It is executed when the bubble is opened
Froged('hook', 'onOpen', () => {
   console.log("The visitor has opened the bubble");

// It is executed when the bubble is closed
Froged('hook', 'onClose', () => {
   console.log("The user has closed the bubble");

// Change inbox status. It is used to know if the visitor has unread messages
Froged('hook', 'onInboxStatusUpdate', (unreadMessagesCount: number) => {
   if (unreadMessagesCount === 0)
      console.log("No messages. Remove badge");
     console.log("There are messages. Show badge");

// Unread conversations list callback. In order to make it works,
// you need to call Froged('listen') previously
Froged('hook', 'onInboxUpdate', (unreadConversations: []) => {

// It is executed when an automessage is triggered and before
// determine if it must be showed. You can use this callback in order
// to avoid showing automessages and not being these accounted in the metrics
Froged('hook', 'onAutomessageRequest', (idAutomessage) => {
   // Your staff here

   // You can customize actions. We provide:
   //   - idAutomessage: the automessage id

   // If return false, no actions (avoid automessage)
   // If return true, automessage will be processed


// It is executed just before an automessage is showed. You can
// avoid it returning false but it is already counted on metrics
Froged('hook', 'onAutomessageOpen', (idAutomessage) => {
   // Your staff here

   // You can customize actions and avoid the automessage. We provide:
   //   - idAutomessage: the automessage id

   // If return false, no actions (avoid automessage showing)
   // If return true, the automessage will be showed


// It is executed when the user click on a link in an automessage
Froged('hook', 'onAutomessageClick', (idAutomessage, uuid, href, name, target) => {
   // Your staff here

   // You can customize actions and avoid default navigation. We provide:
   //   - idAutomessage: the automessage id
   //   - uuid: unique id for this automessageClick event
   //   - href: url to redirect
   //   - name: html element name
   //   - target: link target

   // If return false, no actions (avoid default navigation)
   // If return true, open URL

Was this article helpful?
FROGED Help Center | 2024