Skip to main content
Follow these steps to go from a brand-new account to your first NPC conversation.

​
In-app setup

1

Create a game

Sign in at app.npcbuilder.com and click Add new projectquickstart-1Then access the game and copy the generated GAME_IDquickstart-2
2

Add a world

Inside the game, click Add World; fill name and lore.
Copy the WORLD_ID.
3

Add region & location

Open your world → Add Region(e.g. “Northern Kingdom”) →
inside that region, Add Location(e.g. “Capital City”).
4

Create a character

In the location, click Add Character→ fill name, description, role, traits, etc.
Save; note the character_idquickstart-5to use in the API.
5

Chat in dashboard

On the character page, open the Chattab and send a test message—confirm the NPC responds.

​
Generate credentials

1

Bearer token (quick)

Go to the developers section under graphics engine integration and generate Bearer Tokenquickstart-auth-1Use in header:
Authorization: Bearer YOUR_TOKEN
2

API keys (production)

Still in Developers, you can create an API Key.quickstart-auth-2
Generated API Key secret must be stored securely. If you lose it, you must delete it and generate a new one. We can’t recover API Key secrets
Use in headers with combination of clientId and clientSecret (the generated api key):quickstart-auth-3
{
  "clientId": "API_KEY_ID",
  "clientSecret": "API_KEY_SECRET"
}

​
Call the Interactions API

curl -X POST https://app.npcbuilder.com/api/interactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "CHARACTER_ID",
    "game_id": "GAME_ID",
    "world_id": "WORLD_ID",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

​
Expected JSON

{
  "response": "Greetings, traveler!",
  "user_events": [],
  "character_events": []
}
Include previous user + NPC messages in messages[] on each call to keep context.
Unity and Unreal plugins wrap these calls—see Unity or Unreal guides.