> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal

> Connect OneSignal to your Atako agents — 8 read and 3 write actions.

Let your agents send push notifications, emails and SMS through OneSignal to segments or to specific users, follow and cancel messages, and read your segments, templates and users (and update user tags).

## Connection

* **Authentication**: API key (App API key).

<Note>
  OneSignal dashboard → select your app → Settings (gear icon, bottom-left of the sidebar) → Keys & IDs → Add Key. Name it, leave the IP allowlist empty (otherwise calls from Atako are refused), click Create and copy the value right away (it starts with os\_v2\_app\_ and is shown only once). A key works for one app: the App ID shown on the same page is required by every action — put it in the agent's instructions.

  See [OneSignal's documentation](https://documentation.onesignal.com/docs/en/keys-and-ids).
</Note>

## Read actions (8)

| Action | Description |
| - | - |
| `get_app` | Get one app: name, organization\_id, subscription counts (players, messageable\_players), enabled channels and push configuration. Push credentials (keys, certificates, passwords) are removed from the response. view: "config" skips the subscription counts (faster). |
| `get_message` | Get one message (push, email or SMS): content, targeting, schedule, status (canceled, completed\_at) and delivery statistics (successful, failed, errored, converted, received, remaining, platform\_delivery\_stats per channel). |
| `get_template` | Get one message template: its content, target channel and timestamps. |
| `get_user` | Get a user by alias: properties (tags, language, timezone\_id, country, first/last active), identity (all aliases) and subscriptions (push, email, SMS). alias\_label: "external\_id" (your own user id — the usual choice), "onesignal\_id" or a custom alias label; alias\_id: its value. |
| `list_apps` | List the apps of the OneSignal organization (id = App ID, name, subscription counts). Requires an Organization API key: with an App API key OneSignal answers 403 — the App ID is then on Settings → Keys & IDs. Push credentials (keys, certificates) are removed from the response. |
| `list_messages` | List the app's messages, newest first (queued\_at), with their content, targeting, schedule and delivery counts (successful, failed, errored, converted, remaining). limit: max 50 (default 50); offset: integer; kind: 0 = created in the dashboard, 1 = via the API, 3 = automated; template\_id: only messages sent from this template; time\_offset: ISO 8601 date-time or the token returned by the previous page. |
| `list_segments` | List the app's segments (id, name, created\_at, is\_active), oldest first. The name is what create\_message takes in included\_segments. limit: max 300 (default 300); offset: integer. |
| `list_templates` | List the app's message templates (id, name, created\_at, updated\_at). channel: "push" \| "email" \| "sms" to filter; limit: max 50 (default 50); offset: integer. |

## Write actions (3)

| Action | Description |
| - | - |
| `cancel_message` | Cancel a scheduled message, or stop one still being sent. Args: app\_id (UUID string), message\_id (UUID string, from create\_message or list\_messages). OneSignal answers 400 when the message was already sent to everyone. |
| `create_message` | Send (or schedule) a push notification, an email or an SMS. Args: app\_id (UUID string); target\_channel ("push" \| "email" \| "sms"); exactly ONE targeting method: included\_segments (array of segment name strings, e.g. \["Active Subscriptions"], see list\_segments; optional excluded\_segments, array of strings) OR include\_aliases (object mapping an alias label to an array of strings, e.g. \{ "external\_id": \["user-42"] } — also "onesignal\_id" or a custom alias label; max 20,000 ids) OR include\_subscription\_ids (array of subscription id strings) OR include\_phone\_numbers (array of E.164 strings, sms only). Content — push and sms: contents (object language code → string, "en" required, e.g. \{ "en": "Hello", "fr": "Bonjour" }); push only: headings (same shape, title; must use the same languages as contents), subtitle (same shape, iOS), url (https string), data (object, custom data passed to the app). Email: email\_subject (string) and email\_body (HTML string), optional email\_from\_name, email\_from\_address, email\_reply\_to\_address, email\_preheader (strings). SMS: optional sms\_from (string, sender phone number or messaging service id). Alternatively template\_id (UUID string, see list\_templates) replaces contents / email\_subject / email\_body, with custom\_data (object) for its variables. Optional for all: send\_after (ISO 8601 date-time string, schedules the message), name (string, internal), idempotency\_key (UUID string, prevents duplicate sends on retry). Returns the message id (empty id = not sent) and invalid identifiers in errors. |
| `update_user_tags` | Add or update tags on a user (used for segmentation and personalization). Args: app\_id (UUID string); alias\_label (string: "external\_id", "onesignal\_id" or a custom alias label); alias\_id (string, its value); tags (flat object of string keys to string values, e.g. \{ "plan": "pro", "city": "Lyon" } — no arrays nor nested objects). Tags not listed are left unchanged; your OneSignal plan caps the number of tags per user. |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.

***

*Last reviewed against the provider API: September 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.