molroomolroo
API Reference

Proactive

Check for and manage character-initiated actions.

Proactive

Proactive actions are character-initiated behaviors that occur without user input. The emotion engine can trigger actions based on attachment needs, unmet psychological needs, or emotional overflow. This enables characters that reach out on their own rather than only responding to the user.

Proactive behavior is disabled by default. You must explicitly opt in per session.

Check Proactive Actions

GET /v1/proactive/:sessionId

Check for pending proactive actions in a session. Returns an array of actions the character wants to initiate based on its current emotional and psychological state.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer YOUR_API_KEY

Path Parameters

ParameterTypeDescription
sessionIdstringThe session ID to check

Response

Returns an array of proactive action objects:

FieldTypeDescription
idstringUnique action identifier
typestringAction type (see below)
messagestringSuggested message or action description
prioritystringPriority level: "low", "medium", or "high"
metadataobjectAdditional context about what triggered the action

Action Types

TypeDescription
attachment_seekingCharacter seeks connection due to absence or attachment needs
need_deficitA psychological need (belonging, competence, autonomy) is unmet
emotional_overflowEmotion intensity has exceeded the character's coping threshold

Examples

curl

curl https://api.molroo.io/v1/proactive/session_xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://api.molroo.io/v1/proactive/session_xyz",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
 
const actions = await response.json();
 
actions.forEach((action) => {
  console.log(`[${action.priority}] ${action.type}: ${action.message}`);
});
 
// [medium] attachment_seeking: "Hey, I've been thinking about our last conversation..."
// [low] need_deficit: "I'd love to try something creative together"

Python

import requests
 
response = requests.get(
    "https://api.molroo.io/v1/proactive/session_xyz",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
 
actions = response.json()
 
for action in actions:
    print(f"[{action['priority']}] {action['type']}: {action['message']}")

Errors

CodeStatusDescription
UNAUTHORIZED401Invalid or missing API key
NOT_FOUND404Session not found

Configure Proactive Preferences

PUT /v1/proactive/:sessionId/preferences

Enable or disable proactive behavior and configure which trigger types are active for a session. By default, all proactive behavior is disabled.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer YOUR_API_KEY
Content-TypestringYesapplication/json

Path Parameters

ParameterTypeDescription
sessionIdstringThe session ID to configure

Request Body

FieldTypeRequiredDescription
enabledbooleanYesMaster switch for proactive behavior
triggersobjectNoPer-trigger-type toggles
triggers.attachment_seekingbooleanNoEnable attachment-seeking actions (default: true when enabled)
triggers.need_deficitbooleanNoEnable need-deficit actions (default: true when enabled)
triggers.emotional_overflowbooleanNoEnable emotional overflow actions (default: true when enabled)
cooldown_hoursnumberNoMinimum hours between proactive actions (default: 4)

Response

FieldTypeDescription
sessionIdstringThe session ID
preferencesobjectThe updated preferences object

Examples

curl

Enable proactive behavior with only attachment-seeking and emotional overflow triggers:

curl -X PUT https://api.molroo.io/v1/proactive/session_xyz/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "triggers": {
      "attachment_seeking": true,
      "need_deficit": false,
      "emotional_overflow": true
    },
    "cooldown_hours": 6
  }'

JavaScript

const response = await fetch(
  "https://api.molroo.io/v1/proactive/session_xyz/preferences",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      enabled: true,
      triggers: {
        attachment_seeking: true,
        need_deficit: false,
        emotional_overflow: true,
      },
      cooldown_hours: 6,
    }),
  }
);
 
const result = await response.json();
console.log(result.preferences);
// { enabled: true, triggers: { attachment_seeking: true, need_deficit: false, emotional_overflow: true }, cooldown_hours: 6 }

Python

import requests
 
response = requests.put(
    "https://api.molroo.io/v1/proactive/session_xyz/preferences",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "enabled": True,
        "triggers": {
            "attachment_seeking": True,
            "need_deficit": False,
            "emotional_overflow": True,
        },
        "cooldown_hours": 6,
    },
)
 
result = response.json()
print(result["preferences"])

Errors

CodeStatusDescription
UNAUTHORIZED401Invalid or missing API key
VALIDATION_ERROR400Invalid preferences configuration
NOT_FOUND404Session not found
RATE_LIMIT429Too many requests

Previous

Presets

Next

Relationship

On this page