Skip to main content

Node.js RESTful API Proxy

IMPORTANT

We are depreciating NodeJS RESTful API!! Please migrate all your usage to Simple API.

The Inworld Node.js RESTful API is available here.

Description​

This project is a Node.js based RESTful service of Inworld AI streaming SDK. The service allows for creation, management and closure of multiple AI character sessions. The service can handle multiple users as well as multiple servers automatically depending on how the Character session is created. The service can access characters from many scenes contained within a single Inworld Workspace.

Table of Contents​

  1. Requirements
  2. Installation
  3. Running
  4. Documentation
  5. PM2 Server Installation & Setup (Optional)


Requirements​

  • Node v16.15.1+
  • NPM v8.11.0+
  • GIT
  • Inworld.ai Account API Key, API Secret and a default Scene ID

Installation​

Copy and paste the following lines into your terminal and hit enter to install and setup the service.

git clone https://github.com/inworld-ai/node-js-proxy
cd node-js-proxy
npm i
cp .env-sample .env

Open the .env file in an editor and fill in the variables explained below

  1. INWORLD_KEY - Located at Inworld AI under Integrations -> API Keys -> Key. Note: API Keys are unique for each Workspace.
  2. INWORLD_SECRET - Located at Inworld AI under Integrations -> API Keys -> Secret. Note: API Secrets are unique for each Workspace.
  3. INWORLD_SCENE - Located at Inworld AI under Scenes. Click the button to copy the machine readable id. Note: This is a default scene only used for testing upon starting the service.
  4. PORT - The port to use to run the REST service on. Default is 3000. Note: HTTPS for port 443 is currently not implemented.
  5. EMOTIONS - A boolean that sets if emotions are enabled for the sessions. true for on. false for off.


Running​

Development​

This will monitor the code for any changes and automatically restart when a file is saved.

npm run dev

Production​

npm start

Generating Documentation​

If you contribute to this OpenSource project use this to update the code documentation.

npm run docs

Documentation​

  • Route Documentation - Can be found on Postman here
  • Code Documentation - The TSDocs code documentation can be found in this project at docs/index.html

Use the route documentation to open a session and generate a Session ID. Use that Session ID to send a chat message to the character and then get the events to retrieve the response messages. It is important to close the session after the chat has been completed to prevent conflicts and duplicate sessions.

Basic Route Flow:
  1. Session Open - Opens a new chat session with a character
  2. Session Send Chat Message - Sends a chat message to the character
  3. Service Get All Events - Retrieves the response messages from the character
  4. Session Close - End the chat session with the character

Included in this project is a Postman Collection file you can import and test the routes with. The file is located in this project at postman/Inworld RESTful API Routes.postman_collection.json. To change the default server host from http://localhost:3000, select the Inworld RESTful API Routes collection and click on the Variables tab. Update the {{HOST}} variable to reflect a new base url.

Note: The Postman Agent desktop application is needed to call the routes via http://localhost:3000.


PM2 Server Installation & Setup (Optional)​

PM2 can be used to run on a dedicated server in the background as a stable daemon that will restart on crashing and reboot. More documentation on PM2 can be found here

PM2 Terminal Installation Commands​

sudo npm install -g pm2
pm2 startup
pm2 start pm2.sh --name inworld
pm2 save