Official Hellotext JavaScript library.
This library allows you the following,
- Track events happening on your site to Hellotext in real-time.
- Use Hellotext Forms to dynamically collect data from your customers based on your specific business requirements.
npm i @hellotext/hellotextyarn add @hellotext/hellotextImport the library into your app.
import Hellotext from '@hellotext/hellotext'If you're running in a non-browser environment, such as Node.js, you can import the vanilla implementation which only includes Hellotext.js class without initializing other libraries that rely on the browser environment.
import Hellotext from '@hellotext/hellotext/vanilla'Initialize the library passing the public HELLOTEXT_BUSINESS_ID identifier that represents the business.
You can find it from the business's settings page.
Hellotext.initialize('HELLOTEXT_BUSINESS_ID')Failing to initialize the class before calling any other method will throw a NotInitializedError.
Learn how to leverage the library to track events and collect forms.
This library emits events that you can listen to and perform specific action when the event happens.
Think of it like addEventListener for HTML elements. You can listen for events, and remove events as well.
To listen to an event, you can call the on method, like so
Hellotext.on(eventName, callback)To remove an event listener, you can call removeEventListener
Hellotext.removeEventListener(eventName, callback)session-set: This event is fired when the session value forHellotext.sessionis set. Either through an API request, or if the session was found in the cookie.forms:collectedThis event is fired when forms are collected. The callback will receive the array of forms collected.form:completedThis event is fired when a form has been completed. A form is completed when the user fills all required inputs and verifies their OTP(One-Time Password). The callback will receive the form object that was completed, alongside the data the user filled in the form.
The library looks for a session identifier present on the hellotext_session query parameter. If the session is not present as a cookie neither it will create a new random session identifier, you can disable this default behaviour via the configuration, see Configuration Options for more information.
The session is automatically sent to Hellotext any time the Hellotext.track method is called.
Short links redirections attaches a session identifier to the destination url as hellotext_session query parameter. This will identify all the events back to the customer who opened the link.
It is possible to obtain the current session by simply calling Hellotext.session.
await Hellotext.session
// Returns bBJn9vR15yPaYkWmR2QK0jopMeNxrA6lIf the session has not been set yet, the result returned will be undefined.
You can check whether the session has been set or not by calling Hellotext.isInitialized.
if (Hellotext.isInitialized) {
console.log('session is present')
} else {
console.log('session has not been set')
}Moreover, you can hook in and listen for the session being set, such that when it's set, you're notified about the change, like so
Hellotext.on('session-set', session => {
console.log('session is: ', session)
})You may want to store the session on your backend when customers are unidentified so you can later attach it to a profile when it becomes known.
When initializing the library, you may pass an optional configuration object as the second argument.
Hellotext.initialize('HELLOTEXT_BUSINESS_ID', configurationOptions)| Property | Description | Type | Default |
|---|---|---|---|
| session | A valid Hellotext session which was stored previously. When not set, Hellotext attempts to retrieve the stored value from document.cookie when available, otherwise it creates a new session. |
String | null |
| autoGenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true |
| autoMountForms | Whether the library should automatically mount forms collected or not | Boolean | true |