> ## Documentation Index
> Fetch the complete documentation index at: https://activitysmith.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Go
> Use the ActivitySmith Go SDK to send push notifications and Live Activity progress updates from Go services, workers, and automation jobs.
## Installation
Install the ActivitySmith Go SDK with `go get`:
```go Go theme={null} theme={null}
go get github.com/ActivitySmithHQ/activitysmith-go
```
## Usage
1. [Create an API key](https://activitysmith.com/app/keys)
2. Pass the API key into `activitysmithsdk.New`.
3. Reuse the client anywhere you send pushes or Live Activity updates.
Create the client once:
```go Go theme={null}
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.
```go Go theme={null}
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
```go Go theme={null}
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.
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
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.
```go Go theme={null}
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
```go theme={null}
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
```go theme={null}
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
```go theme={null}
activitysmith.LiveActivities.Stream(
"nightly-backup",
activitysmithsdk.LiveActivityStreamInput{
Title: "Nightly Backup",
Subtitle: "upload archive",
Type: "segmented_progress",
NumberOfSteps: 3,
CurrentStep: 2,
},
)
```
#### Progress
```go theme={null}
activitysmith.LiveActivities.Stream(
"search-reindex",
activitysmithsdk.LiveActivityStreamInput{
Title: "Search Reindex",
Subtitle: "catalog-v2",
Type: "progress",
Percentage: 42,
},
)
```
#### Alert
```go theme={null}
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
```go theme={null}
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.
```go theme={null}
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`.
```go theme={null}
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](https://apps.apple.com/us/app/activitysmith/id6752254835) - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
* [SF Symbols](https://developer.apple.com/sf-symbols/) - Apple's official macOS app
* [Interactful](https://apps.apple.com/app/interactful/id1528095640) - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
#### Badge
Badges are supported by `alert`, `progress`, and `segmented_progress` Live Activities.
```go theme={null}
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 an 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.
#### Open URL action
```go theme={null}
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
```go theme={null}
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
```go theme={null}
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",
},
},
},
)
```
#### Secondary action
Use `secondary_action` when you want a second button beside the primary `action`.
The secondary action button is supported for `alert`, `progress`, and `segmented_progress` Live Activities. Both buttons use the same `open_url`, `webhook`, and Apple Shortcut payload shapes.
```go theme={null}
activitysmith.LiveActivities.Stream(
"agent-approval",
activitysmithsdk.LiveActivityStreamInput{
Title: "Approval Needed",
Message: "Should I send the follow-up email to Brightlane?",
Type: "alert",
Color: "green",
Icon: activitysmithsdk.AlertIcon("sparkles", "green"),
Badge: activitysmithsdk.AlertBadge("Agent", "green"),
Action: &activitysmithsdk.LiveActivityActionInput{
Title: "Send",
Type: "webhook",
URL: "https://agent.example.com/live-activity/approve",
Method: "POST",
Body: map[string]interface{}{
"approval_id": "approval_01JY3J7Q9S0P8M1V5PZK7DR4M2",
"decision": "send",
},
},
SecondaryAction: &activitysmithsdk.LiveActivityActionInput{
Title: "Deny",
Type: "webhook",
URL: "https://agent.example.com/live-activity/deny",
Method: "POST",
Body: map[string]interface{}{
"approval_id": "approval_01JY3J7Q9S0P8M1V5PZK7DR4M2",
"decision": "deny",
},
},
},
)
```
## Channels
Target specific channels when sending a push notification or streaming a Live Activity.
```go Go theme={null}
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
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.
```go theme={null}
_, err := activitysmith.Metrics.Update("deploy.success_rate", 99.9)
if err != nil {
log.Fatal(err)
}
```
String metric values work too.
```go theme={null}
_, 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
View the Go SDK source on GitHub