Notifications

action.notification.notify lets an automation run tell the person it runs as that something happened. It creates one in-app notification for the run's Run As person, in the run's organization. Their Email me about new notifications setting decides whether it is also emailed (see Notifications).

The call names only what is said. Who is told, and in which organization, come from the run itself: the input has no recipient, user or organization field, and a call that adds one is refused.

In a workflow, select the Scrydon tool Notify me in an Agent block's tools. There is no Notify me block. Scheduled digests that Cortex creates use the same tool (see Create an automation from chat).

// Inside a reviewed Scrydon tool that lists "action.notification.notify"
// in its platformOperations.
const { notificationId, status } = await ctx.action.notification.notify({
  title: 'Solar digest',
  body: 'Two new results today.\nhttps://example.com/a',
  link: { url: 'https://example.com/a', label: 'Read it' },
  idempotencyKey: 'digest',
})

Who may call it

• Only a workflow run or a process-flow run. A live Cortex turn is refused, because the person is already in that conversation; Cortex never offers the tool in a chat. A call made with a standalone token, outside any run, is refused too.
• Only a run whose Run As is a person who is still an active member of the organization. A run that runs as a service account, or as nobody, is refused.
• Only Scrydon's own Notify me tool. Another extension's tool is refused even when its manifest lists the operation.

Input

@scrydon/sdk/platform exports the bounds (NOTIFICATION_NOTIFY_TITLE_MAX_CHARS, NOTIFICATION_NOTIFY_BODY_MAX_CHARS, NOTIFICATION_NOTIFY_LINK_URL_MAX_CHARS, NOTIFICATION_NOTIFY_LINK_LABEL_MAX_CHARS, NOTIFICATION_NOTIFY_IDEMPOTENCY_KEY_MAX), so you can check an input before you send it. Unknown fields are refused.

The key is scoped to the run. A retry in the same run with the same key returns the first notification instead of sending a second one, and next week's run of the same workflow, sending the same literal key, notifies again.

Your organization's data loss prevention policy applies to the title, the body and the link label, and checks the link.

Result

notificationId, and status: created, or deduplicated when this run already sent a notification under the same key.

The notification has the type automation.result.

Errors

A refusal is a FORBIDDEN error whose message leads with a stable code, and the code is also in details.refusal. A tool sees only the message, so match on its leading code.

INVALID_REQUEST means the input did not pass validation, for example a recipient field or an http:// link. PROVIDER_UNAVAILABLE means the notification could not be created just then; it is safe to retry with the same key.