Eskalationsstufen
Die Eskalationskette eines Teams lesen, bearbeiten und testen: geordnete Stufen, ihre Einstellungen für automatische Eskalation und Wiederholung, die Schedules unter jeder Stufe und ein Probelauf, wer alarmiert würde.
Die Eskalationskette eines Teams ist eine geordnete Liste von Stufen (Tiers). Stufe 1 wird zuerst alarmiert; Bereitschaft in einer Stufe hat, wen die Schedules der Stufe gerade in Schicht haben. Jede Stufe legt fest, ob und wann der Incident zur nächsten Stufe weiterwandert und wie oft die Stufe vorher erneut alarmiert wird. Wiederholungen der ganzen Kette stehen am Team (Team ändern).
Authentifizierung
Basis-IM-Zugriff: eine IM-berechtigte Rolle oder ein organisationsweiter API-Token, und Incident Management für die Organisation aktiviert. Die Kette lesen darf jeder mit diesem Zugriff. Jedes Schreiben braucht die Team-Schreibhürde: Organisationsrolle admin, oder Team-Admin dieses Teams. Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat, also kommt nur ein Token durch, den ein Organisations-Admin erstellt hat.
Stufenfelder
| Feld | Typ | Beschreibung |
|---|---|---|
tierOrder | integer | Position in der Kette, 1 = wird zuerst alarmiert. Änderbar nur über Neu ordnen. |
autoEscalationEnabled | boolean | Ob der Incident automatisch zur nächsten Stufe weiterwandert. Standard true. |
autoEscalationAfterMinutes | integer | Minuten bis zum Weiterwandern, 0 oder mehr. Standard 5. |
autoEscalationStopMode | string | acknowledged oder resolved: der Incident-Zustand, der die Eskalation stoppt. Standard acknowledged. |
autoEscalationSeverities | array | null | Schweregrade, die automatisch eskalieren: eine Teilmenge von critical, warning, minor. null = alle. |
autoEscalationTimeFilters | array | Wochenfenster, in denen die automatische Eskalation greifen darf, bis zu 50, jeweils { from: "HH:mm", until: "HH:mm", days: number[] } mit ISO-Wochentagen (1 = Montag). until darf "24:00" sein. [] = immer. |
repeats | integer | Wie oft diese Stufe vor dem Weiterwandern noch einmal alarmiert wird, 0 oder mehr. Standard 0. |
repeatsAfterMinutes | integer | null | Minuten zwischen diesen Wiederholungen. null = autoEscalationAfterMinutes verwenden. |
repeatsStopMode | string | acknowledged oder resolved: der Incident-Zustand, der die Wiederholungen stoppt. Standard acknowledged. |
Eskalationskette lesen
GET /api/im/teams/:id/escalations
Liefert alle Stufen in Reihenfolge, jede mit ihren Schedules, Rotationsgruppen und Mitgliedern, dazu die Eskalationseinstellungen des Teams.
Beispiel (cURL)
curl -X GET "$BASE_URL/api/im/teams/3/escalations" \
-H "Authorization: Bearer $TOKEN"Antwort (Response)
200 OK
{
"tiers": [
{
"id": 21,
"tierOrder": 1,
"autoEscalationEnabled": true,
"autoEscalationAfterMinutes": 5,
"autoEscalationStopMode": "acknowledged",
"autoEscalationSeverities": null,
"autoEscalationTimeFilters": [],
"repeats": 0,
"repeatsAfterMinutes": null,
"repeatsStopMode": "acknowledged",
"schedules": [
{
"id": 7,
"displayName": "Primary On-Call",
"timezone": "Europe/Berlin",
"effectiveFrom": null,
"effectiveUntil": null,
"weeklySchedules": [],
"rotationMode": "explicit",
"rotationRepeats": "weekly",
"customRepeatUnit": null,
"customRepeatValue": null,
"autoRotationSize": null,
"roundRobinSize": 1,
"startsOnDayOfWeek": 1,
"startsOnDateOfMonth": null,
"startsOnTime": "09:00",
"rotations": [
{
"id": 12,
"rotationOrder": 1,
"members": [
{ "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null, "memberOrder": 1 }
]
}
]
}
]
}
],
"teamSettings": {
"timezone": "Europe/Berlin",
"escalationRepeats": 1,
"escalationRepeatsAfterMinutes": 15,
"escalationRepeatsStopMode": "acknowledged",
"engagementReportEnabled": false,
"engagementReportDayOfWeek": null,
"engagementReportTime": null
}
}Die Schedule-Felder sind unter Rotationskadenz und Schedule aktualisieren erklärt.
Stufe lesen
GET /api/im/teams/:id/tiers/:tierId
Liest eine Stufe mit ihren Schedules, Rotationen und Mitgliedern zurück, in derselben Form wie ein Eintrag von tiers unter Eskalationskette lesen. Jede IM-berechtigte Rolle darf ihn aufrufen.
Beispiel (cURL)
curl "$BASE_URL/api/im/teams/3/tiers/7" \
-H "Authorization: Bearer $TOKEN"Antwort
200 OK, ein Stufenobjekt wie in tiers[] oben. 404 mit imEscalationTierNotFound, wenn :tierId keine Stufe dieses Teams ist.
Stufe hinzufügen
POST /api/im/teams/:id/tiers
Hängt eine Stufe ans Ende der Kette (tierOrder = höchste + 1) oder fügt sie an der Position aus tierOrder ein. Jedes Stufenfeld außer tierOrder lässt sich in derselben Anfrage setzen, mit denselben Namen und derselben Prüfung wie bei Stufe ändern; ein weggelassenes Feld bekommt den Standardwert aus der Tabelle oben. Im selben Schritt entsteht ein Schedule unter der Stufe: Name Tier N schedule, 24/7, rotationMode: "none", in der Zeitzone des Teams (oder UTC, wenn das Team keine hat), mit einer Rotationsgruppe, die die angegebenen Mitglieder in der angegebenen Reihenfolge enthält.
Anfrage (Request Body)
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
memberUserIds | string[] | Ja | 1 bis 200 verschiedene User-IDs, alle Mitglieder dieses Teams. |
tierOrder | integer | Nein | Position der neuen Stufe, 1 bis höchste + 1. Jede Stufe ab dieser Position rückt im selben Schritt um eins nach hinten. Weggelassen = ans Ende. Overrides, die eine Stufe per escalationTierOrder treffen, behalten ihre Nummer, wie beim Neu ordnen. |
autoEscalationEnabled, autoEscalationAfterMinutes, autoEscalationStopMode, autoEscalationSeverities, autoEscalationTimeFilters, repeats, repeatsAfterMinutes, repeatsStopMode | siehe Stufenfelder | Nein | Die Einstellungen der Stufe. Weggelassen = Standardwert. |
Beispiel (cURL)
curl -X POST "$BASE_URL/api/im/teams/3/tiers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"memberUserIds": ["u_abc123", "u_def456"],
"autoEscalationAfterMinutes": 10,
"repeats": 1
}'Antwort (Response)
200 OK: die Stufenfelder plus schedules mit dem einen neuen Schedule, in derselben Form wie in der Eskalationskette (Mitglieder ohne userImage).
{
"id": 22,
"tierOrder": 2,
"autoEscalationEnabled": true,
"autoEscalationAfterMinutes": 10,
"autoEscalationStopMode": "acknowledged",
"autoEscalationSeverities": null,
"autoEscalationTimeFilters": [],
"repeats": 1,
"repeatsAfterMinutes": null,
"repeatsStopMode": "acknowledged",
"schedules": [
{
"id": 8,
"displayName": "Tier 2 schedule",
"timezone": "Europe/Berlin",
"effectiveFrom": null,
"effectiveUntil": null,
"weeklySchedules": [],
"rotationMode": "none",
"rotationRepeats": null,
"customRepeatUnit": null,
"customRepeatValue": null,
"autoRotationSize": null,
"roundRobinSize": 1,
"startsOnDayOfWeek": null,
"startsOnDateOfMonth": null,
"startsOnTime": null,
"rotations": [
{
"id": 14,
"rotationOrder": 1,
"members": [
{ "userId": "u_abc123", "userName": "Ada Lovelace", "memberOrder": 1 },
{ "userId": "u_def456", "userName": "Bob Fixit", "memberOrder": 2 }
]
}
]
}
]
}Stufe ändern
PATCH /api/im/teams/:id/tiers/:tierId
Jedes Feld aus der Tabelle Stufenfelder außer tierOrder ist optional und änderbar. Nur die im Body vorhandenen Felder ändern sich.
Beispiel (cURL)
curl -X PATCH "$BASE_URL/api/im/teams/3/tiers/21" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"autoEscalationAfterMinutes": 10,
"autoEscalationSeverities": ["critical"],
"autoEscalationTimeFilters": [{ "from": "18:00", "until": "08:00", "days": [1, 2, 3, 4, 5] }]
}'Antwort (Response)
200 OK: die Stufenfelder nach der Änderung (ohne schedules).
Stufe löschen
DELETE /api/im/teams/:id/tiers/:tierId
Löscht die Stufe samt ihren Schedules, Rotationsgruppen und Schichten. Die übrigen Stufen behalten ihre tierOrder; wer Stufe 2 von 3 löscht, behält die Positionen 1 und 3. Mit Neu ordnen schließt du die Lücke, falls du fortlaufende Nummern brauchst.
Beispiel (cURL)
curl -X DELETE "$BASE_URL/api/im/teams/3/tiers/22" \
-H "Authorization: Bearer $TOKEN"Antwort (Response)
200 OK
{ "success": true }Stufen neu ordnen
POST /api/im/teams/:id/tiers/reorder
Nummeriert die Kette in der gesendeten Reihenfolge auf 1..n um.
Anfrage (Request Body)
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
tierIds | number[] | Ja | Jede Stufen-ID dieses Teams genau einmal, in der neuen Reihenfolge. |
Beispiel (cURL)
curl -X POST "$BASE_URL/api/im/teams/3/tiers/reorder" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "tierIds": [22, 21] }'Antwort (Response)
200 OK
{ "tiers": [{ "id": 22, "tierOrder": 1 }, { "id": 21, "tierOrder": 2 }] }Schedule zu einer Stufe hinzufügen
POST /api/im/tiers/:tierId/schedules
Das Team ergibt sich aus der Stufe. Eine unbekannte Stufe oder eine einer anderen Organisation antwortet 404 imEscalationTierNotFound. Der verschachtelte Pfad POST /api/im/teams/:id/tiers/:tierId/schedules nimmt denselben Body und liefert dieselbe Antwort; er ist veraltet und entfällt am 18.01.2027.
Legt einen weiteren Schedule unter einer Stufe an, etwa einen Follow-the-Sun-Schedule in einer anderen Zeitzone, mit Kadenz und Rotationsgruppen in einem Aufruf. Bereitschaft in einer Stufe hat, wen irgendeiner ihrer Schedules gerade in Schicht hat.
Anfrage (Request Body)
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | Ja | 1 bis 120 Zeichen nach dem Trimmen. |
timezone | string | Ja | IANA-Zone, in der der Schedule ausgewertet wird. |
effectiveFrom | string | null | Nein | ISO-Zeitstempel, vor dem der Schedule niemanden alarmiert. |
effectiveUntil | string | null | Nein | ISO-Zeitstempel, nach dem der Schedule niemanden alarmiert. |
weeklySchedules | array | Nein | Bereitschaftsfenster, gleiche Form wie autoEscalationTimeFilters. Weggelassen oder [] = 24/7. |
rotations | array | Nein | Rotationsgruppen, bis zu 50, jeweils { members: string[] } mit bis zu 200 verschiedenen Mitgliedern dieses Teams. Die Array-Reihenfolge ist die Rotationsreihenfolge. |
Dazu die Kadenzfelder aus Rotationskadenz. Weggelassene Kadenzfelder stehen auf rotationMode: "none", roundRobinSize: 1, alles andere null. Die resultierende Kadenz wird als Ganzes validiert.
Beispiel (cURL)
curl -X POST "$BASE_URL/api/im/tiers/21/schedules" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "APAC Follow-the-Sun",
"timezone": "Asia/Singapore",
"weeklySchedules": [{ "from": "09:00", "until": "18:00", "days": [1, 2, 3, 4, 5] }],
"rotationMode": "explicit",
"rotationRepeats": "weekly",
"startsOnDayOfWeek": 1,
"startsOnTime": "09:00",
"rotations": [{ "members": ["u_abc123"] }, { "members": ["u_def456"] }]
}'Antwort (Response)
200 OK: der neue Schedule in derselben Form wie in der Eskalationskette (Mitglieder ohne userImage).
Eskalationskette testen (Probelauf)
POST /api/im/teams/:id/escalation-dry-run
Geht die Stufen des Teams so durch, wie es die Eskalations-Engine für einen Incident mit dem angegebenen Schweregrad zum angegebenen Zeitpunkt tun würde, und meldet pro Stufe, wer wann über welchen Kanal alarmiert würde und was einen Kanal daran hindern würde, jemanden zu erreichen. Es wird nichts gesendet, nichts gespeichert, kein Incident angelegt und Round Robin nicht weitergeschaltet: Eine Round-Robin-Stufe zeigt als Vorschau, wen der nächste Incident vom aktuellen Stand aus bekäme.
Wer ihn aufrufen darf: Organisationsrolle admin oder editor, oder Team-Admin dieses Teams. Alle anderen bekommen 403 imTeamWriteDenied.
Anfrage (Request Body)
Der Body ist optional; {} oder kein Body läuft mit den Standardwerten.
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
at | string | Nein | ISO-8601-Zeitstempel mit Offset: wann der gedachte Incident eintrifft. Standard: jetzt. |
severity | string | Nein | sev1, sev2, sev3 oder sev4. Standard sev1. Wählt bei jeder Person die Regelkette high (sev1/sev2) oder low (sev3/sev4). |
Beispiel (cURL)
curl -X POST "$BASE_URL/api/im/teams/3/escalation-dry-run" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "at": "2026-10-28T23:00:00+01:00", "severity": "sev1" }'Antwort (Response)
200 OK
{
"at": "2026-10-28T22:00:00.000Z",
"severity": "sev1",
"urgency": "high",
"tiers": [
{
"tierId": 21,
"tierOrder": 1,
"offsetMinutes": 0,
"repeatOffsetsMinutes": [10],
"status": "pages",
"filledFromTier": null,
"conditionFailedOpen": false,
"targets": [
{
"userId": "u_abc123",
"name": "Ada Lovelace",
"channels": [
{ "channel": "push", "delayMinutes": 0, "warnings": [] },
{ "channel": "sms", "delayMinutes": 5, "warnings": ["phoneUnverified"] }
],
"warnings": []
}
]
},
{
"tierId": 22,
"tierOrder": 2,
"offsetMinutes": 20,
"repeatOffsetsMinutes": [],
"status": "pages",
"filledFromTier": null,
"conditionFailedOpen": false,
"targets": [
{
"userId": "u_def456",
"name": "Bob Fixit",
"channels": [],
"warnings": ["noRules"]
}
]
},
{
"tierId": 23,
"tierOrder": 3,
"offsetMinutes": null,
"repeatOffsetsMinutes": [],
"status": "notReached",
"filledFromTier": null,
"conditionFailedOpen": false,
"targets": []
}
]
}| Feld | Beschreibung |
|---|---|
at, severity | Die Werte, mit denen der Probelauf gerechnet hat. |
urgency | high bei sev1/sev2, low bei sev3/sev4. |
tiers[].offsetMinutes | Minuten nach Eintreffen des Incidents, zu denen diese Stufe alarmiert. null, wenn die Stufe übersprungen wird, leer ist oder nicht erreicht wird. |
tiers[].repeatOffsetsMinutes | Minuten nach Eintreffen des Incidents für jede Wiederholung dieser Stufe. |
tiers[].status | pages: Die Stufe alarmiert ihre eigenen Diensthabenden. filledUp: Die Stufe ist leer und leiht sich die Personen der nächsthöheren Stufe, in der jemand Bereitschaft hat (automatisches Auffüllen). skipped: Schweregradfilter oder Zeitfenster der Stufe schließen diesen Incident aus. empty: Niemand hat Bereitschaft und nichts füllt die Lücke. notReached: Eine frühere Stufe beendet die Kette. |
tiers[].filledFromTier | Bei filledUp: die tierOrder der Stufe, deren Personen die Lücke füllen, sonst null. |
tiers[].conditionFailedOpen | true, wenn das Zeitfenster der Stufe nicht gelesen werden konnte und die Stufe deshalb trotzdem alarmiert (wie die Engine). |
tiers[].targets[] | Die Personen, die alarmiert würden: userId, name, ihre channels und warnings. |
targets[].channels[] | Ein Eintrag pro Regel in der Kette der Person: channel (push, sms, voice, email), delayMinutes (Minuten, nachdem die Stufe alarmiert) und warnings (leer = dieser Kanal käme an). |
Mögliche Warnungen:
noRules(an der Person): Die Person hat keine Regel für diese Dringlichkeit, über sie wird also niemand alarmiert.phoneUnverified: SMS oder Anruf, und die Person hat keine bestätigte Telefonnummer.noDevice: eine Push-Regel, aber kein registriertes Gerät.quotaExhausted: SMS oder Anruf, und das Telco-Kontingent der Organisation ist aufgebraucht, ohne dass Mehrverbrauch erlaubt ist.disabledForSeverity: Die Person hat diesen Kanal für diesen Schweregrad abgeschaltet.
Zeitablauf wie in der Engine: Eine Stufe alarmiert, wiederholt repeats-mal alle repeatsAfterMinutes (sonst autoEscalationAfterMinutes), dann alarmiert die nächste Stufe autoEscalationAfterMinutes später. Eine übersprungene und eine leere Stufe kosten keine Zeit. Eine Endstufe (die letzte oder eine mit autoEscalationEnabled: false) beendet die Kette; jede spätere Stufe ist notReached. Die Wiederholung der ganzen Kette am Team (Team ändern) ist nicht Teil des Probelaufs.
Häufige Fehler
401 Unauthorized(unauthorized) wenn du nicht authentifiziert bist403 Forbidden(imAccessDenied) bei einem kunden-gescopten Token, oder wenn deine Session keine IM-berechtigte Rolle hat403 Forbidden(imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist403 Forbidden(imTeamWriteDenied) bei jedem Schreiben, wenn du weder Organisations-Admin noch Team-Admin dieses Teams bist; beim Probelauf, wenn du weder Organisations-Admin oder -Editor noch Team-Admin dieses Teams bist404 Not Found(imTeamNotFound) wenn das Team nicht existiert oder zu einer anderen Organisation gehört404 Not Found(imEscalationTierNotFound) wenn:tierIdkeine Stufe dieses Teams ist404 Not Found(imTeamMemberNotFound) wenn eine User-ID inmemberUserIdsoderrotationskein Mitglied dieses Teams ist400 Bad Request(invalidRequestBody) wenn eine Pfad-ID keine positive Ganzzahl ist,atbeim Probelauf kein ISO-8601-Zeitstempel mit Offset ist oderseveritynichtsev1bissev4,memberUserIdsfehlt, leer ist oder eine leere ID enthält,tierIdsfehlt, leer ist oder nicht aus verschiedenen positiven Ganzzahlen besteht,nameodertimezonefehlt oder ungültig ist,effectiveFrom/effectiveUntilkein gültiger Zeitstempel ist,rotationsfehlerhaft ist, odertierOrderkeine Ganzzahl ab1ist422 Unprocessable Entity(imTierReorderMismatch) wenntierIdsnicht genau die Stufen-IDs dieses Teams enthält422 Unprocessable Entity(imInvalidRequestBody) wennautoEscalationEnabledkein Boolean ist422 Unprocessable Entity(imInvalidNumber) wennautoEscalationAfterMinutes,repeatsoderrepeatsAfterMinuteskeine Ganzzahl ab0ist, oder eine Kadenzzahl keine Ganzzahl ab1, odertierOrdergrößer als die höchste Stufe + 1 ist422 Unprocessable Entity(imInvalidStopMode) wenn ein Stop-Modus nichtacknowledgedoderresolvedist422 Unprocessable Entity(imInvalidSeverities) wennautoEscalationSeveritieswedernullnoch eine Liste auscritical,warning,minorist422 Unprocessable Entity(imInvalidTimeFilter) wenn eine Fensterliste kein Array ist, mehr als 50 Einträge hat, oder ein Eintrag kein Objekt ist oder keindays-Array hat422 Unprocessable Entity(imInvalidTimeOfDay) wennfrom/untileines Fensters oderstartsOnTimenicht"HH:mm"ist422 Unprocessable Entity(imInvalidDayOfWeek) wenn ein Fenstertag oderstartsOnDayOfWeeknicht 1 bis 7 ist422 Unprocessable Entity(imInvalidRotationMode) wennrotationModenichtnone,autooderexplicitist422 Unprocessable Entity(imInvalidRotation) wenn die Kadenz nicht zusammenpasst, eine Liste mehr als 200 Mitglieder oder 50 Rotationsgruppen hat, oder eine User-ID in einer Liste doppelt vorkommt409 Conflict(imTierOrderConflict) wenn zwei Stufen im selben Moment angelegt oder verschoben wurden; erneut versuchen
Team-Overrides
Die On-Call-Overrides eines Teams auflisten, hinzufügen, ändern und löschen, sowohl Team-Overrides als auch solche an einem Schedule des Teams.
Teams
Incident-Management-Teams auflisten, lesen, anlegen, ändern und löschen, einschließlich der Team-Einstellungen für Eskalation und Engagement-Report.