{"id":10005,"library":"onesignal-python-api","title":"OneSignal Python API Client","description":"The `onesignal-python-api` library is the official Python client for the OneSignal Push Notification API. It enables developers to programmatically send push notifications, manage users and segments, and interact with other OneSignal services. The current stable version is 5.3.0, and the library generally maintains a monthly or bi-monthly release cadence, with major versions often introducing significant API changes.","status":"active","version":"5.3.0","language":"en","source_language":"en","source_url":"https://github.com/OneSignal/onesignal-python-api","tags":["OneSignal","push notifications","API client","notifications","marketing"],"install":[{"cmd":"pip install onesignal-python-api","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The package name and import structure changed significantly in v4.x and v5.x. The current convention is to import `onesignal` and alias it, then access `Client` via `os_client.Client`.","wrong":"from onesignal_sdk.client import Client","symbol":"Client","correct":"import onesignal as os_client"},{"note":"Specific exception for API-related errors, useful for error handling.","symbol":"OneSignalAPIError","correct":"from onesignal.exceptions import OneSignalAPIError"}],"quickstart":{"code":"import os\nimport onesignal as os_client\nfrom onesignal.exceptions import OneSignalAPIError\n\n# Initialize the OneSignal client using environment variables for credentials\n# Replace 'YOUR_APP_ID' and 'YOUR_REST_API_KEY' with actual values or set environment variables.\napp_id = os.environ.get(\"ONESIGNAL_APP_ID\", \"YOUR_APP_ID\")\nrest_api_key = os.environ.get(\"ONESIGNAL_REST_API_KEY\", \"YOUR_REST_API_KEY\")\n\n# Basic check for placeholder credentials\nif app_id == \"YOUR_APP_ID\" or rest_api_key == \"YOUR_REST_API_KEY\":\n    print(\"WARNING: Please set ONESIGNAL_APP_ID and ONESIGNAL_REST_API_KEY environment variables \")\n    print(\"         or replace placeholders for successful API calls.\")\n\ntry:\n    client = os_client.Client(\n        app_id=app_id,\n        rest_api_key=rest_api_key\n    )\n\n    # Example 1: Send a basic notification to all subscribed users\n    notification_body = {\n        \"contents\": {\"en\": \"Hello from the OneSignal Python API client!\"},\n        \"included_segments\": [\"All\"],\n        \"name\": \"Python Test Notification\" # Optional, for internal tracking\n    }\n    print(\"\\nAttempting to send a notification...\")\n    notification = client.send_notification(notification_body)\n    print(f\"Notification created successfully. ID: {notification.id}\")\n\n    # Example 2: Get details for the app (requires appropriate API key permissions)\n    print(\"\\nAttempting to retrieve app details...\")\n    app_details = client.get_app(app_id)\n    print(f\"Successfully fetched app '{app_details.name}' (ID: {app_details.id})\")\n\nexcept OneSignalAPIError as e:\n    print(f\"\\nOneSignal API Error: {e.status_code} - {e.json_body}\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the OneSignal client using environment variables for credentials and then send a simple notification to all users. It also includes an example of fetching app details. Remember to set `ONESIGNAL_APP_ID` and `ONESIGNAL_REST_API_KEY` in your environment or replace the placeholders."},"warnings":[{"fix":"Review the official v5.x documentation and examples thoroughly. Your code for client initialization, notification creation, and other API calls will likely need to be completely refactored.","message":"Version 5.0.0 (February 2024) introduced a complete rewrite of the API client to comply with OneSignal's OpenAPI specification. This involved significant changes to most methods, model structures, and how parameters are passed.","severity":"breaking","affected_versions":">=5.0.0 (from 4.x or earlier)"},{"fix":"Update method calls from `client.create_notification(...)` to `client.send_notification(...)` and adjust argument structures according to the v4.x documentation.","message":"Version 4.0.0 (May 2023) introduced breaking changes to the `Client` and `Notification` APIs, most notably renaming `create_notification` to `send_notification` and altering parameters.","severity":"breaking","affected_versions":">=4.0.0 (from 3.x)"},{"fix":"Ensure you are using the correct API key type for your intended operation. For sending notifications, use `rest_api_key`. Consult the OneSignal dashboard for correct key types.","message":"Confusion between `rest_api_key` and `user_auth_key` for client initialization. `rest_api_key` is typically used for sending notifications and app-level operations, while `user_auth_key` is for specific authenticated user management actions (e.g., exporting user data). Using the wrong key will result in authentication errors or permission denied responses.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"First, uninstall the old package: `pip uninstall onesignal_sdk`. Then, install the current package: `pip install onesignal-python-api`. Finally, update your imports to `import onesignal as os_client`.","cause":"You are trying to import from the old `onesignal_sdk` package which was used in versions prior to v4.0.0. The package name changed to `onesignal-python-api` and the import path changed.","error":"ModuleNotFoundError: No module named 'onesignal_sdk'"},{"fix":"Consult the current documentation for `send_notification`. Ensure your `notification_body` dictionary uses `contents` (a dictionary of language codes to strings) and other fields as direct keys, e.g., `{'contents': {'en': 'Message'}, 'included_segments': ['All']}`.","cause":"You are passing notification data using an old keyword argument (e.g., `data`, `contents_en`) that is no longer supported or has changed structure in v4.x or v5.x. The new API expects a dictionary for `notification_body` with `contents` as a dictionary, and other top-level keys.","error":"TypeError: send_notification() got an unexpected keyword argument 'data'"},{"fix":"Double-check your OneSignal dashboard for the correct App ID. Ensure it's passed as a string during client initialization, e.g., `client = os_client.Client(app_id='YOUR_CORRECT_APP_ID', ...)`.","cause":"The `app_id` provided during client initialization is incorrect, malformed, or does not exist on your OneSignal account.","error":"OneSignalAPIError: 400 Bad Request - {'errors': ['App id not found.']}"},{"fix":"Verify your REST API Key from your OneSignal dashboard. Ensure it is correctly passed as a string to the `rest_api_key` parameter during client initialization. Also, confirm that the key has the required permissions for the API calls you are making.","cause":"The `rest_api_key` provided during client initialization is incorrect or missing, or lacks the necessary permissions for the requested operation.","error":"OneSignalAPIError: 401 Unauthorized - {'errors': ['REST API Key not found.']}"}]}