Go SDK | ActivitySmith

Installation

Install the ActivitySmith Go SDK with go get:

go get github.com/ActivitySmithHQ/activitysmith-go

Usage

Create an API key
Pass the API key into activitysmithsdk.New.
Reuse the client anywhere you send pushes or Live Activity updates.

Create the client once:

package main

import (
	"log"

	activitysmithsdk "github.com/ActivitySmithHQ/activitysmith-go"
)

func main() {
	activitysmith, err := activitysmithsdk.New("YOUR-API-KEY")
	if err != nil {
		log.Fatal(err)
	}
}

Send a Push Notification

Use activitysmith.Notifications.Send when a deploy finishes, a customer upgrades, or a background job needs attention. Push notification example for a new subscription event

input := activitysmithsdk.PushNotificationInput{
	Title:   "New subscription 💸",
	Message: "Customer upgraded to Pro plan",
}

_, err := activitysmith.Notifications.
	Send(input)
if err != nil {
	log.Fatal(err)
}

Rich Push Notifications with Media

input := activitysmithsdk.PushNotificationInput{
	Title:       "Homepage ready",
	Message:     "Your agent finished the redesign.",
	Media:       "https://cdn.example.com/output/homepage-v2.png",
	Redirection: "https://github.com/acme/web/pull/482",
}

_, err := activitysmith.Notifications.
	Send(input)
if err != nil {
	log.Fatal(err)
}

Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content. Rich push notification with audio

What will work:

direct image URL: .jpg, .png, .gif, etc.
direct audio file URL: .mp3, .m4a, etc.
direct video file URL: .mp4, .mov, etc.
URL that responds with a proper media Content-Type, even if the path has no extension

Media can be combined with Redirection, but not with Actions. Redirection can be an HTTPS URL or a shortcuts://run-shortcut?name=... URL.

Actionable Push Notifications

Actionable push notification with redirection and actions

Push notification redirection can open an HTTPS URL or run a specific iPhone Shortcut with a shortcuts://run-shortcut?name=... URL when someone taps the notification. For expanded notification actions, open_url supports HTTPS URLs and shortcuts://run-shortcut?name=... URLs. Webhooks are executed by the ActivitySmith backend and must use HTTPS.

import (
	"log"

	activitysmithsdk "github.com/ActivitySmithHQ/activitysmith-go"
)

input := activitysmithsdk.PushNotificationInput{
	Title:       "New subscription 💸",
	Message:     "Customer upgraded to Pro plan",
	Redirection: "https://crm.example.com/customers/cus_9f3a1d",
	Actions: []activitysmithsdk.PushNotificationAction{
		activitysmithsdk.PushAction(
			"Open CRM",
			"open_url",
			"https://crm.example.com/customers/cus_9f3a1d",
		),
		activitysmithsdk.PushAction(
			"Chat with Jarvis",
			"open_url",
			"shortcuts://run-shortcut?name=Jarvis",
		),
		activitysmithsdk.PushAction(
			"Start Onboarding Workflow",
			"webhook",
			"https://hooks.example.com/activitysmith/onboarding/start",
			activitysmithsdk.PushActionMethod("POST"),
			activitysmithsdk.PushActionBody(map[string]interface{}{
				"customer_id": "cus_9f3a1d",
				"plan":        "pro",
			}),
		),
	},
}

_, err := activitysmith.Notifications.
	Send(input)
if err != nil {
	log.Fatal(err)
}

Live Activities

There are six types of Live Activities:

stats: best for showing business numbers side by side, such as revenue, sales, new users, conversion, refunds, or any other value you want visible at a glance
metrics: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
segmented_progress: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
progress: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
alert: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
timer: use it when you need countdowns or timers

Start & Update Live Activity

Use a stable streamKey to identify the metric, job, deployment, or system you want to keep visible. The first Stream(...) call starts the Live Activity. Later calls with the same streamKey update it.

Stats

Stats Live Activity stream example

activitysmith.LiveActivities.Stream(
	"sales-hourly",
	activitysmithsdk.LiveActivityStreamInput{
		Title:    "Sales",
		Subtitle: "last hour",
		Type:     "stats",
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("Revenue", "$2430", activitysmithsdk.MetricColor("blue")),
			activitysmithsdk.Metric("Orders", "37", activitysmithsdk.MetricColor("green")),
			activitysmithsdk.Metric("Conversion", "4.8%", activitysmithsdk.MetricColor("magenta")),
			activitysmithsdk.Metric("Avg Order", "$65.68", activitysmithsdk.MetricColor("yellow")),
			activitysmithsdk.Metric("Refunds", "$84", activitysmithsdk.MetricColor("red")),
			activitysmithsdk.Metric("New Buyers", "18", activitysmithsdk.MetricColor("cyan")),
		},
	},
)

Metrics

Metrics Live Activity stream example

activitysmith.LiveActivities.Stream(
	"prod-web-1",
	activitysmithsdk.LiveActivityStreamInput{
		Title:    "Server Health",
		Subtitle: "prod-web-1",
		Type:     "metrics",
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("CPU", 9, activitysmithsdk.MetricUnit("%")),
			activitysmithsdk.Metric("MEM", 45, activitysmithsdk.MetricUnit("%")),
		},
	},
)

Segmented Progress

Segmented Progress Live Activity stream example

activitysmith.LiveActivities.Stream(
	"nightly-backup",
	activitysmithsdk.LiveActivityStreamInput{
		Title:         "Nightly Backup",
		Subtitle:      "upload archive",
		Type:          "segmented_progress",
		NumberOfSteps: 3,
		CurrentStep:   2,
	},
)

Progress

Progress Live Activity stream example

activitysmith.LiveActivities.Stream(
	"search-reindex",
	activitysmithsdk.LiveActivityStreamInput{
		Title:      "Search Reindex",
		Subtitle:   "catalog-v2",
		Type:       "progress",
		Percentage: 42,
	},
)

Alert

Alert Live Activity stream example

activitysmith.LiveActivities.Stream(
	"customer-ops",
	activitysmithsdk.LiveActivityStreamInput{
		Title:   "Reactivation",
		Message: "Lumen came back after 2 weeks",
		Type:    activitysmithsdk.LiveActivityTypeAlert,
		Icon:    activitysmithsdk.AlertIcon("cloud.sun", "yellow"),
		Badge:   activitysmithsdk.AlertBadge("Customer", "magenta"),
	},
)

Timer

Timer Live Activity stream example

activitysmith.LiveActivities.Stream(
	"benchmark-run",
	activitysmithsdk.LiveActivityStreamInput{
		Title:           "Benchmark Run",
		Subtitle:        "sampling",
		Type:            "timer",
		DurationSeconds: 300,
		Color:           "cyan",
	},
)

For a countdown, send DurationSeconds. You can update Title, Subtitle, Color, or any other visible field as the work changes. Leave DurationSeconds out unless you want to change the timer. To start at 00:00 and count up, set CountsDown to false and leave out DurationSeconds.

End Live Activity

Call EndStream(...) with the same streamKey to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set AutoDismissMinutes to choose a different dismissal time, including 0 for immediate dismissal.

activitysmith.LiveActivities.EndStream(
	"prod-web-1",
	activitysmithsdk.LiveActivityStreamEndInput{
		Title:    "Server Health",
		Subtitle: "prod-web-1",
		Type:     "metrics",
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("CPU", 7, activitysmithsdk.MetricUnit("%")),
			activitysmithsdk.Metric("MEM", 38, activitysmithsdk.MetricUnit("%")),
		},
		AutoDismissMinutes: 2,
	},
)

Icons and Badges

Add more context to Live Activities with icons and badges.

Icon

Supported Live Activity types: stats, metrics, progress, segmented_progress, alert, and timer.

activitysmith.LiveActivities.Stream(
	"prod-web-1",
	activitysmithsdk.LiveActivityStreamInput{
		Title:    "Server Health",
		Subtitle: "prod-web-1",
		Type:     "metrics",
		Icon:     activitysmithsdk.AlertIcon("server.rack", "blue"),
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("CPU", 18, activitysmithsdk.MetricUnit("%")),
			activitysmithsdk.Metric("MEM", 42, activitysmithsdk.MetricUnit("%")),
		},
	},
)

The Icon symbol value is an Apple SF Symbol name. Browse the catalog with one of these tools:

ActivitySmith app - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
SF Symbols - Apple’s official macOS app
Interactful - free third-party iOS app listing all SF Symbols under Foundations -> Iconography

Badge

Badges are supported by alert, progress, and segmented_progress Live Activities.

activitysmith.LiveActivities.Stream(
	"nightly-database-backup",
	activitysmithsdk.LiveActivityStreamInput{
		Title:      "Nightly Database Backup",
		Subtitle:   "verify restore",
		Type:       "progress",
		Badge:      activitysmithsdk.AlertBadge("S3", "cyan"),
		Percentage: 62,
	},
)

Live Activity Colors

Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge: lime, green, cyan, blue, purple, magenta, red, orange, yellow, gray

Live Activity Action

Live Activities can include one optional action button.

open_url: open an HTTPS URL.
open_url with a shortcuts://run-shortcut?name=... URL: run a specific iPhone Shortcut, for example to open an app.
webhook: trigger a backend GET/POST workflow.

Live Activity with action button

Open URL action

activitysmith.LiveActivities.Stream(
	"prod-web-1",
	activitysmithsdk.LiveActivityStreamInput{
		Title:    "Server Health",
		Subtitle: "prod-web-1",
		Type:     "metrics",
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("CPU", 76, activitysmithsdk.MetricUnit("%")),
			activitysmithsdk.Metric("MEM", 52, activitysmithsdk.MetricUnit("%")),
		},
		Action: &activitysmithsdk.LiveActivityActionInput{
			Title: "Dashboard",
			Type:  "open_url",
			URL:   "https://status.example.com/servers/prod-web-1",
		},
	},
)

Apple Shortcut action

activitysmith.LiveActivities.Stream(
	"prod-web-1",
	activitysmithsdk.LiveActivityStreamInput{
		Title:    "Server Health",
		Subtitle: "prod-web-1",
		Type:     "metrics",
		Metrics: []activitysmithsdk.ActivityMetric{
			activitysmithsdk.Metric("CPU", 76, activitysmithsdk.MetricUnit("%")),
			activitysmithsdk.Metric("MEM", 52, activitysmithsdk.MetricUnit("%")),
		},
		Action: &activitysmithsdk.LiveActivityActionInput{
			Title: "Chat with Jarvis",
			Type:  "open_url",
			URL:   "shortcuts://run-shortcut?name=Jarvis",
		},
	},
)

Webhook action

activitysmith.LiveActivities.Stream(
	"search-reindex",
	activitysmithsdk.LiveActivityStreamInput{
		Title:         "Reindexing product search",
		Subtitle:      "Shard 7 of 12",
		Type:          "segmented_progress",
		NumberOfSteps: 12,
		CurrentStep:   7,
		Action: &activitysmithsdk.LiveActivityActionInput{
			Title:  "Pause Reindex",
			Type:   "webhook",
			URL:    "https://ops.example.com/hooks/search/reindex/pause",
			Method: "POST",
			Body: map[string]interface{}{
				"job_id":       "reindex-2026-03-19",
				"requested_by": "activitysmith-go",
			},
		},
	},
)

Channels

Target specific channels when sending a push notification or streaming a Live Activity.

activitysmith.Notifications.Send(activitysmithsdk.PushNotificationInput{
	Title:    "New subscription 💸",
	Message:  "Customer upgraded to Pro plan",
	Channels: []string{"ios-builds", "engineering"},
})

activitysmith.LiveActivities.Stream(
	"nightly-backup",
	activitysmithsdk.LiveActivityStreamInput{
		Title:         "Nightly database backup",
		NumberOfSteps: 3,
		CurrentStep:   1,
		Type:          "segmented_progress",
		Channels:      []string{"ios-builds"},
	},
)

Widgets

Lock screen widgets

ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the web app, then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.

Use the metric key to update its value.

_, err := activitysmith.Metrics.Update("deploy.success_rate", 99.9)
if err != nil {
	log.Fatal(err)
}

String metric values work too.

_, err = activitysmith.Metrics.Update("prod.status", "healthy")
if err != nil {
	log.Fatal(err)
}

Error Handling

SDK calls return response, err, so check err after every call.

Additional Resources

Source Code

View the Go SDK source on GitHub

​Installation

​Usage

​Send a Push Notification

​Rich Push Notifications with Media

​Actionable Push Notifications

​Live Activities

​Start & Update Live Activity

​Stats

​Metrics

​Segmented Progress

​Progress

​Alert

​Timer

​End Live Activity

​Icons and Badges

​Icon

​Badge

​Live Activity Colors

​Live Activity Action

​Open URL action

​Apple Shortcut action

​Webhook action

​Channels

​Widgets

​Error Handling

​Additional Resources