ConnectCloud Developers

Channel kinds and settings for the settings pages (comms:read)

GET /api/comms/v1/bootstrap

Module: Comms · operationId: getBootstrap · Tag: Settings · Auth: access token (Authorization: Bearer <accessToken>)

Responses

  • 200 Bootstrap (application/json)
  • 403 Error (application/json)

Fields of the 200 answer:

  • canAdmin (boolean): Whether the caller may change channels and settings (comms:admin)
  • channelKinds (array of ChannelKind): The channel kinds a tenant can configure, with their form fields
    • capabilities (object): Optional abilities of the kind
      • html (boolean): The kind can send HTML
      • inbound (boolean): The kind can also receive (a mailbox)
    • description (string): Short explanation of the kind
    • fields (array of FieldSpec): Configuration and secret fields of the kind
      • help (string): Help text for the field
      • key (string): Key in config or secrets
      • label (string): Display label of the field
      • options (array of object): Choices of a select field
        • label (string): Display label
        • value (string): Stored value
      • required (boolean): The field must be set
      • secret (boolean): Stored encrypted and never returned
      • type (string): Input type; secret fields go into secrets and are never returned (one of text, email, url, secret, select, number, bool)
    • kind (string): Kind key, used as kind when creating a channel
    • label (string): Display name of the kind
    • managed (boolean): Created by comms itself (kind teams: when the Teams app is added to a team or group chat), never through POST /channels; the configuration is read-only
    • medium (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of email, webhook, teams, push)
    • owner (string): platform: run by the platform; tenant: configured by the tenant (one of platform, tenant)
  • events (array of EventSpec): The event catalogue personal subscriptions can start on
    • default (object): Default subject and body of a notification of the event
      • body (string): Body template
      • subject (string): Subject template
    • fields (array of EventField): Payload fields conditions and templates may use
      • kind (string): Value type of the field (one of text, number, date, bool, list)
      • label (string): Display name of the field
      • path (string): Path of the field in the event payload
    • group (string): Group the event is listed under
    • label (string): Display name of the event
    • link (string): Portal path of the event's record with {path} placeholders
    • people (array of object): Payload fields that name people (recipients of the event)
      • kind (string): How the field names the person (one of email, employee, user_ref, user_refs)
      • label (string): Display name of the role
      • manager (boolean): The person's managers can be addressed too
      • path (string): Path of the field in the event payload
    • source (string): Producing module
    • type (string): Event type, e.g. hr.absence.requested
  • settings (Settings)
    • defaultEmailChannelId (string (uuid)): The tenant's default e-mail channel; empty: the platform channel
    • rev (integer): Revision of the settings

Example 200 answer:

{
  "canAdmin": true,
  "channelKinds": [
    {
      "capabilities": {
        "html": false,
        "inbound": false
      },
      "description": "Signierte HTTP-Anfragen an eine Adresse Ihrer Wahl, z. B. einen Teams-Workflow oder Power Automate.",
      "fields": [
        {
          "help": "Wird verschlüsselt gespeichert, weil Webhook-Adressen oft ein Zugriffstoken enthalten.",
          "key": "url",
          "label": "Adresse (URL)",
          "required": true,
          "secret": true,
          "type": "url"
        },
        {
          "key": "format",
          "label": "Format",
          "options": [
            {
              "label": "JSON-Ereignis",
              "value": "json_event"
            },
            {
              "label": "Microsoft Teams (Adaptive Card)",
              "value": "teams_card"
            }
          ],
          "required": true,
          "secret": false,
          "type": "select"
        }
      ],
      "kind": "webhook",
      "label": "Webhook",
      "managed": false,
      "medium": "webhook",
      "owner": "tenant"
    }
  ],
  "events": [
    {
      "default": {
        "body": "Die Abwesenheit „{{typeName}}“ von {{employeeName}} vom {{startDate}} bis {{endDate}} ({{days}} Arbeitstage) wurde beantragt.\n\n{{link}}",
        "subject": "Abwesenheit beantragt: {{employeeName}} ({{startDate}} – {{endDate}})"
      },
      "fields": [
        {
          "kind": "text",
          "label": "Mitarbeiter:in",
          "path": "employeeName"
        },
        {
          "kind": "date",
          "label": "Von",
          "path": "startDate"
        },
        {
          "kind": "date",
          "label": "Bis",
          "path": "endDate"
        },
        {
          "kind": "number",
          "label": "Arbeitstage",
          "path": "days"
        }
      ],
      "group": "Personal",
      "label": "Abwesenheit beantragt",
      "link": "/hr/absences/{absenceId}",
      "people": [
        {
          "kind": "employee",
          "label": "Antragsteller:in",
          "manager": true,
          "path": "employeeId"
        }
      ],
      "source": "hr",
      "type": "hr.absence.requested"
    }
  ],
  "settings": {
    "defaultEmailChannelId": "6b1f3c2a-8d4e-4f5a-9b7c-1e2d3f4a5b6c",
    "rev": 3
  }
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/comms/v1/bootstrap' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI