Skip to main content
The behaviors array in BatchConfig accepts two types of entries — preset reference strings and full BehaviorDef objects — and you can mix both freely.

​
Listing available presets

Call GET /api/velma-2-batch/list-presets or GET /api/velma-2-streaming/list-presets to retrieve the behavior preset catalog. Both endpoints require the X-API-Key header and return the same response format. 
curl https://modulate-developer-apis.com/api/velma-2-batch/list-presets \
  -H "X-API-Key: $MODULATE_API_KEY"

{
  "presets": [
    {
      "identifier": "service-churn",
      "name": "Service Churn",
      "short_description": "Customer decides to cancel an ongoing service.",
      "detailed_description": "To qualify, the speech must fit the following criteria: The speech must feature assertions that the speaker would like to cancel a service or subscription. The speech must not be phrased as a threat in the first or second person voice."
    },
    {
      "identifier": "harassment",
      "name": "Harassment",
      "short_description": "Targeted, repeated hostile behavior toward a participant.",
      "detailed_description": "..."
    }
  ]
}
The identifier is what you use in a preset reference string. The detailed_description is the exact detection language Velma applies when you reference a preset — use it as a starting point when adapting a preset into a custom behavior.

​
Using preset references

Include a preset by adding a "preset:<identifier>" string to the behaviors array. Velma expands it into the full behavior definition before processing. 
websocat "wss://modulate-developer-apis.com/api/velma-2-streaming?api_key=$MODULATE_API_KEY" \
  --text - <<'EOF'
{"behaviors":["preset:harassment","preset:service-churn","preset:account-impersonation"]}
EOF

​
Including BehaviorDef objects directly

Put full BehaviorDef objects in the behaviors array for precise control. All four required fields must be present. To define a custom behavior: supply all four fields with a UUID you generate. See Custom behaviors. 
websocat "wss://modulate-developer-apis.com/api/velma-2-streaming?api_key=$MODULATE_API_KEY" \
  --text - <<'EOF'
{
  "behaviors": [
    {
      "behavior_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Service Churn",
      "short_description": "Customer decides to cancel an ongoing service.",
      "detailed_description": "To qualify, the speech must fit the following criteria: The speech must feature assertions that the speaker would like to cancel a service or subscription. The speech must not be phrased as a threat in the first or second person voice."
    }
  ]
}
EOF

​
Mixing presets and custom behaviors

Preset references and BehaviorDef objects can coexist in the same behaviors array. If a custom BehaviorDef shares a UUID with a preset entry, the custom definition takes precedence. 
{
  "behaviors": [
    "preset:harassment",
    {
      "behavior_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Service Churn",
      "short_description": "Customer decides to cancel an ongoing service.",
      "detailed_description": "To qualify, the speech must feature assertions that the speaker would like to cancel a service or subscription. The speech must not be phrased as a threat in the first or second person voice."
    }
  ]
}

​
Behavior fields reference

FieldTypeRequired
behavior_uuidUUID stringYes
namestring (min 1 char)Yes
short_descriptionstringYes
detailed_descriptionstringYes
applies_to_conversation_type_uuidsUUID array or nullNo
applies_to_participant_role_uuidsUUID array or nullNo