Einrichtungsstand und Test-Alarm

GET /api/im/setup/state · PATCH /api/im/setup/state · POST /api/im/setup/test-page

Die Organisation hat ein frei gestaltbares Einrichtungsobjekt, damit sich eine Einrichtung (Team, Dienstplan, Alarmquelle, Test-Alarm) auf einem anderen Gerät oder von einem anderen Admin fortsetzen lässt. Diese Endpunkte lesen und schreiben dieses Objekt und schicken einen Test-Alarm, mit dem du prüfst, ob die Alarmierung dich erreicht.

AuthentifizierungAnkerlink kopieren

Alle drei brauchen eine IM-berechtigte Rolle (admin, editor, responder) oder einen organisationsweiten API-Token.

• Der Einrichtungsstand ist schon vor der Aktivierung von Incident Management erreichbar. Schreiben erfordert die Rolle admin der Organisation.
• Der Test-Alarm erfordert aktiviertes Incident Management und Schreibrechte am Team: die Rolle admin oder Team-Admin-Mitgliedschaft. Er alarmiert dich, braucht also eine Benutzersitzung; ein organisationsweiter API-Token erhält 403 (imAccessDenied).

Einrichtungsstand lesenAnkerlink kopieren

GET /api/im/setup/state

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/setup/state" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

{
  "organizationId": 42,
  "setupState": {
    "teamId": 7,
    "sourceCreated": true
  }
}

setupState ist das zuletzt gespeicherte Objekt (die Schlüssel oben sind nur ein Beispiel). Solange nichts gespeichert wurde, ist es {}.

Einrichtungsstand speichernAnkerlink kopieren

PATCH /api/im/setup/state

Ersetzt das gespeicherte Objekt vollständig.

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/setup/state" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setupState":{"teamId":7,"sourceCreated":true}}'

Antwort (Response)Ankerlink kopieren

Der gespeicherte Stand, in derselben Form wie beim GET.

Test-Alarm sendenAnkerlink kopieren

POST /api/im/setup/test-page

Legt im angegebenen Team einen Test-Incident an (isTest: true, Schweregrad sev4, Titel „Setup wizard test page“) und alarmiert dich auf jedem Kanal, der dich erreichen kann:

• email, immer
• sms, wenn in den Benachrichtigungseinstellungen eine bestätigte Telefonnummer hinterlegt ist
• voice, zusätzlich wenn includeVoice true ist und die Telefonnummer bestätigt ist

Test-Incidents zählt Offene Incidents zählen nicht mit. Test-Alarme und Test-Benachrichtigungen teilen sich eine Grenze von 5 pro Stunde und Person.

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/setup/test-page" \
  -H "Content-Type: application/json" \
  -b "$SESSION_COOKIE" \
  -d '{"teamId":7}'

Antwort (Response)Ankerlink kopieren

{
  "incidentId": 1834,
  "channels": ["email", "sms"],
  "enqueueErrors": []
}

enqueueErrors nennt die Kanäle, deren Alarm nicht in die Warteschlange kam. Leer bei Erfolg.

Häufige FehlerAnkerlink kopieren

• 400 Bad Request (invalidRequestBody) wenn setupState fehlt, kein Objekt oder größer als 8 KB ist, oder wenn teamId fehlt
• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn keine IM-berechtigte Rolle vorliegt, oder wenn der Test-Alarm mit einem API-Token angefordert wird
• 403 Forbidden (forbidden) wenn jemand ohne Admin-Rolle den Einrichtungsstand schreibt
• 403 Forbidden (imNotEnabled) wenn ein Test-Alarm vor der Aktivierung von Incident Management angefordert wird
• 403 Forbidden (imTeamWriteDenied) wenn du das Team nicht bearbeiten darfst
• 422 Unprocessable Entity (invalidTeamId) wenn das Team in deiner Organisation nicht existiert
• 429 Too Many Requests (imTestNotificationRateLimited) nach 5 Test-Alarmen oder Test-Benachrichtigungen in einer Stunde; retryAfterSeconds sagt, wann es wieder geht