Delivery Channels

Surflet supports 11 delivery channels, allowing you to push notifications to your target users across various platforms when publishing a page.

Quick Notify

The simplest approach is the shorthand syntax for the notify parameter:

page = client.publish(
    title="Deploy Report",
    content="Build #456 deployed.",
    notify="slack:#devops",
)

Multi-Channel Notifications

Use the notify parameter to configure multiple channels at once:

page = client.publish(
    title="Refund Approval",
    page_type="approval",
    blocks=[...],
    notify={
        "channels": [
            {"type": "slack", "target": "#cs-approvals"},
            {"type": "email", "to": ["[email protected]"]},
            {"type": "sms", "to": ["+8613800138000"]},
        ],
    },
)

Channel Types

1. Slack

Send a message to a Slack channel or individual.

{
  "type": "slack",
  "target": "#channel-name",
  "mention": ["@user1", "@user2"],
  "thread_ts": "optional-thread-id"
}

Shorthand: notify="slack:#channel-name"

Requires a Slack App OAuth Token configured in the Surflet console.

2. Email

Send an email notification.

{
  "type": "email",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],
  "subject_prefix": "[Surflet]",
  "template": "approval"
}

Shorthand: notify="email:[email protected]"

Supports custom email templates. By default, the email includes the page title, summary, and action link.

3. SMS

Send an SMS notification.

{
  "type": "sms",
  "to": ["+8613800138000"],
  "message_template": "You have a new approval pending: {{title}}"
}

Shorthand: notify="sms:+8613800138000"

4. Push Notification

Send a mobile push notification.

{
  "type": "push",
  "user_ids": ["user_abc123"],
  "title": "New Approval",
  "body": "Refund approval #4821 requires your attention",
  "priority": "high"
}

Requires users to have the Surflet mobile app installed or to have integrated the Push SDK.

5. Webhook

Push to a custom webhook URL.

{
  "type": "webhook",
  "url": "https://your-system.com/webhook/notifications",
  "headers": {
    "Authorization": "Bearer token123"
  },
  "method": "POST"
}

The webhook receives a JSON payload containing the page ID, title, and URL.

6. Jira

Create or update a Jira issue.

{
  "type": "jira",
  "project": "CS",
  "issue_type": "Task",
  "assignee": "[email protected]",
  "labels": ["surflet", "refund"],
  "custom_fields": {
    "customfield_10001": "high"
  }
}

Requires Jira connection details (URL, API Token) configured in the console.

7. Microsoft Teams

Send a message to a Teams channel.

{
  "type": "teams",
  "webhook_url": "https://outlook.office.com/webhook/...",
  "mention": ["[email protected]"]
}

Uses the Teams Incoming Webhook connector.

8. Discord

Send a message to a Discord channel.

{
  "type": "discord",
  "webhook_url": "https://discord.com/api/webhooks/...",
  "mention_roles": ["@approvers"]
}

9. PagerDuty

Create a PagerDuty incident.

{
  "type": "pagerduty",
  "routing_key": "your-integration-key",
  "severity": "warning",
  "summary": "Refund approval timed out without action"
}

Ideal for triggering on-call escalation when a critical approval times out.

10. Voice Call

Place a voice call notification.

{
  "type": "voice",
  "to": ["+8613800138000"],
  "message": "You have an urgent approval that requires your attention. Please log in to Surflet to review.",
  "language": "en-US"
}

Suitable for urgent scenarios, such as high-value transaction approvals that have timed out.

11. Custom

Custom channel via plugin extension.

{
  "type": "custom",
  "channel_id": "my-internal-chat",
  "config": {
    "room": "approvals",
    "priority": "urgent"
  }
}

Notification Templates

Each channel supports custom notification templates using Mustache syntax:

{
  "type": "slack",
  "target": "#approvals",
  "template": {
    "title": "🔔 New Approval: {{page.title}}",
    "body": "Submitted by: {{page.created_by}}\nPriority: {{page.priority}}\n\n<{{page.url}}|View Details>"
  }
}

Available variables:

Variable	Description
{{page.title}}	Page title
{{page.url}}	Page URL
{{page.summary}}	Page summary
{{page.priority}}	Priority
{{page.created_by}}	Creator
{{page.tags}}	Tags

Retry Policy

Retry behavior when a notification delivery fails:

{
  "notify": {
    "channels": [...],
    "retry": {
      "max_attempts": 3,
      "backoff": "exponential",
      "initial_delay_seconds": 60
    }
  }
}

Defaults to 3 retries with exponential backoff.

Scheduled Delivery

Supports scheduling notifications for a future time:

{
  "notify": {
    "channels": [...],
    "schedule": {
      "send_at": "2026-03-24T09:00:00Z",
      "timezone": "Asia/Shanghai"
    }
  }
}