Skip to main content
A behavior is a detection target — a named signal you want Velma to look for in a conversation. You include behaviors in your BatchConfig before streaming audio, and Velma emits a behavior_detection event for each one with a verdict, a confidence score, and the clips that served as evidence. Behaviors are the primary mechanism for customizing what Velma pays attention to. The same underlying audio can be evaluated against a compliance checklist, a safety policy, a sales coaching rubric, or any other set of criteria — it all depends on the behaviors you define.

​
Two ways to use behaviors

Use a pre-built behavior. Modulate maintains a catalog of behaviors covering common use cases across customer support, sales, content moderation, media monitoring, and more. Call GET /api/velma-2-batch/list-presets or GET /api/velma-2-streaming/list-presets to retrieve the catalog. Each entry includes an identifier you reference with the "preset:<identifier>" syntax in your behaviors array. Define a custom behavior. Supply your own BehaviorDef with a name and description you write. Velma evaluates whatever criteria you specify. You can start from scratch or adapt a pre-built definition as a template. Both paths use the same BehaviorDef object in your BatchConfig. The difference is whether the UUID and descriptions come from the preset catalog or from you.

​
The BehaviorDef schema

Every behavior in your BatchConfig.behaviors array must include all four required fields:
FieldTypeRequiredDescription
behavior_uuidUUID stringYesUniquely identifies this behavior. For pre-built behaviors, use the UUID from the list-presets response. For custom behaviors, supply a UUID v4 you generate.
namestringYesA short label. Used in behavior_detection event responses to identify which behavior fired.
short_descriptionstringYesOne sentence summarizing what the behavior detects.
detailed_descriptionstringYesThe criteria Velma uses to determine whether the behavior is present. This is the most important field — see Best practices.
applies_to_conversation_type_uuidsUUID arrayNoRestrict this behavior to specific conversation types. Null or omitted means all types.
applies_to_participant_role_uuidsUUID arrayNoRestrict this behavior to specific participant roles. Null or omitted means all roles.

​
What Velma returns

Each behavior produces a behavior_detection event: 
{
  "type": "behavior_detection",
  "detection": {
    "behavior_uuid": "33333333-3333-4333-8333-033333333006",
    "behavior_name": "Service Churn",
    "speaker_label": "Speaker_1",
    "detected": true,
    "confidence": 0.91,
    "evidence_clip_uuids": ["a1b2c3d4-...", "e5f6a7b8-..."],
    "definitive_clip_uuid": "a1b2c3d4-...",
    "reasoning": "Speaker explicitly stated they want to cancel their subscription.",
    "skipped": false,
    "skip_reason": null,
    "error_reason": null
  }
}
detected is the primary verdict. evidence_clip_uuids links the detection back to the specific clips in the session. skipped: true means Velma did not attempt detection — typically because the conversation context was insufficient for this behavior. error_reason is non-null if detection failed.

​
A minimal example

Using a preset reference — the simplest path: 
{
  "behaviors": ["preset:service-churn"]
}
Or with a full BehaviorDef for custom or adapted language: 
{
  "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 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."
    }
  ]
}

​
Next steps

Using behaviors

How to retrieve the preset catalog and include behaviors in your requests.

Custom behaviors

Define your own behaviors from scratch or adapted from pre-built ones.

Best practices

Write descriptions that produce consistent, accurate detections.