RATIO MACHINA STARTER logo

MERCURY

Conversation Monitoring REST API

The Conversation Monitoring REST API provides endpoints for creating and managing persona monitors, which continuously analyze conversations for quality, compliance, sentiment, and escalation triggers.

Base URL & Authentication

Base URL: https://your-api-name.mercury.ratiomachina.com
Authentication: x-mercury-api-key: YOUR_API_KEY

Persona Monitors

🔍 Persona Monitors: Define automated surveillance rules that continuously analyze conversations involving specific personas, detecting patterns, quality issues, or trigger conditions that require attention.

List All Persona Monitors

GET/persona-monitors

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • personaId - Filter by specific persona
  • monitorType - Filter by monitor type
  • active - Filter by active status

Response Example

{
  "personaMonitors": [
    {
      "id": "uuid-monitor-123",
      "personaId": "uuid-persona-456",
      "name": "Sales Sentiment Monitor",
      "monitorType": "sentiment_analysis",
      "isActive": true,
      "thresholds": {
        "negativeSentiment": 0.7,
        "alertAfterCount": 3
      },
      "alertMethods": ["email", "webhook"],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0
  }
}

Create Persona Monitor

POST/persona-monitors

Request Body

{
  "personaId": "uuid-persona-456",
  "name": "Customer Support Quality Monitor",
  "description": "Monitor customer satisfaction and escalation triggers",
  "monitorType": "sentiment_analysis",
  "configuration": {
    "sentimentThresholds": {
      "negative": 0.7,
      "positive": 0.3
    },
    "windowSize": 10,
    "alertConditions": {
      "consecutiveNegative": 3,
      "averageNegativeWindow": 0.6
    }
  },
  "alertMethods": [
    {
      "type": "email",
      "recipients": ["manager@company.com"]
    },
    {
      "type": "webhook",
      "url": "https://your-app.com/webhook/alert",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  ],
  "schedule": {
    "enabled": true,
    "frequency": "real_time"
  }
}

Response Example

{
  "personaMonitor": {
    "id": "uuid-monitor-789",
    "personaId": "uuid-persona-456",
    "name": "Customer Support Quality Monitor",
    "description": "Monitor customer satisfaction and escalation triggers",
    "monitorType": "sentiment_analysis",
    "configuration": {
      "sentimentThresholds": {
        "negative": 0.7,
        "positive": 0.3
      },
      "windowSize": 10,
      "alertConditions": {
        "consecutiveNegative": 3,
        "averageNegativeWindow": 0.6
      }
    },
    "alertMethods": [
      {
        "type": "email",
        "recipients": ["manager@company.com"]
      },
      {
        "type": "webhook",
        "url": "https://your-app.com/webhook/alert"
      }
    ],
    "schedule": {
      "enabled": true,
      "frequency": "real_time"
    },
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Get Persona Monitor by ID

GET/persona-monitors/{id}

Path Parameters

  • id - Persona Monitor UUID

Query Parameters

  • includeJobs - Include recent monitoring jobs
  • includeStats - Include execution statistics

Response Example

{
  "personaMonitor": {
    "id": "uuid-monitor-789",
    "personaId": "uuid-persona-456",
    "name": "Customer Support Quality Monitor",
    "monitorType": "sentiment_analysis",
    "configuration": { ... },
    "alertMethods": [ ... ],
    "isActive": true,
    "stats": {
      "totalJobs": 1247,
      "alertsTriggered": 23,
      "lastExecution": "2024-01-15T14:30:00Z",
      "averageExecutionTime": 1.2
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Update Persona Monitor

PUT/persona-monitors/{id}

Updates persona monitor configuration. Only provided fields will be updated (partial updates supported).

Request Body

{
  "name": "Enhanced Support Quality Monitor",
  "configuration": {
    "sentimentThresholds": {
      "negative": 0.6,
      "positive": 0.4
    },
    "alertConditions": {
      "consecutiveNegative": 2
    }
  },
  "isActive": true
}

Response Example

{
  "personaMonitor": {
    "id": "uuid-monitor-789",
    "name": "Enhanced Support Quality Monitor",
    "configuration": {
      "sentimentThresholds": {
        "negative": 0.6,
        "positive": 0.4
      },
      "alertConditions": {
        "consecutiveNegative": 2,
        "averageNegativeWindow": 0.6
      }
    },
    "isActive": true,
    "updatedAt": "2024-01-15T11:30:00Z"
  }
}

Delete Persona Monitor

DELETE/persona-monitors/{id}

⚠️ Warning: Deleting a persona monitor will permanently remove it and all associated job history. Active monitoring for the persona will stop immediately.

Path Parameters

  • id - Persona Monitor UUID

Response Example

{
  "message": "Persona monitor deleted successfully",
  "deletedMonitor": {
    "id": "uuid-monitor-789",
    "name": "Customer Support Quality Monitor",
    "personaId": "uuid-persona-456"
  }
}

Persona Monitor Jobs

⚙️ Monitor Jobs: Individual execution instances of persona monitors that analyze specific conversations or batches of conversations, producing alerts and insights based on the monitor's configuration.

List Jobs for Monitor

GET/persona-monitors/{id}/jobs

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • status - Filter by job status
  • from - Jobs created after date
  • to - Jobs created before date
  • alertsTriggered - Jobs that triggered alerts

Response Example

{
  "monitorJobs": [
    {
      "id": "uuid-job-123",
      "personaMonitorId": "uuid-monitor-789",
      "conversationId": "uuid-conv-456",
      "status": "completed",
      "results": {
        "sentiment": {
          "overall": "negative",
          "confidence": 0.82,
          "score": -0.7
        },
        "alertsTriggered": [
          {
            "type": "negative_sentiment_threshold",
            "severity": "medium",
            "message": "Negative sentiment exceeded threshold",
            "timestamp": "2024-01-15T10:35:22Z"
          }
        ]
      },
      "executionTime": 1.4,
      "createdAt": "2024-01-15T10:35:00Z",
      "completedAt": "2024-01-15T10:35:01Z"
    }
  ],
  "pagination": {
    "total": 1247,
    "limit": 50,
    "offset": 0
  }
}

Create Monitor Job

POST/persona-monitors/{id}/jobs

Manually trigger a monitoring job for specific conversations or conversation batches. This is useful for on-demand analysis or testing monitor configurations.

Request Body

{
  "target": {
    "type": "conversation_id",
    "conversationId": "uuid-conv-456"
  },
  "options": {
    "includeHistory": true,
    "historyLimit": 50,
    "priority": "high"
  },
  "notifications": {
    "onCompletion": true,
    "onAlert": true
  }
}

Batch Analysis

{
  "target": {
    "type": "batch",
    "criteria": {
      "personaId": "uuid-persona-456",
      "dateRange": {
        "from": "2024-01-14T00:00:00Z",
        "to": "2024-01-15T00:00:00Z"
      },
      "channel": "email"
    }
  },
  "options": {
    "batchSize": 100,
    "priority": "normal"
  }
}

Response Example

{
  "monitorJob": {
    "id": "uuid-job-987",
    "personaMonitorId": "uuid-monitor-789",
    "target": {
      "type": "conversation_id",
      "conversationId": "uuid-conv-456"
    },
    "status": "queued",
    "options": {
      "includeHistory": true,
      "historyLimit": 50,
      "priority": "high"
    },
    "estimatedCompletion": "2024-01-15T10:36:00Z",
    "createdAt": "2024-01-15T10:35:30Z"
  }
}

Job Status Values

  • queued - Job is waiting to be processed
  • running - Job is currently executing
  • completed - Job completed successfully
  • failed - Job failed with errors
  • cancelled - Job was cancelled

Monitor Type Examples

Sentiment Analysis Monitor

Configuration Example

{
  "monitorType": "sentiment_analysis",
  "configuration": {
    "thresholds": {
      "negative": 0.7,
      "positive": 0.8,
      "neutral_range": [0.3, 0.7]
    },
    "alertConditions": {
      "consecutiveNegative": 3,
      "slidingWindowAverage": {
        "windowSize": 10,
        "threshold": 0.6
      }
    },
    "analysisOptions": {
      "includeIntensity": true,
      "detectSarcasm": true,
      "contextWindow": 5
    }
  }
}

Use Cases

  • Customer satisfaction monitoring
  • Support quality assurance
  • Sales conversation effectiveness
  • Escalation trigger detection
  • Brand sentiment tracking

Alert Example

{
  "type": "negative_sentiment_trend",
  "severity": "high",
  "message": "3 consecutive negative responses detected",
  "details": {
    "averageSentiment": -0.8,
    "conversationId": "uuid-conv-123",
    "messageCount": 3
  }
}

String Analysis Monitor

Configuration Example

{
  "monitorType": "string_analysis",
  "configuration": {
    "keywords": [
      {
        "phrase": "cancel subscription",
        "caseSensitive": false,
        "wholeWord": false,
        "severity": "high"
      },
      {
        "phrase": "speak to manager",
        "caseSensitive": false,
        "wholeWord": true,
        "severity": "medium"
      }
    ],
    "patterns": [
      {
        "regex": "\\b(refund|money back)\\b",
        "description": "Refund requests",
        "severity": "medium"
      }
    ],
    "alertConditions": {
      "immediateAlert": ["cancel subscription"],
      "threshold": {
        "count": 2,
        "timeWindow": "1h"
      }
    }
  }
}

Use Cases

  • Cancellation intent detection
  • Compliance monitoring
  • Escalation keyword tracking
  • Product interest identification
  • Privacy concern detection

Alert Example

{
  "type": "keyword_detected",
  "severity": "high",
  "message": "Cancellation intent detected",
  "details": {
    "keyword": "cancel subscription",
    "messageContent": "I want to cancel my subscription",
    "conversationId": "uuid-conv-123",
    "position": 15
  }
}

Support Escalation Monitor

Configuration Example

{
  "monitorType": "support_escalation",
  "configuration": {
    "escalationTriggers": {
      "conversationLength": {
        "messageCount": 15,
        "timeSpan": "30m"
      },
      "repeatConcerns": {
        "threshold": 3,
        "similarity": 0.8
      },
      "complexityKeywords": [
        "technical issue",
        "not working",
        "bug",
        "error"
      ]
    },
    "skillGapDetection": {
      "enabled": true,
      "confidenceThreshold": 0.5
    },
    "priorityRules": [
      {
        "condition": "premium_customer",
        "priority": "high"
      }
    ]
  }
}

Use Cases

  • Complex issue identification
  • Agent skill gap detection
  • Priority customer handling
  • Technical escalation triggers
  • Quality assurance alerts

Alert Example

{
  "type": "escalation_required",
  "severity": "high",
  "message": "Conversation requires human intervention",
  "details": {
    "reason": "complex_technical_issue",
    "conversationLength": 18,
    "customerTier": "premium",
    "suggestedAction": "route_to_senior_support"
  }
}

Monitoring Best Practices

Monitor Configuration

  • Start with conservative thresholds and adjust based on actual data
  • Use different monitor types for comprehensive coverage
  • Test monitor configurations before deploying to production
  • Regularly review and update monitoring rules

Alert Management

  • Set up appropriate escalation chains for different alert types
  • Use multiple notification channels for critical alerts
  • Implement alert fatigue prevention with smart grouping
  • Monitor the monitors - track their performance and accuracy
Monitoring RPC API →Evaluation REST API →
Transcend the hype with MERCURY by Ratio Machina