productivity
OneSignal Lua API for KosmoKrator Agents
Agent-facing Lua documentation and function reference for the OneSignal KosmoKrator integration.Lua Namespace
Agents call this integration through app.integrations.one_signal.*.
Use lua_read_doc("integrations.one-signal") inside KosmoKrator to discover the same reference at runtime.
Call Lua from the Headless CLI
Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic
OneSignal workflow without starting an interactive agent session.
kosmo integrations:lua --eval 'dump(app.integrations.one_signal.list_messages({app_id = "example_app_id", limit = 1, offset = 1}))' --jsonkosmo integrations:lua --eval 'print(docs.read("one-signal"))' --json
kosmo integrations:lua --eval 'print(docs.read("one-signal.list_messages"))' --jsonWorkflow file
Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.
local one_signal = app.integrations.one_signal
local result = one_signal.list_messages({app_id = "example_app_id", limit = 1, offset = 1})
dump(result)kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json Namespace note.
integrations:lua exposes app.integrations.one_signal, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.one_signal.default.* or app.integrations.one_signal.work.* when you configured named credential accounts.
MCP-only Lua
If the script only needs configured MCP servers and does not need OneSignal, use the narrower mcp:lua command.
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --jsonAgent-Facing Lua Docs
This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.
OneSignal Lua API
Namespace: app.integrations["one-signal"]
Use this integration for OneSignal messages, users, aliases, subscriptions, segments, templates, outcomes, apps, and legacy player records.
Messages
onesignal_list_notifications({ app_id, limit, offset, kind, template_id, time_offset })onesignal_get_notification({ id, app_id, outcome_names, outcome_time_range, outcome_platforms, outcome_attribution })onesignal_create_notification({ app_id, payload = {...} })onesignal_create_notification({ app_id, contents, headings, included_segments, url, data })onesignal_cancel_notification({ message_id, app_id })
Only one targeting method should be used per message: aliases, subscription IDs, segments, or filters.
Users And Aliases
onesignal_create_user({ app_id, payload = {...} })onesignal_get_user({ app_id, alias_label, alias_id })onesignal_update_user({ app_id, alias_label, alias_id, payload = {...} })onesignal_delete_user({ app_id, alias_label, alias_id })onesignal_get_user_identity({ app_id, alias_label, alias_id })onesignal_create_or_update_alias({ app_id, alias_label, alias_id, identity = {...} })onesignal_delete_alias({ app_id, alias_label, alias_id, alias_label_to_delete })
Use external_id as the primary alias_label when possible.
Subscriptions
onesignal_get_identity_by_subscription({ app_id, subscription_id })onesignal_create_alias_by_subscription({ app_id, subscription_id, identity = {...} })onesignal_create_subscription({ app_id, alias_label, alias_id, payload = {...} })onesignal_update_subscription({ app_id, subscription_id, payload = {...} })onesignal_transfer_subscription({ app_id, subscription_id, identity = {...} })
Subscriptions represent the actual delivery channel: push, email, SMS, and related channel-specific properties.
Segments
onesignal_list_segments({ app_id, limit, offset })onesignal_get_segment({ app_id, segment_id, ["include-segment-detail"] = true })onesignal_create_segment({ app_id, payload = {...} })onesignal_update_segment({ app_id, segment_id, payload = {...} })onesignal_delete_segment({ app_id, segment_id })
Segment filters use the same format as OneSignal’s create/update segment API. User-based segments containing unsupported dashboard-only filters cannot be managed through the public API.
Templates
onesignal_list_templates({ app_id, limit, offset })onesignal_get_template({ app_id, template_id })onesignal_create_template({ app_id, payload = {...} })onesignal_update_template({ app_id, template_id, payload = {...} })onesignal_delete_template({ app_id, template_id })
Templates can be push, email, or SMS. Pass the documented template body through payload.
Analytics, Apps, Legacy Devices, Raw API
onesignal_view_outcomes({ app_id, outcome_names, outcome_time_range, outcome_platforms, outcome_attribution })onesignal_list_apps({})onesignal_get_current_app({ app_id })onesignal_update_app({ app_id, payload = {...} })onesignal_list_devices({ app_id, limit, offset })onesignal_get_device({ id, app_id })onesignal_api_get({ path, params })onesignal_api_post({ path, payload })onesignal_api_patch({ path, payload })onesignal_api_delete({ path, payload })
App administration may require an Organization API key. Legacy device tools use the older player terminology and are kept for compatibility.
Examples
local message = app.integrations["one-signal"].onesignal_create_notification({
contents = { en = "Your report is ready." },
include_aliases = {
external_id = { "user-123" }
},
target_channel = "push"
})local user = app.integrations["one-signal"].onesignal_update_user({
alias_label = "external_id",
alias_id = "user-123",
payload = {
properties = {
tags = {
plan = "pro"
}
}
}
})local segment = app.integrations["one-signal"].onesignal_create_segment({
payload = {
name = "Active Pro Users",
filters = {
{ field = "tag", key = "plan", relation = "=", value = "pro" },
{ operator = "AND" },
{ field = "session_count", relation = ">", value = "5" }
}
}
})Raw agent markdown
# OneSignal Lua API
Namespace: `app.integrations["one-signal"]`
Use this integration for OneSignal messages, users, aliases, subscriptions, segments, templates, outcomes, apps, and legacy player records.
## Messages
- `onesignal_list_notifications({ app_id, limit, offset, kind, template_id, time_offset })`
- `onesignal_get_notification({ id, app_id, outcome_names, outcome_time_range, outcome_platforms, outcome_attribution })`
- `onesignal_create_notification({ app_id, payload = {...} })`
- `onesignal_create_notification({ app_id, contents, headings, included_segments, url, data })`
- `onesignal_cancel_notification({ message_id, app_id })`
Only one targeting method should be used per message: aliases, subscription IDs, segments, or filters.
## Users And Aliases
- `onesignal_create_user({ app_id, payload = {...} })`
- `onesignal_get_user({ app_id, alias_label, alias_id })`
- `onesignal_update_user({ app_id, alias_label, alias_id, payload = {...} })`
- `onesignal_delete_user({ app_id, alias_label, alias_id })`
- `onesignal_get_user_identity({ app_id, alias_label, alias_id })`
- `onesignal_create_or_update_alias({ app_id, alias_label, alias_id, identity = {...} })`
- `onesignal_delete_alias({ app_id, alias_label, alias_id, alias_label_to_delete })`
Use `external_id` as the primary `alias_label` when possible.
## Subscriptions
- `onesignal_get_identity_by_subscription({ app_id, subscription_id })`
- `onesignal_create_alias_by_subscription({ app_id, subscription_id, identity = {...} })`
- `onesignal_create_subscription({ app_id, alias_label, alias_id, payload = {...} })`
- `onesignal_update_subscription({ app_id, subscription_id, payload = {...} })`
- `onesignal_transfer_subscription({ app_id, subscription_id, identity = {...} })`
Subscriptions represent the actual delivery channel: push, email, SMS, and related channel-specific properties.
## Segments
- `onesignal_list_segments({ app_id, limit, offset })`
- `onesignal_get_segment({ app_id, segment_id, ["include-segment-detail"] = true })`
- `onesignal_create_segment({ app_id, payload = {...} })`
- `onesignal_update_segment({ app_id, segment_id, payload = {...} })`
- `onesignal_delete_segment({ app_id, segment_id })`
Segment filters use the same format as OneSignal's create/update segment API. User-based segments containing unsupported dashboard-only filters cannot be managed through the public API.
## Templates
- `onesignal_list_templates({ app_id, limit, offset })`
- `onesignal_get_template({ app_id, template_id })`
- `onesignal_create_template({ app_id, payload = {...} })`
- `onesignal_update_template({ app_id, template_id, payload = {...} })`
- `onesignal_delete_template({ app_id, template_id })`
Templates can be push, email, or SMS. Pass the documented template body through `payload`.
## Analytics, Apps, Legacy Devices, Raw API
- `onesignal_view_outcomes({ app_id, outcome_names, outcome_time_range, outcome_platforms, outcome_attribution })`
- `onesignal_list_apps({})`
- `onesignal_get_current_app({ app_id })`
- `onesignal_update_app({ app_id, payload = {...} })`
- `onesignal_list_devices({ app_id, limit, offset })`
- `onesignal_get_device({ id, app_id })`
- `onesignal_api_get({ path, params })`
- `onesignal_api_post({ path, payload })`
- `onesignal_api_patch({ path, payload })`
- `onesignal_api_delete({ path, payload })`
App administration may require an Organization API key. Legacy device tools use the older player terminology and are kept for compatibility.
## Examples
```lua
local message = app.integrations["one-signal"].onesignal_create_notification({
contents = { en = "Your report is ready." },
include_aliases = {
external_id = { "user-123" }
},
target_channel = "push"
})
```
```lua
local user = app.integrations["one-signal"].onesignal_update_user({
alias_label = "external_id",
alias_id = "user-123",
payload = {
properties = {
tags = {
plan = "pro"
}
}
}
})
```
```lua
local segment = app.integrations["one-signal"].onesignal_create_segment({
payload = {
name = "Active Pro Users",
filters = {
{ field = "tag", key = "plan", relation = "=", value = "pro" },
{ operator = "AND" },
{ field = "session_count", relation = ">", value = "5" }
}
}
})
```local result = app.integrations.one_signal.list_messages({app_id = "example_app_id", limit = 1, offset = 1})
print(result)Functions
list_messages Read
List push notifications sent through OneSignal. Returns notification details including delivery stats, click counts, and outcomes. Use limit and offset for pagination.
- Lua path
app.integrations.one_signal.list_messages- Full name
one-signal.onesignal_list_notifications
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | yes | The OneSignal app ID to list notifications for. |
limit | integer | no | Maximum number of notifications to return (default: 50, max: 50). |
offset | integer | no | Offset for pagination (default: 0). |
get_message Read
Get details of a specific OneSignal push notification by its ID. Returns full notification data including content, delivery stats, and targeting.
- Lua path
app.integrations.one_signal.get_message- Full name
one-signal.onesignal_get_notification
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The notification ID to retrieve. |
app_id | string | yes | The OneSignal app ID the notification belongs to. |
create_message Write
Send a new push notification via OneSignal. Specify message contents (per language), optional headings, target segments, a click URL, and a custom data payload.
- Lua path
app.integrations.one_signal.create_message- Full name
one-signal.onesignal_create_notification
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | yes | The OneSignal app ID to send the notification from. |
payload | object | no | Full message payload. If provided, it is sent directly with app_id. |
contents | object | yes | Notification body per language, e.g. {"en": "Hello!", "es": "Hola!"}. The "en" key is required. |
headings | object | no | Notification title per language, e.g. {"en": "Update"}. Defaults to the app name if omitted. |
included_segments | array | no | Segments to target, e.g. ["All", "Active Users"]. Defaults to ["All"] if omitted. |
url | string | no | URL to open when the notification is tapped. |
data | object | no | Custom key-value data payload delivered to the app when the notification is opened. |
cancel_message Write
Cancel a scheduled or currently outgoing OneSignal message by ID.
- Lua path
app.integrations.one_signal.cancel_message- Full name
one-signal.onesignal_cancel_notification
| Parameter | Type | Required | Description |
|---|---|---|---|
message_id | string | yes | Message or notification ID. |
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
list_legacy_devices Read
List devices (players) registered in a OneSignal app. Returns device identifiers, platform, session counts, and tags. Use limit and offset for pagination.
- Lua path
app.integrations.one_signal.list_legacy_devices- Full name
one-signal.onesignal_list_devices
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | yes | The OneSignal app ID to list devices for. |
limit | integer | no | Maximum number of devices to return (default: 50, max: 300). |
offset | integer | no | Offset for pagination (default: 0). |
get_legacy_device Read
Get details of a specific OneSignal device (player) by its ID. Returns push token, platform, session data, tags, and more.
- Lua path
app.integrations.one_signal.get_legacy_device- Full name
one-signal.onesignal_get_device
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The device/player ID to retrieve. |
app_id | string | yes | The OneSignal app ID the device belongs to. |
list_apps Read
List all OneSignal apps accessible with the configured REST API key. Returns app names, IDs, player counts, and configuration.
- Lua path
app.integrations.one_signal.list_apps- Full name
one-signal.onesignal_list_apps
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_app Read
Get details of a specific OneSignal app by its ID. Returns app configuration, player counts, and platform settings.
- Lua path
app.integrations.one_signal.get_app- Full name
one-signal.onesignal_get_current_app
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | yes | The OneSignal app ID to retrieve. |
update_app Write
Update app configuration. This may require an organization-scoped API key.
- Lua path
app.integrations.one_signal.update_app- Full name
one-signal.onesignal_update_app
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
payload | object | yes | App update payload. |
create_user Write
Create a OneSignal user with optional identity aliases, properties, and subscriptions.
- Lua path
app.integrations.one_signal.create_user- Full name
one-signal.onesignal_create_user
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
payload | object | yes | User payload containing identity, properties, and/or subscriptions. |
get_user Read
View a OneSignal user by alias, such as external_id or onesignal_id.
- Lua path
app.integrations.one_signal.get_user- Full name
one-signal.onesignal_get_user
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Alias label, usually external_id or onesignal_id. |
alias_id | string | yes | Alias value. |
update_user Write
Update user-level properties or deltas for a OneSignal user located by alias.
- Lua path
app.integrations.one_signal.update_user- Full name
one-signal.onesignal_update_user
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Alias label. |
alias_id | string | yes | Alias value. |
payload | object | yes | User update payload with properties and/or deltas. |
delete_user Write
Delete a OneSignal user and all associated subscriptions by alias.
- Lua path
app.integrations.one_signal.delete_user- Full name
one-signal.onesignal_delete_user
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Alias label. |
alias_id | string | yes | Alias value. |
get_user_identity Read
Fetch the identity aliases for a OneSignal user located by alias.
- Lua path
app.integrations.one_signal.get_user_identity- Full name
one-signal.onesignal_get_user_identity
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Alias label. |
alias_id | string | yes | Alias value. |
create_or_update_alias Write
Create or update one or more identity aliases for a OneSignal user.
- Lua path
app.integrations.one_signal.create_or_update_alias- Full name
one-signal.onesignal_create_or_update_alias
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Known alias label. |
alias_id | string | yes | Known alias value. |
identity | object | yes | Aliases to add or update. |
delete_alias Write
Remove a specific alias from a OneSignal user without deleting the user.
- Lua path
app.integrations.one_signal.delete_alias- Full name
one-signal.onesignal_delete_alias
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Known alias label. |
alias_id | string | yes | Known alias value. |
alias_label_to_delete | string | yes | Alias label to remove. |
get_identity_by_subscription Read
Fetch the user identity aliases associated with a subscription ID.
- Lua path
app.integrations.one_signal.get_identity_by_subscription- Full name
one-signal.onesignal_get_identity_by_subscription
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
subscription_id | string | yes | Subscription ID. |
create_alias_by_subscription Write
Create or update aliases for the user associated with a known subscription ID.
- Lua path
app.integrations.one_signal.create_alias_by_subscription- Full name
one-signal.onesignal_create_alias_by_subscription
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
subscription_id | string | yes | Subscription ID. |
identity | object | yes | Aliases to add or update. |
create_subscription Write
Create a subscription for a user identified by alias.
- Lua path
app.integrations.one_signal.create_subscription- Full name
one-signal.onesignal_create_subscription
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
alias_label | string | yes | Alias label for the user. |
alias_id | string | yes | Alias value for the user. |
payload | object | yes | Subscription payload. |
update_subscription Write
Update a subscription by ID, such as tags, enabled state, or channel properties.
- Lua path
app.integrations.one_signal.update_subscription- Full name
one-signal.onesignal_update_subscription
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
subscription_id | string | yes | Subscription ID. |
payload | object | yes | Subscription update payload. |
transfer_subscription Write
Transfer a subscription to another user identity within the same app.
- Lua path
app.integrations.one_signal.transfer_subscription- Full name
one-signal.onesignal_transfer_subscription
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
subscription_id | string | yes | Subscription ID. |
identity | object | yes | Destination identity with exactly one alias. |
list_segments Read
List segments for an app with pagination.
- Lua path
app.integrations.one_signal.list_segments- Full name
one-signal.onesignal_list_segments
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
limit | integer | no | Maximum rows to return. |
offset | integer | no | Pagination offset. |
get_segment Read
Get a segment by ID and optionally include segment filters.
- Lua path
app.integrations.one_signal.get_segment- Full name
one-signal.onesignal_get_segment
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
segment_id | string | yes | Segment ID. |
include-segment-detail | boolean | no | Include segment metadata and filters. |
create_segment Write
Create a segment with name and filters.
- Lua path
app.integrations.one_signal.create_segment- Full name
one-signal.onesignal_create_segment
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
payload | object | yes | Segment payload with name and filters. |
update_segment Write
Update a segment name or filters.
- Lua path
app.integrations.one_signal.update_segment- Full name
one-signal.onesignal_update_segment
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
segment_id | string | yes | Segment ID. |
payload | object | yes | Segment update payload. |
delete_segment Write
Delete a segment by ID.
- Lua path
app.integrations.one_signal.delete_segment- Full name
one-signal.onesignal_delete_segment
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
segment_id | string | yes | Segment ID. |
list_templates Read
List message templates for an app with pagination.
- Lua path
app.integrations.one_signal.list_templates- Full name
one-signal.onesignal_list_templates
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
limit | integer | no | Maximum templates to return. |
offset | integer | no | Pagination offset. |
get_template Read
Get a message template by ID.
- Lua path
app.integrations.one_signal.get_template- Full name
one-signal.onesignal_get_template
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
template_id | string | yes | Template ID. |
create_template Write
Create a reusable push, email, or SMS template.
- Lua path
app.integrations.one_signal.create_template- Full name
one-signal.onesignal_create_template
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
payload | object | yes | Template payload. |
update_template Write
Update a reusable push, email, or SMS template.
- Lua path
app.integrations.one_signal.update_template- Full name
one-signal.onesignal_update_template
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
template_id | string | yes | Template ID. |
payload | object | yes | Template update payload. |
delete_template Write
Delete a message template by ID.
- Lua path
app.integrations.one_signal.delete_template- Full name
one-signal.onesignal_delete_template
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
template_id | string | yes | Template ID. |
view_outcomes Read
View outcome analytics such as clicks, confirmed deliveries, session duration, or custom outcomes.
- Lua path
app.integrations.one_signal.view_outcomes- Full name
one-signal.onesignal_view_outcomes
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | no | OneSignal App ID. Defaults to configured app_id. |
outcome_names | string | yes | Comma-separated outcome names such as os__click.count. |
outcome_time_range | string | no | Time range. |
outcome_platforms | string | no | Comma-separated platform IDs. |
outcome_attribution | string | no | Attribution type. |
api_get Read
Call a safe relative OneSignal API path with GET for endpoints not yet wrapped by a dedicated tool.
- Lua path
app.integrations.one_signal.api_get- Full name
one-signal.onesignal_api_get
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Relative API path such as /notifications. Absolute URLs are rejected. |
params | object | no | Query parameters. |
api_post Write
Call a safe relative OneSignal API path with POST for endpoints not yet wrapped by a dedicated tool.
- Lua path
app.integrations.one_signal.api_post- Full name
one-signal.onesignal_api_post
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Relative API path. Absolute URLs are rejected. |
payload | object | no | JSON payload. |
api_patch Write
Call a safe relative OneSignal API path with PATCH for endpoints not yet wrapped by a dedicated tool.
- Lua path
app.integrations.one_signal.api_patch- Full name
one-signal.onesignal_api_patch
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Relative API path. Absolute URLs are rejected. |
payload | object | no | JSON payload. |
api_delete Write
Call a safe relative OneSignal API path with DELETE for endpoints not yet wrapped by a dedicated tool.
- Lua path
app.integrations.one_signal.api_delete- Full name
one-signal.onesignal_api_delete
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Relative API path. Absolute URLs are rejected. |
payload | object | no | JSON payload. |