Skip to content

API reference

Chat announcements

Joiner, team move and new title posts in Slack, Microsoft Teams, Google Chat, Mattermost, Discord or Rocket.Chat: status, the preview of each post, skipping one and trying a failed one again. Connecting, settings and test messages happen in the web app.

9 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

Chat announcements status#

POST/v1/org/chat.statusRead

Announcements in chat tools (Slack, Microsoft Teams, Google Chat, Mattermost, Discord and Rocket.Chat; spec chat-announcements): for each tool, whether this server offers it (available), the connection (status, Slack workspace, channel, whether the setup is finished (status removed: Slack reported that the workspace removed Bizisy; an owner or admin connects again in Integrations → Slack), settings: joiners, moves (team moves), titles (new job titles, promotions included), leavers (off by default), mention (Slack only: @mention by work email; the other tools can't map a person by email, so their posts use the name)) and counts (scheduled in the next 7 days, posted in the last 30, failed). Owners, admins and HR; never custom roles. How the Slack app works, for anyone asking: https://bizisy.com/integrations/slack.

Who can call it
Manage key owner admin hr
MCP tool
org_chat_status on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • providersobject[]required
    5 fields
    • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
    • namestringrequired
    • availablebooleanrequired

      The server offers this tool (it is set up for it); false: not available yet.

    • connectionobject | nullrequired
      8 fields
      • status"pending" | "connected" | "error" | "removed"required

        pending: not connected yet; connected; error: the last run could not post (error says why); removed: Slack reported that the workspace removed Bizisy, so its access is gone and nothing is posted until an owner or admin connects again in Integrations → Slack.

      • labelstring | nullrequired
      • channelobject | nullrequired
        2 fields
        • idstring | nullrequired
        • namestringrequired
      • connected_atstring | nullrequired
      • errorstring | nullrequired
      • setup_completebooleanrequired

        False from a first connect until an owner or admin finishes the setup (Start posting, or settings_update setup_complete: true); nothing is posted until then.

      • failureobject | nullrequired

        Why the last attempt to connect failed, until one succeeds: session (finished in another browser or as someone else), denied (access not granted), scopes (not every permission allowed), failed.

        2 fields
        • reason"session" | "denied" | "scopes" | "failed"required
        • atstringrequired
      • settingsobjectrequired
        6 fields
        • joinersbooleanrequired
        • movesbooleanrequired
        • titlesbooleanrequired
        • leaversbooleanrequired
        • mentionbooleanrequired
        • announcementsbooleanrequired

          Company announcements published to everyone: their title, the day they are published (on by default).

    • countsobjectrequired
      3 fields
      • scheduledintegerrequired

        Announcements in the next 7 days (today's included until they are posted).

      • postedintegerrequired

        Posted in the last 30 days.

      • failedintegerrequired

        Failed and waiting for Try again (or still being retried).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "providers": [
      {
        "provider": "slack",
        "name": "Slack",
        "available": true,
        "connection": {
          "status": "connected",
          "label": "Acme",
          "channel": {
            "id": "C1",
            "name": "general"
          },
          "connected_at": "2026-10-01T10:00:00.000Z",
          "error": null,
          "setup_complete": true,
          "failure": null,
          "settings": {
            "joiners": true,
            "moves": true,
            "titles": true,
            "leavers": false,
            "mention": true,
            "announcements": true
          }
        },
        "counts": {
          "scheduled": 2,
          "posted": 5,
          "failed": 0
        }
      },
      {
        "provider": "teams",
        "name": "Microsoft Teams",
        "available": false,
        "connection": null,
        "counts": {
          "scheduled": 0,
          "posted": 0,
          "failed": 0
        }
      }
    ]
  }
}

Connect a chat tool#

POST/v1/org/chat.connectWrite

Starts connecting a tool for announcements. Slack: returns the address where someone allowed to install apps in the Slack workspace adds Bizisy (it expires in 15 minutes). Every other tool: send webhook_url, the incoming webhook address made in the channel, and optionally channel_name (shown in Bizisy). Microsoft Teams: a Workflows webhook ("Send webhook alerts to a channel") on Microsoft's Power Automate hosts. Google Chat: https://chat.googleapis.com/v1/spaces/…/messages?key=…&token=… (space → Apps & integrations → Webhooks). Mattermost: https://<your server>/hooks/<id> (Integrations → Incoming Webhooks). Discord: https://discord.com/api/webhooks/<id>/<token> (Server Settings → Integrations → Webhooks). Rocket.Chat: https://<your server>/hooks/<id>/<token> (Administration → Integrations → Incoming). Nothing is posted until the setup is finished. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. An owner or admin connects a chat tool in the app (Integrations, Chat: Slack, Microsoft Teams, Google Chat, Mattermost, Discord or Rocket.Chat).
MCP tool
org_chat_connect on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • webhook_urlstring

    Every tool but Slack: the webhook (Teams: workflow) address.

    Up to 2000 characters.

  • channel_namestring

    Every tool but Slack: the channel's name, as shown in Bizisy.

    1–100 characters.

Returns

  • urlstring | nullrequired

    Slack: where to add Bizisy; null for the other tools.

  • expires_atstring | nullrequired
  • connectedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.connect \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "provider": "discord",
  "webhook_url": "https://discord.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz0123456789",
  "channel_name": "announcements"
}'
Response
{
  "data": {
    "url": "https://slack.com/oauth/v2/authorize?state=x",
    "expires_at": "2026-10-10T10:15:00.000Z",
    "connected": false
  }
}

Slack channels#

POST/v1/org/chat.channelsRead

Lists the public channels of the connected Slack workspace (q filters by name; at most 200), to choose where announcements go (org_chat_settings_update channel_id). Private channels are not offered. Owners and admins.

Who can call it
Manage key owner admin
MCP tool
org_chat_channels on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • provider"slack"required
  • qstring

    Up to 80 characters.

Returns

  • channelsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.channels \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"slack","q":"gen"}'
Response
{
  "data": {
    "channels": [
      {
        "id": "C1",
        "name": "general"
      }
    ]
  }
}

Change chat announcement settings#

POST/v1/org/chat.settings.updateWrite

Changes where and what a connected tool announces: channel_id (Slack: a public channel from org_chat_channels), channel_name (every other tool: the channel's name as shown in Bizisy), joiners, moves (team moves), titles (new job titles, promotions included), leavers (the day after the last day; off by default), mention (Slack only: @mention people by work email), announcements (company announcements published to everyone: their title; on by default), setup_complete (true: finishes the setup; nothing is posted before; Slack needs a channel first). Send only what changes. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. The channel and what is announced change in the app only.
MCP tool
org_chat_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • channel_idstring

    1–50 characters.

  • channel_namestring

    1–100 characters.

  • joinersboolean
  • movesboolean
  • titlesboolean
  • leaversboolean
  • mentionboolean
  • announcementsboolean
  • setup_completetrue

Returns

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • channelobject | nullrequired
    2 fields
    • idstring | nullrequired
    • namestringrequired
  • settingsobjectrequired
    6 fields
    • joinersbooleanrequired
    • movesbooleanrequired
    • titlesbooleanrequired
    • leaversbooleanrequired
    • mentionbooleanrequired
    • announcementsbooleanrequired

      Company announcements published to everyone: their title, the day they are published (on by default).

  • setup_completebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "provider": "slack",
  "channel_id": "C1",
  "joiners": true,
  "moves": true,
  "titles": false,
  "leavers": true,
  "mention": true,
  "setup_complete": true
}'
Response
{
  "data": {
    "provider": "slack",
    "channel": {
      "id": "C1",
      "name": "general"
    },
    "settings": {
      "joiners": true,
      "moves": true,
      "titles": false,
      "leavers": true,
      "mention": true,
      "announcements": true
    },
    "setup_complete": true
  }
}

Send a test message to a chat tool#

POST/v1/org/chat.testWrite

Posts a short test message to the connected channel now, so an owner or admin sees where announcements go (at most 10 tries an hour, failed ones included). sent false with error: the tool refused it or did not answer (error says why, in Bizisy's words). A dry run posts nothing. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. Test messages are sent from the app.
MCP tool
org_chat_test on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required

Returns

  • sentbooleanrequired
  • channelstring | nullrequired
  • errorstring

    Why the test message was not posted (the tool refused it or did not answer).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.test \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"slack"}'
Response
{
  "data": {
    "sent": true,
    "channel": "general"
  }
}

Preview chat announcements#

POST/v1/org/chat.previewRead

What a connected tool announces, with the exact text (nothing is posted): samples (an example of each kind and the test message) and items: the next 7 days and the last 30, each with its kind (joiner, change, leaver), person, day, status (scheduled, due, posted, failed, skipped) and error. Posts go out on the day they take effect, from 09:00 company time; a change recorded late is posted if its day was at most 2 days ago. Owners, admins and HR; never custom roles.

Who can call it
Manage key owner admin hr
MCP tool
org_chat_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required

Returns

  • samplesobject[]required
    4 fields
    • kind"joiner" | "change" | "leaver" | "test"required
    • titlestringrequired
    • textstringrequired
    • detailsstring | nullrequired
  • itemsobject[]required
    10 fields
    • kind"joiner" | "change" | "leaver"required
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • daystringrequired
    • status"scheduled" | "due" | "posted" | "failed" | "skipped"required

      scheduled: a later day, or today before 09:00; due: the next run posts it (within the hour); posted; failed (error says why; Try again with org_chat_retry); skipped (org_chat_skip).

    • titlestringrequired
    • textstringrequired
    • detailsstring | nullrequired
    • errorstring | nullrequired
    • attemptsintegerrequired
    • posted_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.preview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"teams"}'
Response
{
  "data": {
    "samples": [
      {
        "kind": "joiner",
        "title": "New joiner",
        "text": "Please welcome Alex Morgan to Acme!",
        "details": "Product Designer · Design · reports to Sam Lee"
      },
      {
        "kind": "test",
        "title": "Bizisy is connected",
        "text": "Announcements from Acme will appear in this channel.",
        "details": null
      }
    ],
    "items": [
      {
        "kind": "joiner",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "day": "2026-10-12",
        "status": "scheduled",
        "title": "New joiner",
        "text": "Please welcome Inês Martins to Acme!",
        "details": "Engineer · Platform",
        "error": null,
        "attempts": 0,
        "posted_at": null
      }
    ]
  }
}

Skip a chat announcement#

POST/v1/org/chat.skipWrite

Skips one announcement before it is posted (skipped true), for example when the person prefers none, or undoes the skip (skipped false). kind (joiner, change, leaver), person_id and day as in org_chat_preview. A posted announcement can't be skipped. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Skipping an announcement happens in the app.
MCP tool
org_chat_skip on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • person_idstringrequired
  • kind"joiner" | "change" | "leaver"required
  • daystringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • skippedbooleanrequired

Returns

  • person_idstringrequired
  • kind"joiner" | "change" | "leaver"required
  • daystringrequired
  • skippedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.skip \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "provider": "slack",
  "person_id": "p5",
  "kind": "joiner",
  "day": "2026-10-12",
  "skipped": true
}'
Response
{
  "data": {
    "person_id": "p5",
    "kind": "joiner",
    "day": "2026-10-12",
    "skipped": true
  }
}

Try a failed chat announcement again#

POST/v1/org/chat.retryWrite

Posts a failed announcement again now (after 3 attempts, or a failure that is not worth retrying by itself, it waits for this), even if its day has passed. kind, person_id and day as in org_chat_preview. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Trying a failed announcement again happens in the app.
MCP tool
org_chat_retry on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • person_idstringrequired
  • kind"joiner" | "change" | "leaver"required
  • daystringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • person_idstringrequired
  • kind"joiner" | "change" | "leaver"required
  • daystringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.retry \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"slack","person_id":"p5","kind":"change","day":"2026-10-09"}'
Response
{
  "data": {
    "person_id": "p5",
    "kind": "change",
    "day": "2026-10-09"
  }
}

Disconnect a chat tool#

POST/v1/org/chat.disconnectDestructive

Stops announcements in a chat tool: forgets the connection, its settings and the record of what was posted, and hands Slack its access back. Messages already posted stay in the channel. For every other tool, next_step says how to turn the webhook (Teams: workflow) off in that tool too. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. Disconnecting happens in the app.
MCP tool
org_chat_disconnect on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required

Returns

  • provider"slack" | "teams" | "google_chat" | "mattermost" | "discord" | "rocketchat"required
  • disconnectedtruerequired
  • next_stepstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/chat.disconnect \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"teams"}'
Response
{
  "data": {
    "provider": "teams",
    "disconnected": true,
    "next_step": "Bizisy no longer posts to Teams. To turn the workflow off too, open the Workflows app in Teams, find the workflow under Your workflows, and turn it off or delete it."
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs