Node.js SDK

The Node.js SDK provides a straightforward way to ingest events on the server-side.

Installation

Install the SDK from npm:

npm i alignai

yarn add alignai

pnpm add alignai

Initialize the SDK

To start, initialize the SDK using your API key and Project ID:

import { AlignAI } from 'alignai';

const sdk = new AlignAI('PROJECT_ID', 'API_KEY');

Create an Event

Once you initialize the SDK, create events at the pre-defined circumstances as appropriate. Below are events that can be created:

Event: IdentifyUser

Send the IdentifyUserEvent to record detailed user information.

The recommended use cases of this method are:

When a user first signs up for your service.
When a user updates their profile information such as email address or display name.
When OpenSessionEvent is created.
- While the IdentifyUserEvent can be created during sign-up or profile updates, an alternate strategy is to initially avoid the IdentifyUserEvent altogether. Given that the OpenSessionEvent inherently demands a userId, you can solely focus on this event. By doing so, the user's identification process will be managed seamlessly.

The userId is the distinct identifier given to every user in your service. You can employ your existing user ID or create a new one using methods similar to uuid.

On the other hand, userDisplayName is the user's display name shown on the dashboard.

userId (string, required): Unique user ID used internally. This ID will not be displayed on the dashboard. Max 64 chars allowed.
userDisplayName (string): User display name shown on the dashboard. It's advised to use the user's nickname for this purpose. If a nickname isn't available, alternatives like the email address can be used. This field does not have to be unique. Otherwise, it defaults to empty string. Max 64 chars allowed.
userEmail (string): User email address. Max 256 chars allowed.
userIp (string): User IPv4 address. Provide either ip or country code for user location. If both are given, country code overrides ip.
userCountryCode (string): User country code in ISO Alpha-2. Provide either ip or country code for user location. If both are given, country code overrides ip.
userCreateTime (Date): User creation time.
customProperties (Record<string, string>): Custom Properties(Metadata) of user. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import {IdentifyUserEvent} from 'alignai';

const event = new IdentifyUserEvent({
    userId: "USER_ID",
    userDisplayName: "USER_DISPLAY_NAME",
    userEmail: "USER_EMAIL",
    userCountryCode: "ALPHA2_COUNTRY_CODE",
    userIp: "USER_IP",
    userCreateTime: "USER_CREATE_TIME",
});

Event: OpenSession

Send the OpenSessionEvent to record the initiation of a session.

sessionId (string, required): Session ID. Max 64 chars allowed.
userId (string, required): User ID that the session belongs to. Max 64 chars allowed.
assistantId (string): Assistant ID, if any. By default, 'DEFAULT' will be used. Max 64 chars allowed.
customProperties (Record<string, string>): Custom Properties(Metadata) of session. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import {OpenSessionEvent} from 'alignai';

const event = new OpenSessionEvent({
    sessionId: "SESSION_ID",
    userId: "USER_ID",
    assistantId: "ASSISTANT_ID",
});

Event: CreateMessage

Send the CreateMessageEvent method to record an individual message within a session.

sessionId (string, required): Session ID the message belongs to. Max 64 chars allowed.
messageIndex (number, required): Message index used to sort messages in a chronological order within a session. Must be unique within a session and should be a positive integer.
messageRole (string, required): 'user' or 'assistant'.
messageContent (string, required): Content of the message.
customProperties (Record<string, string>): Custom Properties(Metadata) of message. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import {CreateMessageEvent} from 'alignai';

const event = new CreateMessageEvent({
    sessionId: "SESSION_ID",
    messageIndex: 1,
    messageRole: "user",
    messageContent: "MESSAGE_CONTENT",
});

Event: CloseSession

Send the CloseSessionEvent to record the end of a session.

After 30 minutes of inactivity, the session will close automatically.

sessionId (string, required): Session ID. Max 64 chars allowed.

import {CloseSessionEvent} from 'alignai';

const event = new CloseSessionEvent({
    sessionId: "SESSION_ID",
});

Event: CreateMessageFeedback

Send the CreateMessageFeedbackEvent to record the feedback for a message.

sessionId (string, required): Session ID the message belongs to. Max 64 chars allowed.
messageIndex (number, required): Message index used to sort messages in a chronological order within a session. Must be unique within a session and should be a positive integer.
feedbackType (string, required): "thumbs_up" or "thumbs_down".

Event: CreateSessionFeedback

Send the CreateSessionFeedbackEvent to record the feedback for a session.

sessionId (string, required): Session ID the message belongs to. Max 64 chars allowed.
feedbackType (string, required): "thumbs_up" or "thumbs_down".

Send Events

Once you create an event, send it to Align using the collectEvents method.

// You can send a single event
await sdk.collectEvents(event);

// or, you can send multiple events at once
await sdk.collectEvents(event1, event2, event3);

Last modified: 28 February 2025