Skip to content
Sup

sup.chat.npc

The sup.chat.npc property provides access to the NPC functionality in the current chat. NPCs are AI-powered chat participants that can be nudged, whispered to, or prompted for responses.

Example NPC Usage
// Check if NPC is enabled
if (sup.chat.npc.enabled) {
  // Get NPC info
  console.log(`NPC: ${sup.chat.npc.displayName} (@${sup.chat.npc.username})`);
  console.log(`Persona: ${sup.chat.npc.persona}`);


  // Send a nudge to get the NPC's attention
  sup.chat.npc.nudge();


  // Send a private whisper message
  sup.chat.npc.whisper("The user seems confused about the topic");


  // Get a direct response from the NPC
  const response = sup.chat.npc.prompt("What do you think about this topic?");


  // Post a message directly as the NPC (with optional custom username)
  sup.chat.npc.say("Hello from the NPC!", { username: "mr_npc" });


  return response;
}

Properties

sup.chat.npc.enabled

boolean

if (sup.chat.npc.enabled) {
  // NPC functionality is available
}

Returns true if an NPC is enabled and active in this chat, false otherwise.

sup.chat.npc.username

string

const npcUsername = sup.chat.npc.username; // "assistant"

The NPC’s username. Defaults to "npc" if not configured.

sup.chat.npc.displayName

string

const npcName = sup.chat.npc.displayName; // "Chat Assistant"

The NPC’s display name. Falls back to the username if no display name is set.

sup.chat.npc.pfp

SupImage | undefined

const npcAvatar = sup.chat.npc.pfp;
if (npcAvatar) {
  return npcAvatar; // Display the NPC's profile picture
}

The NPC’s profile picture as a SupImage, or undefined if no avatar is set.

sup.chat.npc.persona

string

const npcPersonality = sup.chat.npc.persona;
// "I am a helpful assistant focused on coding and technical discussions"

The NPC’s personality/persona prompt that defines how it behaves and responds.

Methods

sup.chat.npc.nudge()

() → void

function main() {
  if (sup.user.username === "alice") {
    // Nudge the NPC to join the conversation
    sup.chat.npc.nudge();
    return "Called the assistant to help!";
  }
}

Sends a nudge to the NPC, prompting it to participate in the conversation. The NPC will typically respond with a contextually appropriate message.

Important:

  • Executes after the patch has fully completed, allowing the NPC to comment on or respond to the patch output
  • Either nudge() or whisper() can be called once per patch execution, but not both

sup.chat.npc.whisper()

(content: string) → void

function main() {
  if (sup.input.text?.includes("help")) {
    // Send private context to the NPC
    sup.chat.npc.whisper("The user is asking for help with: " + sup.input.text);
    return "I've alerted the assistant about your question.";
  }
}

Sends a private whisper message to the NPC. This message is not visible to other chat participants but provides context for the NPC’s next response.

Parameters:

  • content (string): The whisper message to send to the NPC

Important:

  • Executes after the patch has fully completed, allowing the NPC to comment on or respond to the patch output
  • Either nudge() or whisper() can be called once per patch execution, but not both

sup.chat.npc.prompt()

(userPrompt: string, options?: SupAIPromptOptions) → string | object

function main() {
  if (!sup.chat.npc.enabled) {
    return "No NPC available in this chat";
  }


  // Get a direct response from the NPC
  const analysis = sup.chat.npc.prompt(
    "Analyze this user's coding question and provide suggestions",
    { temperature: 0.7 }
  );


  return analysis;
}

Directly prompts the NPC for a response using its configured persona. This is synchronous and returns the NPC’s response immediately.

Parameters:

  • userPrompt (string): The prompt/question to send to the NPC
  • options (optional): AI prompt options like temperature, schema, etc.

Returns: The NPC’s response as a string, or structured object if using schema

Note: The NPC will respond as its configured persona, and the system prompt includes both the NPC’s display name and personality description.

sup.chat.npc.say()

(firstArg?: string | SupImage | SupAudio | SupVideo, ...args: Array<SupImage | SupAudio | SupVideo | Array<SupImage | SupAudio | SupVideo> | { pfp?: string | SupImage; username?: string }>) → void

function main() {
  if (!sup.chat.npc.enabled) {
    return "No NPC available in this chat";
  }


  // Post a simple text message as the NPC
  sup.chat.npc.say("Hello! I'm here to help.");


  // Post a message with a custom profile picture (URL string)
  sup.chat.npc.say("Check out this update!", {
    pfp: "https://example.com/custom-avatar.png"
  });


  // Post a message with a custom profile picture (SupImage)
  const customAvatar = sup.image("https://example.com/custom-avatar.png");
  sup.chat.npc.say("I'm using a custom avatar!", { pfp: customAvatar });


  // Post a message with a custom username
  sup.chat.npc.say("This message appears from a different username!", {
    username: "custom_bot"
  });


  // Post a message with both custom pfp and username
  sup.chat.npc.say("I'm a completely different character!", {
    pfp: "https://example.com/other-avatar.png",
    username: "other_character"
  });


  // Post a message with attachments
  const image = sup.input.image;
  if (image) {
    sup.chat.npc.say("Here's the image you shared:", image);
  }


  // Post a message with attachments and custom identity
  sup.chat.npc.say("Here's an image from me:", image, {
    pfp: "https://example.com/custom-avatar.png",
    username: "image_bot"
  });
}

Posts a message directly as the NPC without AI processing. This allows you to send messages on behalf of the NPC with full control over the content.

Parameters:

  • firstArg (optional): The message content as a string, or an attachment (SupImage, SupAudio, or SupVideo)
  • ...args (optional): Additional attachments or an options object with:
    • pfp (optional): A custom profile picture for this message. Can be a URL string or a SupImage object. If not provided, uses the NPC’s default avatar.
    • username (optional): A custom username for this message. Allows the NPC to post as a different identity. If not provided, uses the NPC’s default username.

Important:

  • The message is posted immediately without AI processing
  • The custom pfp and username only apply to this specific message; subsequent messages will use the NPC’s defaults unless overridden again
  • At least one argument (text or attachment) must be provided
  • This method executes immediately, unlike nudge() and whisper() which execute after patch completion

Usage Notes

  • NPC functionality must be enabled in the chat for these methods to work
  • nudge() and whisper() execute after patch completion, enabling them to respond to the patch output
  • Either nudge() or whisper() can be called once per patch execution (not both)
  • prompt() can be called multiple times but requires the NPC to be enabled
  • say() executes immediately and allows posting messages directly as the NPC without AI processing
  • The custom pfp and username parameters in say() only apply to that specific message
  • The NPC uses its configured persona to maintain consistent personality across interactions
  • NPCs are great for providing contextual assistance, moderation, or interactive chat experiences

Error Handling

function main() {
  try {
    if (sup.chat.npc.enabled) {
      return sup.chat.npc.prompt("Hello!");
    } else {
      return "NPC is not enabled in this chat";
    }
  } catch (error) {
    return "Error communicating with NPC: " + error.message;
  }
}

Always check sup.chat.npc.enabled before calling NPC methods to avoid errors.