API

Capabilities configuration

const capabilities = new Capabilities({ emotions: true });

Name	Description	Default value
audio	If false, then the client will not receive spoken audio from the characters (text only mode).	true
emotions	You will receive character emotions.	false

Connection configuration

const connection = {
  disconnectTimeout: 10 * 1000, // time in milliseconds
  autoReconnect: false, // true by default
}

Name	Description	Default value
disconnectTimeout	Close connection due to inactivity	60000
autoReconnect	Connection will be opened automatically on send if it is closed. Otherwise, an existing open connection will be used. Our server closes the connection automatically after 1 minute of inactivity.	true

SessionToken

const token = client.generateSessionToken();

// Get a token.
token.getToken();

// Get type (Bearer).
token.getType();

// Get expiration time.
// Token should be regenerated after expiration time.
token.getExpirationTime();

// Get session id.
token.getSessionId();

InworldClient with API key

If you prefer to use automatic session management set client key/secret.

const client = new InworldClient();

// ApiKey is required.
client.setApiKey({ key, secret });

// User is not required.
client.setUser(user);

// Configuration is not required.
client.setConfiguration({
  capabilities,
  connection: {
    disconnectTimeout: 10 * 1000, // time in milliseconds
    autoReconnect: false,
  }
});

// Scene is not required for token generation.
// But if you would like to speak with scene characters you need to provide scene full name.
// It should be like workspaces/{WORKSPACE_NAME}/characters/{CHARACTER_NAME}.
// Or like workspaces/{WORKSPACE_NAME}/scenes/{SCENE_NAME}.
client.setScene(scene);

// Event handlers
client.setOnDisconnect(fn);
client.setOnError(fn);
client.setOnMessage(fn);

// Generate SessionAccessToken.
client.generateSessionToken();

// Finish connection configuration.
// Return instance of EventService.
// Сonnection is not open. It's just ready to open on message send.
const connection = client.build();

InworldClient with token

If you prefer to manage a session manually you should provide a generateSessionToken function instead of setting the client key/secret. This will allow you to store sessionId externally(for example, in redis) and reuse a session on application restart. See the discord_bot example for more details.

const key = 'character_key';

async function generateSessionToken() {
  const client = new InworldClient()
    .setApiKey({
      key: process.env.INWORLD_KEY,
      secret: process.env.INWORLD_SECRET,
    });
  const token = await client.generateSessionToken();

  const sessionId = await redisClient.get(key);
  const actualToken = new SessionToken({
    expirationTime: token.getExpirationTime(),
    token: token.getToken(),
    type: token.getType(),
    sessionId: sessionId ?? token.getSessionId(),
  });

  if (!sessionId) {
    redisClient.set(key, actualToken.getSessionId());
  }

  return actualToken;
}

const client = new InworldClient();

// User is not required.
client.setUser(user);

// Configuration is not required.
client.setConfiguration({
  capabilities,
  connection: {
    disconnectTimeout: 10 * 1000, // time in milliseconds
    autoReconnect: false,
  }
});

// Scene is not required for token generation.
// But if you would like to speak with scene characters you need to provide scene full name.
// It should be like workspaces/{WORKSPACE_NAME}/characters/{CHARACTER_NAME}.
// Or like workspaces/{WORKSPACE_NAME}/scenes/{SCENE_NAME}.
client.setScene(scene);

// Event handlers
client.setOnDisconnect(fn);
client.setOnError(fn);
client.setOnMessage(fn);

// Generate SessionAccessToken.
// It will be called only if currect token is empty or expired.
client.setGenerateSessionToken(generateSessionToken);

// Finish connection configuration.
// Return instance of EventService.
// Сonnection is not open. It's just ready to open on message send.
const connection = client.build();

Character

const character = connection.getCurrentCharacter();

// Character id.
character.getId();

// Character resource name.
character.getResourceName();

// Character display name.
character.getDisplayName();

InworldPacket

client.setOnMessage((packet: InworldPacket) => {...});

// ISO string.
packet.date

// It's a text event.
packet.isText()

// Get message of text event.
packet.text.text
packet.text.final

// Get emotions.
packet.emotion.joy
packet.emotion.fear
packet.emotion.trust
packet.emotion.surprise

// Get behavior affected by emotions.
packet.emotion.behavior.isNeutral()
packet.emotion.behavior.isDisgust()
packet.emotion.behavior.isContempt()
packet.emotion.behavior.isBelligerence()
packet.emotion.behavior.isDomineering()
packet.emotion.behavior.isCriticism()
packet.emotion.behavior.isAnger()
packet.emotion.behavior.isAnger()
packet.emotion.behavior.isTension()
packet.emotion.behavior.isTenseHumor()
packet.emotion.behavior.isDefensiveness()
packet.emotion.behavior.isWhining()
packet.emotion.behavior.isSadness()
packet.emotion.behavior.isStonewalling()
packet.emotion.behavior.isInterest()
packet.emotion.behavior.isValidation()
packet.emotion.behavior.isAffection()
packet.emotion.behavior.isHumor()
packet.emotion.behavior.isSurprise()
packet.emotion.behavior.isJoy()

// Get strength of the emotion.
packet.emotion.strength.isWeak()
packet.emotion.strength.isStrong()

// It's an audio event.
packet.isAudio()

// Get chunck of audio event.
packet.audio.chunk

// It's a trigger event.
packet.isTrigger()

// It's an emotion event.
packet.isEmotion()

// It's a control event.
packet.isControl()

// It's a special control event. It means that interaction ends.
packet.isInteractionEnd();

Error handling

import {
  status,
} from '@inworld/nodejs-sdk';

handleError(err: ServiceError) {
    switch (err.code) {
        // Cancelled by server due timeout inactivity.
        case status.ABORTED:
        // Cancelled by client.
        case status.CANCELLED:
            break;
        default:
            console.error(err);
            break;
    }
};

You can read more about possible GRPC status codes here.

Environment

Use these environment variables for local debugging of the package.

Name	Description	Default value
NODE_SDK_INWORLD_STUDIO_HOST	Studio endpoint	api-studio.inworld.ai:443
NODE_SDK_INWORLD_STUDIO_SSL	Define if Studio connection uses TLS	true
NODE_SDK_INWORLD_ENGINE_HOST	API endpoint	api-engine.inworld.ai:443
NODE_SDK_INWORLD_ENGINE_SSL	Define if Engine connection uses TLS	true