{ "openapi": "3.1.0", "info": { "title": "api.onesignal.com", "version": "11.6" }, "servers": [ { "url": "https://api.onesignal.com" } ], "components": { "schemas": { "BasicErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "One or more human-readable error messages." }, "success": { "type": "boolean", "description": "Present (and `false`) on some endpoints (notifications, templates, segments). Not emitted by every endpoint." }, "reference": { "type": "array", "items": { "type": "string" }, "description": "Documentation URL fragments related to the error. Only emitted by the API-key auth error helpers." } } }, "StructuredErrorItem": { "type": "object", "required": [ "code", "title" ], "properties": { "code": { "type": "string", "description": "Stable error-code identifier. Use this for programmatic branching in your integration." }, "title": { "type": "string", "description": "Human-readable error message intended for logs and operator-facing surfaces." }, "meta": { "type": "object", "additionalProperties": true, "description": "Optional structured details about this specific error. The shape of `meta` varies by `code` — for example, the create-user `Conflict` code returns `{ conflicting_aliases: { [alias_label]: alias_id } }`." } } }, "StructuredErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredErrorItem" } } } }, "ApiKeyToken": { "type": "object", "description": "An API Key Token record (Rich Authentication Token). Different operations return different subsets of these fields:\n\n- **GET tokens** lists every field except `formatted_token`.\n- **POST tokens** (create) returns `token_id` and `formatted_token`.\n- **POST tokens/{id}/rotate** returns `formatted_token` only.\n- **PATCH tokens/{id}** updates the record; the response body is currently empty (consumers should re-fetch via GET).\n\n`formatted_token` is the actual REST API Key and is shown ONCE — OneSignal does not store it. Keep it secret.", "properties": { "token_id": { "type": "string", "format": "uuid", "description": "OneSignal-generated identifier for this API key. NOT the API key itself — use this to manage the key in subsequent calls." }, "name": { "type": "string", "description": "Internal name set when the key was created or last updated. Maximum 128 characters." }, "ip_allowlist_mode": { "type": "string", "enum": [ "disabled", "explicit" ], "description": "When `explicit`, only requests from IP addresses matching `ip_allowlist` may use this key. Defaults to `disabled`." }, "ip_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Allowed CIDR ranges. Only enforced when `ip_allowlist_mode` is `explicit`." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the key was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the key was last updated." }, "formatted_token": { "type": "string", "description": "The actual Rich Authentication Token (REST API Key). Returned in plaintext ONLY by the create and rotate endpoints, and ONLY immediately after that call. OneSignal does not store the secret — if you lose it, you must rotate the key. See [Rotate API Key](/reference/rotate-api-key)." } } }, "TemplateResourceContent": { "type": "object", "description": "The content block of a template. Every field is nullable: a field is populated only when the corresponding channel feature is enabled for the template. For example, push fields (`isAndroid`, `isIos`, `headings`, ...) are populated for push templates; email fields (`isEmail`, `email_body`, ...) for email templates; and SMS fields (`isSMS`, `sms_from`, ...) for SMS templates. Cross-channel templates may have multiple feature blocks populated.", "properties": { "isAndroid": { "type": [ "boolean", "null" ] }, "isIos": { "type": [ "boolean", "null" ] }, "isMacOSX": { "type": [ "boolean", "null" ] }, "isAdm": { "type": [ "boolean", "null" ] }, "isAlexa": { "type": [ "boolean", "null" ] }, "isWP": { "type": [ "boolean", "null" ] }, "isWP_WNS": { "type": [ "boolean", "null" ] }, "isChrome": { "type": [ "boolean", "null" ] }, "isChromeWeb": { "type": [ "boolean", "null" ] }, "isSafari": { "type": [ "boolean", "null" ] }, "isFirefox": { "type": [ "boolean", "null" ] }, "isEdge": { "type": [ "boolean", "null" ] }, "isHuawei": { "type": [ "boolean", "null" ] }, "headings": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Map of language code to localized string. Keys are 2-letter ISO codes (e.g., `en`, `es`); values are the message text." }, "subtitle": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Map of language code to localized string. Keys are 2-letter ISO codes (e.g., `en`, `es`); values are the message text." }, "contents": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Map of language code to localized string. Keys are 2-letter ISO codes (e.g., `en`, `es`); values are the message text." }, "global_image": { "type": [ "string", "null" ], "description": "URL of the image to render with the push notification." }, "url": { "type": [ "string", "null" ], "description": "Click-action URL for push notifications.", "format": "uri" }, "isEmail": { "type": [ "boolean", "null" ] }, "email_body": { "type": [ "string", "null" ], "description": "HTML body of the email." }, "email_subject": { "type": [ "string", "null" ] }, "email_preheader": { "type": [ "string", "null" ] }, "email_from_address": { "type": [ "string", "null" ], "format": "email" }, "email_from_name": { "type": [ "string", "null" ] }, "email_reply_to_address": { "type": [ "string", "null" ], "format": "email" }, "email_bcc": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email" }, "maxItems": 5, "description": "BCC recipients for the email template. Maximum 5 addresses. Only supported when the email service provider is OneSignal Email." }, "disable_email_click_tracking": { "type": [ "boolean", "null" ] }, "isSMS": { "type": [ "boolean", "null" ] }, "sms_from": { "type": [ "string", "null" ], "description": "Sender phone number in E.164 format." }, "sms_media_urls": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri" }, "description": "Optional array of media URLs to attach to the SMS (MMS)." }, "huawei_badge_add_num": { "type": [ "integer", "null" ], "description": "Increment value for the Huawei badge counter." }, "huawei_badge_class": { "type": [ "string", "null" ], "description": "Activity class associated with the Huawei badge counter." }, "huawei_badge_set_num": { "type": [ "integer", "null" ], "description": "Absolute value to set the Huawei badge counter to." } } }, "TemplateResource": { "type": "object", "required": [ "id" ], "description": "A template record. The `content` block is a `TemplateResourceContent` whose populated fields depend on the template's channel(s).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Template ID in UUID v4 format." }, "name": { "type": "string", "description": "Internal label set when the template was created or last updated. Maximum 128 characters." }, "channel": { "type": "string", "enum": [ "push", "email", "SMS" ], "description": "The primary channel the template is configured for. Note: `SMS` is uppercased while the others are lowercased." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the template was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the template was last updated." }, "content": { "$ref": "#/components/schemas/TemplateResourceContent" } } }, "CreateUserConflictResponse": { "type": "object", "description": "Returned at HTTP 409 by POST `/apps/{app_id}/users` when the request's claimed identity (`aliases` or `external_id`) collides with an existing user. The structured meta block lists each colliding alias label and the alias ID that already identifies a different user.", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "code", "title" ], "properties": { "code": { "type": "string", "description": "Stable error code identifier. For this response: `Conflict`.", "example": "Conflict" }, "title": { "type": "string", "description": "Human-readable conflict description.", "example": "Conflicting aliases" }, "meta": { "type": "object", "description": "Structured details about the conflict.", "properties": { "conflicting_aliases": { "type": "object", "description": "Map of alias label to the alias ID that already identifies a different user. Use this to surface the specific conflict to the operator and decide whether to retry with a different alias.", "additionalProperties": { "type": "string" }, "example": { "external_id": "user-already-claimed-by-another-account", "amazon_id": "amzn-id-already-bound" } } } } } } } } } }, "securitySchemes": {} }, "security": [ {} ], "paths": { "/apps": { "x-mcp": { "enabled": true }, "get": { "summary": "View apps", "description": "Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.", "operationId": "view-apps", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\ntry {\n const response = await apiInstance.getApps();\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getApps failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n\n # example, this endpoint has no required or optional parameters\n try:\n # View apps\n api_response = api_instance.get_apps()\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_apps: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n\ntry {\n $result = $apiInstance->getApps();\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getApps: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getApps: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.GetApps(orgAuth).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetApps``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetApps`: []App\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetApps`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\n\nbegin\n # View apps\n result = api_instance.get_apps\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_apps: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport java.util.List;\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n try {\n List result = apiInstance.getApps();\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getApps\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetAppsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n\n try\n {\n // View apps\n List result = apiInstance.GetApps();\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetApps: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n match default_api::get_apps(&configuration).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_apps failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_apps failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The OneSignal App ID in UUID v4 format.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "type": "string" }, "players": { "description": "The total number of Subscriptions in the app.", "type": "integer" }, "messageable_players": { "description": "The number of Subscriptions eligible to receive messages in the app.", "type": "integer" }, "created_at": { "description": "The date and time the app was created.", "type": "string" }, "updated_at": { "description": "The date and time the app was last updated.", "type": "string" }, "organization_id": { "description": "The Organization ID in which the app was created.", "type": "string" } } } } } } }, "400": { "description": "Bad request. Returned when the account or organization has more than 1000 apps (this endpoint is disabled above that limit), or when the Authorization key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "This API endpoint is disabled for organizations with over 1000 apps. Please contact support if you need access to this endpoint." ] } } } }, "403": { "description": "Forbidden. The Authorization key does not have permission to list apps in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "You do not have permission to list apps." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "post": { "summary": "Create an app", "description": "Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.", "operationId": "create-an-app", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// App\nconst app: Onesignal.App = {\n name: \"name_example\",\n android_gcm_sender_id: \"android_gcm_sender_id_example\",\n gcm_key: \"gcm_key_example\",\n chrome_web_origin: \"chrome_web_origin_example\",\n chrome_key: \"chrome_key_example\",\n chrome_web_default_notification_icon: \"chrome_web_default_notification_icon_example\",\n chrome_web_sub_domain: \"chrome_web_sub_domain_example\",\n apns_env: \"sandbox\",\n apns_p12: \"apns_p12_example\",\n apns_p12_password: \"apns_p12_password_example\",\n safari_apns_p12: \"safari_apns_p12_example\",\n safari_apns_p12_password: \"safari_apns_p12_password_example\",\n apns_key_id: \"apns_key_id_example\",\n apns_team_id: \"apns_team_id_example\",\n apns_bundle_id: \"apns_bundle_id_example\",\n apns_p8: \"apns_p8_example\",\n safari_site_origin: \"safari_site_origin_example\",\n safari_icon_256_256: \"safari_icon_256_256_example\",\n site_name: \"site_name_example\",\n organization_id: \"organization_id_example\",\n additional_data_is_root_payload: true,\n };\n\ntry {\n const response = await apiInstance.createApp(app);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createApp failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app = App(\n name=\"name_example\",\n android_gcm_sender_id=\"android_gcm_sender_id_example\",\n gcm_key=\"gcm_key_example\",\n chrome_web_origin=\"chrome_web_origin_example\",\n chrome_key=\"chrome_key_example\",\n chrome_web_default_notification_icon=\"chrome_web_default_notification_icon_example\",\n chrome_web_sub_domain=\"chrome_web_sub_domain_example\",\n apns_env=\"sandbox\",\n apns_p12=\"apns_p12_example\",\n apns_p12_password=\"apns_p12_password_example\",\n safari_apns_p12=\"safari_apns_p12_example\",\n safari_apns_p12_password=\"safari_apns_p12_password_example\",\n apns_key_id=\"apns_key_id_example\",\n apns_team_id=\"apns_team_id_example\",\n apns_bundle_id=\"apns_bundle_id_example\",\n apns_p8=\"apns_p8_example\",\n safari_site_origin=\"safari_site_origin_example\",\n safari_icon_256_256=\"safari_icon_256_256_example\",\n site_name=\"site_name_example\",\n organization_id=\"organization_id_example\",\n additional_data_is_root_payload=True,\n ) \n\n try:\n # Create an app\n api_response = api_instance.create_app(app)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_app: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app = new \\onesignal\\client\\model\\App(); // \\onesignal\\client\\model\\App\n\ntry {\n $result = $apiInstance->createApp($app);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createApp: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createApp: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n app := *onesignal.NewApp() // App | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateApp(orgAuth).App(app).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateApp``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateApp`: App\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateApp`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp = OneSignal::App.new # App | \n\nbegin\n # Create an app\n result = api_instance.create_app(app)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_app: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n App app = new App(); // App | \n try {\n App result = apiInstance.createApp(app);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createApp\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateAppExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var app = new App(); // App | \n\n try\n {\n // Create an app\n App result = apiInstance.CreateApp(app);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateApp: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app: models::App = todo!();\n\n match default_api::create_app(&configuration, app).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_app failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_app failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "organization_id" ], "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "default": "NAME_OF_NEW_APP" }, "organization_id": { "type": "string", "description": "The [Organization ID](/docs/en/keys-and-ids#organization-id) that the app will be associated with.", "default": "YOUR_ORG_ID" }, "chrome_web_origin": { "type": "string", "description": "The HTTPS [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) URL for your website. Required for web push notifications." }, "site_name": { "type": "string", "description": "The name of your website. Used for web push notification titles when omitted from the notification payload. Required for web push notifications.", "default": "SITE_NAME" }, "safari_site_origin": { "type": "string", "description": "The HTTPS [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) URL for your website. Required for web push notifications for Safari and should be the same as `chrome_web_origin`." }, "chrome_web_default_notification_icon": { "type": "string", "description": "The full `https` URL to your default icon resource. The icon should be a `256x256px` PNG." }, "safari_icon_256_256": { "type": "string", "description": "The full `https` URL to your default icon resource. The icon should be a `256x256px` PNG." }, "safari_apns_p12": { "type": "string", "description": "A Base64 encoded p12 certificate for Safari Push Notifications. If omitted, we will assign one to your app for you." }, "safari_apns_p12_password": { "type": "string", "description": "The password for the `safari_apns_p12` file if applicable." }, "fcm_v1_service_account_json": { "type": "string", "description": "Your FCM Service Account JSON file converted to base64 format. See [Android: Firebase Credentials](/docs/android-firebase-credentials). Required for Android mobile push notifications." }, "apns_p8": { "type": "string", "description": "A Base64 encoded p8 file for iOS mobile Push Notifications. Omit if using `apns_p12`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_env": { "type": "string", "description": "The [APS Environment Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) to specify whether this is a `production` or `development` environment. Defaults to `production`. Use with `apns_p8`.", "enum": [ "production", "development" ] }, "apns_key_id": { "type": "string", "description": "The APNS Key ID. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_team_id": { "type": "string", "description": "The APNS Team ID. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_bundle_id": { "type": "string", "description": "The Bundle ID for your app. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_p12": { "type": "string", "description": "A Base64 encoded p12 certificate for iOS mobile push notifications. Omit if using `apns_p8`. See [p12 APNS Authentication](/docs/ios-p12-generate-certificates)." }, "apns_p12_password": { "type": "string", "description": "The password for the `apns_p12` file if applicable." }, "additional_data_is_root_payload": { "type": "boolean", "description": "If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/osnotification-payload).", "default": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The OneSignal App ID in UUID v4 format.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "type": "string" }, "players": { "description": "The total number of Subscriptions in the app.", "type": "integer" }, "messageable_players": { "description": "The number of Subscriptions eligible to receive messages in the app.", "type": "integer" }, "created_at": { "description": "The date and time the app was created.", "type": "string" }, "updated_at": { "description": "The date and time the app was last updated.", "type": "string" }, "organization_id": { "description": "The Organization ID in which the app was created.", "type": "string" } } } } } }, "403": { "description": "Forbidden. The Authorization key does not have permission to create an app under this organization, or the request violates the organization's policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "You do not have permission to create an app in this organization." ] } } } }, "404": { "description": "Either the referenced organization or the source app (when copying configuration) was not found, or your API key cannot reach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Organization not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}": { "get": { "summary": "View an app", "description": "View the details of a single OneSignal app", "operationId": "view-an-app", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | An app id\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n\ntry {\n const response = await apiInstance.getApp(appId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getApp failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # An app id \n\n try:\n # View an app\n api_response = api_instance.get_app(app_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_app: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | An app id\n\ntry {\n $result = $apiInstance->getApp($app_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getApp: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getApp: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | An app id\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetApp(restAuth, appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetApp``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetApp`: App\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetApp`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | An app id\n\nbegin\n # View an app\n result = api_instance.get_app(app_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_app: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | An app id\n try {\n App result = apiInstance.getApp(appId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getApp\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetAppExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | An app id\n\n try\n {\n // View an app\n App result = apiInstance.GetApp(appId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetApp: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n\n match default_api::get_app(&configuration, app_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_app failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_app failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The OneSignal App ID in UUID v4 format.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "type": "string" }, "players": { "description": "The total number of Subscriptions in the app.", "type": "integer" }, "messageable_players": { "description": "The number of Subscriptions eligible to receive messages in the app.", "type": "integer" }, "created_at": { "description": "The date and time the app was created.", "type": "string" }, "updated_at": { "description": "The date and time the app was last updated.", "type": "string" }, "organization_id": { "description": "The Organization ID in which the app was created.", "type": "string" }, "fcm_v1_service_account_json": { "description": "Your FCM Service Account JSON file for Android push notifications. See [Android: Firebase Credentials](/docs/android-firebase-credentials).", "type": "string" }, "fcm_sender_id": { "description": "The FCM Sender ID associated with your Firebase project.", "type": "string" }, "chrome_web_key": { "description": "Web push VAPID public key for Chrome web push notifications.", "type": "string" }, "chrome_web_origin": { "description": "The HTTPS origin URL for your website. Required for web push notifications.", "type": "string" }, "chrome_web_gcm_sender_id": { "description": "The GCM Sender ID used for web push notifications.", "type": "string" }, "chrome_web_default_notification_icon": { "description": "The full HTTPS URL to your default notification icon. Should be a 256x256px PNG.", "type": "string" }, "chrome_web_sub_domain": { "description": "The OneSignal subdomain for web push if not using your own origin.", "type": "string" }, "apns_env": { "description": "The APNS environment: `production` or `development`. See [iOS SDK Setup](/docs/ios-sdk-setup).", "type": "string" }, "apns_certificates": { "description": "The APNS p12 certificate for iOS push notifications. See [p12 APNS Authentication](/docs/ios-p12-generate-certificates).", "type": "string" }, "apns_p8": { "description": "The APNS p8 token key for iOS push notifications. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns).", "type": "string" }, "apns_team_id": { "description": "The Apple Team ID associated with your APNS credentials.", "type": "string" }, "apns_key_id": { "description": "The APNS Key ID for p8 token-based authentication.", "type": "string" }, "apns_bundle_id": { "description": "The iOS app Bundle ID associated with your APNS credentials.", "type": "string" }, "site_name": { "description": "The name of your website, used for web push notification titles.", "type": "string" } } } } } }, "403": { "description": "Forbidden. The Authorization key does not have permission to view this app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "You do not have permission to view this app." ] } } } }, "404": { "description": "App not found. Either the App ID is wrong or your API key cannot reach this app's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Couldn't find app with id = " ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "put": { "summary": "Update an app", "description": "Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules", "operationId": "update-an-app", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | An app id\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// App\nconst app: Onesignal.App = {\n name: \"name_example\",\n android_gcm_sender_id: \"android_gcm_sender_id_example\",\n gcm_key: \"gcm_key_example\",\n chrome_web_origin: \"chrome_web_origin_example\",\n chrome_key: \"chrome_key_example\",\n chrome_web_default_notification_icon: \"chrome_web_default_notification_icon_example\",\n chrome_web_sub_domain: \"chrome_web_sub_domain_example\",\n apns_env: \"sandbox\",\n apns_p12: \"apns_p12_example\",\n apns_p12_password: \"apns_p12_password_example\",\n safari_apns_p12: \"safari_apns_p12_example\",\n safari_apns_p12_password: \"safari_apns_p12_password_example\",\n apns_key_id: \"apns_key_id_example\",\n apns_team_id: \"apns_team_id_example\",\n apns_bundle_id: \"apns_bundle_id_example\",\n apns_p8: \"apns_p8_example\",\n safari_site_origin: \"safari_site_origin_example\",\n safari_icon_256_256: \"safari_icon_256_256_example\",\n site_name: \"site_name_example\",\n organization_id: \"organization_id_example\",\n additional_data_is_root_payload: true,\n };\n\ntry {\n const response = await apiInstance.updateApp(appId, app);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateApp failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # An app id \n app = App(\n name=\"name_example\",\n android_gcm_sender_id=\"android_gcm_sender_id_example\",\n gcm_key=\"gcm_key_example\",\n chrome_web_origin=\"chrome_web_origin_example\",\n chrome_key=\"chrome_key_example\",\n chrome_web_default_notification_icon=\"chrome_web_default_notification_icon_example\",\n chrome_web_sub_domain=\"chrome_web_sub_domain_example\",\n apns_env=\"sandbox\",\n apns_p12=\"apns_p12_example\",\n apns_p12_password=\"apns_p12_password_example\",\n safari_apns_p12=\"safari_apns_p12_example\",\n safari_apns_p12_password=\"safari_apns_p12_password_example\",\n apns_key_id=\"apns_key_id_example\",\n apns_team_id=\"apns_team_id_example\",\n apns_bundle_id=\"apns_bundle_id_example\",\n apns_p8=\"apns_p8_example\",\n safari_site_origin=\"safari_site_origin_example\",\n safari_icon_256_256=\"safari_icon_256_256_example\",\n site_name=\"site_name_example\",\n organization_id=\"organization_id_example\",\n additional_data_is_root_payload=True,\n ) \n\n try:\n # Update an app\n api_response = api_instance.update_app(app_id, app)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_app: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | An app id\n$app = new \\onesignal\\client\\model\\App(); // \\onesignal\\client\\model\\App\n\ntry {\n $result = $apiInstance->updateApp($app_id, $app);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateApp: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateApp: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | An app id\n app := *onesignal.NewApp() // App | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateApp(orgAuth, appId).App(app).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateApp``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateApp`: App\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateApp`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | An app id\napp = OneSignal::App.new # App | \n\nbegin\n # Update an app\n result = api_instance.update_app(app_id, app)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_app: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | An app id\n App app = new App(); // App | \n try {\n App result = apiInstance.updateApp(appId, app);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateApp\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateAppExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | An app id\n var app = new App(); // App | \n\n try\n {\n // Update an app\n App result = apiInstance.UpdateApp(appId, app);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateApp: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let app: models::App = todo!();\n\n match default_api::update_app(&configuration, app_id, app).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_app failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_app failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "default": "NAME_OF_NEW_APP" }, "organization_id": { "type": "string", "description": "The [Organization ID](/docs/en/keys-and-ids#organization-id) that the app will be associated with.", "default": "YOUR_ORG_ID" }, "chrome_web_origin": { "type": "string", "description": "The HTTPS [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) URL for your website. Required for web push notifications." }, "site_name": { "type": "string", "description": "The name of your website. Used for web push notification titles when omitted from the notification payload. Required for web push notifications.", "default": "SITE_NAME" }, "safari_site_origin": { "type": "string", "description": "The HTTPS [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) URL for your website. Required for web push notifications for Safari and should be the same as `chrome_web_origin`." }, "chrome_web_default_notification_icon": { "type": "string", "description": "The full `https` URL to your default icon resource. The icon should be a `256x256px` PNG." }, "safari_icon_256_256": { "type": "string", "description": "The full `https` URL to your default icon resource. The icon should be a `256x256px` PNG." }, "safari_apns_p12": { "type": "string", "description": "A Base64 encoded p12 certificate for Safari Push Notifications. If omitted, we will assign one to your app for you." }, "safari_apns_p12_password": { "type": "string", "description": "The password for the `safari_apns_p12` file if applicable." }, "fcm_v1_service_account_json": { "type": "string", "description": "Your FCM Service Account JSON file converted to base64 format. See [Android: Firebase Credentials](/docs/android-firebase-credentials). Required for Android mobile push notifications." }, "apns_p8": { "type": "string", "description": "A Base64 encoded p8 file for iOS mobile Push Notifications. Omit if using `apns_p12`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_env": { "type": "string", "description": "The [APS Environment Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) to specify whether this is a `production` or `development` environment. Defaults to `production`. Use with `apns_p8`.", "enum": [ "production", "development" ] }, "apns_key_id": { "type": "string", "description": "The APNS Key ID. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_team_id": { "type": "string", "description": "The APNS Team ID. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_bundle_id": { "type": "string", "description": "The Bundle ID for your app. Use with `apns_p8`. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns)." }, "apns_p12": { "type": "string", "description": "A Base64 encoded p12 certificate for iOS mobile push notifications. Omit if using `apns_p8`. See [p12 APNS Authentication](/docs/ios-p12-generate-certificates)." }, "apns_p12_password": { "type": "string", "description": "The password for the `apns_p12` file if applicable." }, "additional_data_is_root_payload": { "type": "boolean", "description": "If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/osnotification-payload).", "default": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The OneSignal App ID in UUID v4 format.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track Apps. Maximum 128 characters.", "type": "string" }, "players": { "description": "The total number of Subscriptions in the app.", "type": "integer" }, "messageable_players": { "description": "The number of Subscriptions eligible to receive messages in the app.", "type": "integer" }, "created_at": { "description": "The date and time the app was created.", "type": "string" }, "updated_at": { "description": "The date and time the app was last updated.", "type": "string" }, "organization_id": { "description": "The Organization ID in which the app was created.", "type": "string" }, "fcm_v1_service_account_json": { "description": "Your FCM Service Account JSON file for Android push notifications. See [Android: Firebase Credentials](/docs/android-firebase-credentials).", "type": "string" }, "fcm_sender_id": { "description": "The FCM Sender ID associated with your Firebase project.", "type": "string" }, "chrome_web_key": { "description": "Web push VAPID public key for Chrome web push notifications.", "type": "string" }, "chrome_web_origin": { "description": "The HTTPS origin URL for your website. Required for web push notifications.", "type": "string" }, "chrome_web_gcm_sender_id": { "description": "The GCM Sender ID used for web push notifications.", "type": "string" }, "chrome_web_default_notification_icon": { "description": "The full HTTPS URL to your default notification icon. Should be a 256x256px PNG.", "type": "string" }, "chrome_web_sub_domain": { "description": "The OneSignal subdomain for web push if not using your own origin.", "type": "string" }, "apns_env": { "description": "The APNS environment: `production` or `development`. See [iOS SDK Setup](/docs/ios-sdk-setup).", "type": "string" }, "apns_certificates": { "description": "The APNS p12 certificate for iOS push notifications. See [p12 APNS Authentication](/docs/ios-p12-generate-certificates).", "type": "string" }, "apns_p8": { "description": "The APNS p8 token key for iOS push notifications. See [p8 Token-based connection to APNS](/docs/ios-p8-token-based-connection-to-apns).", "type": "string" }, "apns_team_id": { "description": "The Apple Team ID associated with your APNS credentials.", "type": "string" }, "apns_key_id": { "description": "The APNS Key ID for p8 token-based authentication.", "type": "string" }, "apns_bundle_id": { "description": "The iOS app Bundle ID associated with your APNS credentials.", "type": "string" }, "site_name": { "description": "The name of your website, used for web push notification titles.", "type": "string" } } } } } }, "403": { "description": "Forbidden. The Authorization key does not have permission to update this app, or the requested change violates the organization's policy (e.g., transferring an app to another organization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "You do not have permission to update this app." ] } } } }, "404": { "description": "App not found, or the target organization (when transferring) was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Couldn't find app with id = " ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/players/csv_export": { "post": { "summary": "Export subscriptions CSV", "description": "Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.", "operationId": "csv-export", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The app ID that you want to export devices from\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// ExportSubscriptionsRequestBody (optional)\nconst exportSubscriptionsRequestBody: Onesignal.ExportSubscriptionsRequestBody = {\n extra_fields: [\n \"extra_fields_example\",\n ],\n last_active_since: \"last_active_since_example\",\n segment_name: \"segment_name_example\",\n };\n\ntry {\n const response = await apiInstance.exportSubscriptions(appId, exportSubscriptionsRequestBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"exportSubscriptions failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The app ID that you want to export devices from \n export_subscriptions_request_body = ExportSubscriptionsRequestBody(\n extra_fields=[\n \"extra_fields_example\",\n ],\n last_active_since=\"last_active_since_example\",\n segment_name=\"segment_name_example\",\n ) \n\n try:\n # Export CSV of Subscriptions\n api_response = api_instance.export_subscriptions(app_id, export_subscriptions_request_body=export_subscriptions_request_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->export_subscriptions: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The app ID that you want to export devices from\n$export_subscriptions_request_body = new \\onesignal\\client\\model\\ExportSubscriptionsRequestBody(); // \\onesignal\\client\\model\\ExportSubscriptionsRequestBody\n\ntry {\n $result = $apiInstance->exportSubscriptions($app_id, $export_subscriptions_request_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->exportSubscriptions: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->exportSubscriptions: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The app ID that you want to export devices from\n exportSubscriptionsRequestBody := *onesignal.NewExportSubscriptionsRequestBody() // ExportSubscriptionsRequestBody | (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.ExportSubscriptions(restAuth, appId).ExportSubscriptionsRequestBody(exportSubscriptionsRequestBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.ExportSubscriptions``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `ExportSubscriptions`: ExportSubscriptionsSuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.ExportSubscriptions`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The app ID that you want to export devices from\nopts = {\n export_subscriptions_request_body: OneSignal::ExportSubscriptionsRequestBody.new # ExportSubscriptionsRequestBody | \n}\n\nbegin\n # Export CSV of Subscriptions\n result = api_instance.export_subscriptions(app_id, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->export_subscriptions: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The app ID that you want to export devices from\n ExportSubscriptionsRequestBody exportSubscriptionsRequestBody = new ExportSubscriptionsRequestBody(); // ExportSubscriptionsRequestBody | \n try {\n ExportSubscriptionsSuccessResponse result = apiInstance.exportSubscriptions(appId, exportSubscriptionsRequestBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#exportSubscriptions\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class ExportSubscriptionsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The app ID that you want to export devices from\n var exportSubscriptionsRequestBody = new ExportSubscriptionsRequestBody(); // ExportSubscriptionsRequestBody | (optional) \n\n try\n {\n // Export CSV of Subscriptions\n ExportSubscriptionsSuccessResponse result = apiInstance.ExportSubscriptions(appId, exportSubscriptionsRequestBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.ExportSubscriptions: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let export_subscriptions_request_body: Option = None;\n\n match default_api::export_subscriptions(&configuration, app_id, export_subscriptions_request_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"export_subscriptions failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"export_subscriptions failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "extra_fields": { "type": "array", "description": "Additional properties that you can include in the CSV.", "default": [ "external_user_id", "country", "timezone_id" ], "items": { "type": "string", "enum": [ "external_user_id", "onesignal_id", "location", "country", "rooted", "ip", "web_auth", "web_p256", "unsubscribed_at", "notification_types", "timezone_id" ] } }, "last_active_since": { "type": "string", "description": "A Unix timestamp (in seconds) used to filter Subscriptions based on recent activity. Only Subscriptions with a `last_session` timestamp after this value will be included in the export. Example: To export Subscriptions active since January 1st, 2024, use `1704067200`." }, "segment_name": { "type": "string", "description": "The name of a specific segment to filter the export. Only subscriptions that belong to this segment will be included in the CSV. Omit this field to export all subscriptions in the app." }, "include_unsubscribed": { "type": "boolean", "description": "When used with `segment_name`, set to `true` to include unsubscribed subscriptions in the export. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.", "default": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "csv_file_url": { "type": "string", "description": "The URL to download the CSV file. The file is available for 3 days after generation." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Request is malformed: Failed to parse app_id from request" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/notifications/{message_id}/history": { "x-mcp": { "enabled": true }, "post": { "summary": "Message history", "description": "View which subscriptions received a particular message", "operationId": "message-history", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The \\\"id\\\" of the message found in the Notification object\nconst notificationId: string = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n// GetNotificationHistoryRequestBody\nconst getNotificationHistoryRequestBody: Onesignal.GetNotificationHistoryRequestBody = {\n events: \"sent\",\n email: \"email_example\",\n app_id: \"app_id_example\",\n };\n\ntry {\n const response = await apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getNotificationHistory failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n notification_id = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" # The \\\"id\\\" of the message found in the Notification object \n get_notification_history_request_body = GetNotificationHistoryRequestBody(\n events=\"sent\",\n email=\"email_example\",\n app_id=\"app_id_example\",\n ) \n\n try:\n # Notification History\n api_response = api_instance.get_notification_history(notification_id, get_notification_history_request_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_notification_history: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string | The \\\"id\\\" of the message found in the Notification object\n$get_notification_history_request_body = new \\onesignal\\client\\model\\GetNotificationHistoryRequestBody(); // \\onesignal\\client\\model\\GetNotificationHistoryRequestBody\n\ntry {\n $result = $apiInstance->getNotificationHistory($notification_id, $get_notification_history_request_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n notificationId := \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" // string | The \\\"id\\\" of the message found in the Notification object\n getNotificationHistoryRequestBody := *onesignal.NewGetNotificationHistoryRequestBody() // GetNotificationHistoryRequestBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetNotificationHistory(restAuth, notificationId).GetNotificationHistoryRequestBody(getNotificationHistoryRequestBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetNotificationHistory``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetNotificationHistory`: NotificationHistorySuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetNotificationHistory`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nnotification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | The \\\"id\\\" of the message found in the Notification object\nget_notification_history_request_body = OneSignal::GetNotificationHistoryRequestBody.new # GetNotificationHistoryRequestBody | \n\nbegin\n # Notification History\n result = api_instance.get_notification_history(notification_id, get_notification_history_request_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_notification_history: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // String | The \\\"id\\\" of the message found in the Notification object\n GetNotificationHistoryRequestBody getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody | \n try {\n NotificationHistorySuccessResponse result = apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getNotificationHistory\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetNotificationHistoryExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // string | The \\\"id\\\" of the message found in the Notification object\n var getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody | \n\n try\n {\n // Notification History\n NotificationHistorySuccessResponse result = apiInstance.GetNotificationHistory(notificationId, getNotificationHistoryRequestBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetNotificationHistory: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let notification_id: &str = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n let get_notification_history_request_body: models::GetNotificationHistoryRequestBody = todo!();\n\n match default_api::get_notification_history(&configuration, notification_id, get_notification_history_request_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_notification_history failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_notification_history failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "message_id", "in": "path", "description": "The identifier of the message in UUID v4 format. Get this `id` in the response of your Create Message API request, the [View Messages API](/reference/view-messages), and in your OneSignal dashboard Message Reports.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "events" ], "properties": { "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "default": "YOUR_APP_ID" }, "events": { "type": "string", "description": "Specifies the type of event to retrieve. `sent` — retrieves all subscriptions sent the specified message. Note: sent events are not recorded for messages targeting fewer than 1,000 recipients. `clicked` — retrieves all subscriptions that interacted with the message. Note: There isn't a recipient count threshold for tracking clicked event.", "default": "sent" }, "email": { "type": "string", "description": "The email address in which to deliver the report." } } } } } }, "responses": { "202": { "description": "Accepted. The history-export job was enqueued. The export is delivered asynchronously to the configured S3 destination.", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "destination_url": "https://onesignal-aws-link.csv" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "destination_url": { "type": "string", "example": "https://onesignal-aws-link.csv" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "param `email` must be a valid email" ], "success": false } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/segments": { "post": { "summary": "Create segment", "description": "Programmatically create segments in your OneSignal app using flexible filters and targeting rules.", "operationId": "create-segments", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// Segment (optional)\nconst segment: Onesignal.Segment = {\n id: \"id_example\",\n name: \"name_example\",\n filters: [\n {\n field: \"field_example\",\n key: \"key_example\",\n value: \"value_example\",\n hours_ago: \"hours_ago_example\",\n radius: 3.14,\n lat: 3.14,\n long: 3.14,\n relation: \">\",\n },\n ],\n };\n\ntry {\n const response = await apiInstance.createSegment(appId, segment);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createSegment failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n segment = Segment(\n id=\"id_example\",\n name=\"name_example\",\n filters=[\n Filter(\n field=\"field_example\",\n key=\"key_example\",\n value=\"value_example\",\n hours_ago=\"hours_ago_example\",\n radius=3.14,\n lat=3.14,\n long=3.14,\n relation=\">\",\n ),\n ],\n ) \n\n try:\n # Create Segment\n api_response = api_instance.create_segment(app_id, segment=segment)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_segment: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$segment = new \\onesignal\\client\\model\\Segment(); // \\onesignal\\client\\model\\Segment\n\ntry {\n $result = $apiInstance->createSegment($app_id, $segment);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createSegment: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createSegment: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n segment := *onesignal.NewSegment(\"Name_example\", []onesignal.FilterExpression{onesignal.FilterExpression{Filter: onesignal.NewFilter()}}) // Segment | (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateSegment(restAuth, appId).Segment(segment).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateSegment``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateSegment`: CreateSegmentSuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateSegment`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\nopts = {\n segment: OneSignal::Segment.new({name: 'name_example', filters: [OneSignal::Filter.new]}) # Segment | \n}\n\nbegin\n # Create Segment\n result = api_instance.create_segment(app_id, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_segment: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n Segment segment = new Segment(); // Segment | \n try {\n CreateSegmentSuccessResponse result = apiInstance.createSegment(appId, segment);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createSegment\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateSegmentExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var segment = new Segment(); // Segment | (optional) \n\n try\n {\n // Create Segment\n CreateSegmentSuccessResponse result = apiInstance.CreateSegment(appId, segment);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateSegment: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let segment: Option = None;\n\n match default_api::create_segment(&configuration, app_id, segment).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_segment failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_segment failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "filters" ], "properties": { "id": { "type": "string", "description": "UUID of the segment. If left empty, it will be assigned automatically." }, "name": { "type": "string", "description": "An internal name you set to help organize and track Segments. Maximum 128 characters.", "default": "YOUR_SEGMENT_NAME" }, "description": { "type": "string", "description": "Optional human-readable description for the segment. Maximum 255 characters.", "maxLength": 255, "default": "YOUR_SEGMENT_DESCRIPTION" }, "filters": { "type": "array", "description": "Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).", "items": { "oneOf": [ { "title": "Filter", "description": "Required. The fitler object.", "required": [ "field", "relation" ], "type": "object", "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "enum": [ "tag", "last_session", "first_session", "session_count", "session_time", "language", "app_version", "location", "country" ] }, "relation": { "type": "string", "description": "Used with most filters. See details on the specific filter.", "enum": [ "=", "!=", ">", "<", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with." } } }, { "title": "Operator", "type": "object", "properties": { "operator": { "type": "string", "description": "Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.", "enum": [ "AND", "OR" ], "default": "AND" } } } ] }, "minItems": 1, "maxItems": 200 } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true if the segment was created successfully, false otherwise.", "default": true }, "id": { "type": "string", "description": "The UUID of the created segment." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "The reason why the segment was not created." ] } } } }, "403": { "description": "Forbidden. Your app's plan does not allow this segment operation, or the Authorization key does not have permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "This API is not available for applications on your plan." ] } } } }, "422": { "description": "Unprocessable Entity. The segment cannot be created because the app has reached an entitlement limit on segments (e.g., the maximum number of segments allowed for this plan). Distinct from 403 (which signals a permission denial); 422 is specifically a plan-limits failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "You have reached the maximum number of segments allowed for your plan." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] }, "get": { "summary": "View segments", "description": "Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.", "operationId": "view-segments", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// number | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional)\nconst offset: number = 0;\n// number | The amount of Segments in the response. Maximum 300. (optional)\nconst limit: number = 10;\n\ntry {\n const response = await apiInstance.getSegments(appId, offset, limit);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getSegments failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n offset = 0 # Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional) \n limit = 10 # The amount of Segments in the response. Maximum 300. (optional) \n\n try:\n # Get Segments\n api_response = api_instance.get_segments(app_id, offset=offset, limit=limit)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_segments: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$offset = 0; // int | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.\n$limit = 10; // int | The amount of Segments in the response. Maximum 300.\n\ntry {\n $result = $apiInstance->getSegments($app_id, $offset, $limit);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getSegments: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getSegments: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n offset := int32(0) // int32 | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional)\n limit := int32(10) // int32 | The amount of Segments in the response. Maximum 300. (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetSegments(restAuth, appId).Offset(offset).Limit(limit).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetSegments``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetSegments`: GetSegmentsSuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetSegments`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\nopts = {\n offset: 0, # Integer | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.\n limit: 10 # Integer | The amount of Segments in the response. Maximum 300.\n}\n\nbegin\n # Get Segments\n result = api_instance.get_segments(app_id, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_segments: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n Integer offset = 0; // Integer | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.\n Integer limit = 10; // Integer | The amount of Segments in the response. Maximum 300.\n try {\n GetSegmentsSuccessResponse result = apiInstance.getSegments(appId, offset, limit);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getSegments\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetSegmentsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var offset = 0; // int? | Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments. (optional) \n var limit = 10; // int? | The amount of Segments in the response. Maximum 300. (optional) \n\n try\n {\n // Get Segments\n GetSegmentsSuccessResponse result = apiInstance.GetSegments(appId, offset, limit);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetSegments: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let offset: Option = None;\n let limit: Option = None;\n\n match default_api::get_segments(&configuration, app_id, offset, limit).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_segments failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_segments failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "offset", "in": "query", "description": "The index to start returning segments from. Defaults to `0`. Segments are sorted by their creation date (`created_at`) in ascending order.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The maximum number of segments to return. Default/Max: `300`. Ideal for controlling data volume in large-scale applications.", "schema": { "type": "integer", "format": "int32", "default": 300 } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "total_count": 1, "offset": 0, "limit": 300, "segments": [ { "id": "4414c404-56a3-11ed-9b6a-0242ac120002", "name": "Subscribed Users", "description": "YOUR_SEGMENT_DESCRIPTION", "created_at": "2022-07-23T13:44:10.324Z", "updated_at": "2022-09-18T11:33:02.451Z", "app_id": "65c10914-56a3-11ed-9b6a-0242ac120002", "read_only": false, "is_active": true } ] } } }, "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "The total number of segments available for the app." }, "offset": { "type": "integer", "description": "Value set in the `offset` query parameter." }, "limit": { "type": "integer", "description": "Value set in the `limit` query parameter." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the segment in UUID v4 format." }, "name": { "type": "string", "description": "An internal name you set to help organize and track Segments. Maximum 128 characters." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description for the segment. `null` when unset. Maximum 255 characters." }, "created_at": { "type": "string", "description": "The date and time the segment was created in ISO 8601 format." }, "updated_at": { "type": "string", "description": "The date and time the segment was last updated in ISO 8601 format." }, "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids)." }, "read_only": { "type": "boolean", "description": "Indicates if the segment is read-only." }, "is_active": { "type": "boolean", "description": "Indicates if the segment is active. `false` means the segment is paused and cannot be used to send messages." } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "example error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/apps/{app_id}/segments/{segment_id}": { "get": { "summary": "View segment", "description": "Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.", "operationId": "view-segment", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "segment_id", "in": "path", "description": "The segment's unique identifier. Can be found using the View segments API or in the dashboard URL.", "schema": { "type": "string", "default": "YOUR_SEGMENT_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "include-segment-detail", "in": "query", "description": "Set to `true` to include segment metadata and filters in the response.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Basic": { "value": { "subscriber_count": 12345 } }, "With Details (simple)": { "value": { "subscriber_count": 12345, "payload": { "id": "4414c404-56a3-11ed-9b6a-0242ac120002", "name": "Subscribed Users", "description": "YOUR_SEGMENT_DESCRIPTION", "created_at": 1658584650, "source": "custom", "filters": [ { "field": "session_count", "relation": ">", "value": "5" } ] } } }, "With Details (AND/OR)": { "value": { "subscriber_count": 5678, "payload": { "id": "5525d515-67b4-22fe-0c7b-1353bd231113", "name": "Engaged Users", "description": "YOUR_SEGMENT_DESCRIPTION", "created_at": 1658584650, "source": "custom", "filters": [ { "field": "session_count", "relation": ">", "value": "2" }, { "operator": "AND" }, { "field": "tag", "key": "level", "relation": "=", "value": "10" }, { "operator": "OR" }, { "field": "last_session", "relation": "<", "hours_ago": "24" } ] } } } }, "schema": { "type": "object", "properties": { "subscriber_count": { "type": "integer", "description": "The number of subscribers matching this segment." }, "payload": { "type": "object", "description": "Segment details. Only included when `include-segment-detail=true`.", "properties": { "id": { "type": "string", "description": "The unique identifier for the segment (UUID v4)." }, "name": { "type": "string", "description": "The segment name." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description for the segment. `null` when unset. Maximum 255 characters." }, "created_at": { "type": "integer", "description": "Unix timestamp when the segment was created." }, "source": { "type": "string", "description": "The source of the segment.", "enum": [ "default", "custom", "quickstart" ] }, "filters": { "type": "array", "description": "Array of filter and operator objects defining the segment criteria. Uses the same format as the Create segment API, so filters can be directly used to recreate or update the segment.", "items": { "oneOf": [ { "type": "object", "description": "A filter condition.", "properties": { "field": { "type": "string", "description": "The filter type." }, "relation": { "type": "string", "description": "The comparison operator.", "enum": [ ">", "<", "=", "!=", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "value": { "type": "string", "description": "The filter value." }, "key": { "type": "string", "description": "The filter key (used for tag filters)." }, "hours_ago": { "type": "string", "description": "Hours ago value (used for last_session/first_session filters)." }, "radius": { "type": "string", "description": "Radius in meters (used for location filters)." }, "lat": { "type": "string", "description": "Latitude (used for location filters)." }, "long": { "type": "string", "description": "Longitude (used for location filters)." }, "unsupported_in_api": { "type": "boolean", "description": "If true, this filter type cannot be used with the Create/Update segment APIs. These filters were created via the dashboard UI using features not available in the public API (e.g., message_event, custom_event filters)." } } }, { "type": "object", "description": "A logical operator to combine filters.", "properties": { "operator": { "type": "string", "description": "The logical operator.", "enum": [ "AND", "OR" ] } }, "required": [ "operator" ] } ] } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Missing Authorization": { "value": { "errors": [ "Please include a case-sensitive header of Authorization" ] } }, "User-based Segment": { "value": { "errors": [ "User-based segments (with message event or custom event filters) are not yet supported via the API" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "segment not found" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] }, "patch": { "summary": "Update segment", "description": "Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.", "operationId": "update-segment", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "segment_id", "in": "path", "description": "The `segment_id` can be found in the URL of the segment when viewing it in the dashboard.", "schema": { "type": "string", "default": "YOUR_SEGMENT_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Required. The segment name. Maximum 128 characters.", "default": "YOUR_SEGMENT_NAME" }, "description": { "type": "string", "description": "Optional human-readable description for the segment. Maximum 255 characters. Pass an empty string to clear; omit to leave unchanged.", "maxLength": 255, "default": "YOUR_SEGMENT_DESCRIPTION" }, "filters": { "type": "array", "description": "Optional. When provided, replaces all existing filters. Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Create segment](/reference/create-segments) for filter syntax.", "items": { "oneOf": [ { "title": "Filter", "description": "Required. The filter object.", "required": [ "field", "relation" ], "type": "object", "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "enum": [ "tag", "last_session", "first_session", "session_count", "session_time", "language", "app_version", "location", "country" ] }, "relation": { "type": "string", "description": "Used with most filters. See details on the specific filter.", "enum": [ "=", "!=", ">", "<", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with." } } }, { "title": "Operator", "type": "object", "properties": { "operator": { "type": "string", "description": "Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.", "enum": [ "AND", "OR" ], "default": "AND" } } } ] }, "minItems": 1, "maxItems": 200 } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true if the segment was updated successfully, false otherwise.", "default": true }, "id": { "type": "string", "description": "The UUID of the updated segment." } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ "Segment name is already taken." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ "This API is not available for applications on your plan." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ "segment not found" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] }, "delete": { "summary": "Delete segment", "description": "Delete segments from OneSignal. Does not delete users or subscriptions.", "operationId": "delete-segments", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\nconst segmentId: string = \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\";\n\ntry {\n const response = await apiInstance.deleteSegment(appId, segmentId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteSegment failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n segment_id = \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\" # The segment_id can be found in the URL of the segment when viewing it in the dashboard. \n\n try:\n # Delete Segment\n api_response = api_instance.delete_segment(app_id, segment_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_segment: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$segment_id = 'd6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e'; // string | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\n\ntry {\n $result = $apiInstance->deleteSegment($app_id, $segment_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteSegment: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteSegment: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n segmentId := \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\" // string | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.DeleteSegment(restAuth, appId, segmentId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteSegment``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `DeleteSegment`: GenericSuccessBoolResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.DeleteSegment`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\nsegment_id = 'd6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e' # String | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\n\nbegin\n # Delete Segment\n result = api_instance.delete_segment(app_id, segment_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_segment: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n String segmentId = \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\"; // String | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\n try {\n GenericSuccessBoolResponse result = apiInstance.deleteSegment(appId, segmentId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteSegment\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteSegmentExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var segmentId = \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\"; // string | The segment_id can be found in the URL of the segment when viewing it in the dashboard.\n\n try\n {\n // Delete Segment\n GenericSuccessBoolResponse result = apiInstance.DeleteSegment(appId, segmentId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteSegment: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let segment_id: &str = \"d6c5a3e1-9f17-44a1-9d10-7c0e4a2b1c8e\";\n\n match default_api::delete_segment(&configuration, app_id, segment_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_segment failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_segment failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "segment_id", "in": "path", "description": "The `segment_id` can be found in the URL of the segment when viewing it in the dashboard.", "schema": { "type": "string", "default": "YOUR_SEGMENT_ID" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "app_id not found. You may be missing a Content-Type: application/json header." ], "reference": [ "/docs/accounts-and-keys#section-keys-ids" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "success": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true } } } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}": { "x-mcp": { "enabled": true }, "get": { "summary": "View outcomes", "description": "View and export push notification outcome metrics such as clicks, conversions, and custom events.", "operationId": "view-outcomes", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \nconst outcomeNames: string = \"os__session_duration.count,os__click.count\";\n// string | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. (optional)\nconst outcomeNames2: string = \"os__session_duration.count\";\n// string | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. (optional)\nconst outcomeTimeRange: string = \"1d\";\n// string | Optional Platform id. Refer device\\'s platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. (optional)\nconst outcomePlatforms: string = \"0,1\";\n// string | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. (optional)\nconst outcomeAttribution: string = \"direct\";\n\ntry {\n const response = await apiInstance.getOutcomes(appId, outcomeNames, outcomeNames2, outcomeTimeRange, outcomePlatforms, outcomeAttribution);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getOutcomes failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n outcome_names = \"os__session_duration.count,os__click.count\" # Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \n outcome_names2 = \"os__session_duration.count\" # Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. (optional) \n outcome_time_range = \"1d\" # Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. (optional) \n outcome_platforms = \"0,1\" # Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. (optional) \n outcome_attribution = \"direct\" # Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. (optional) \n\n try:\n # View Outcomes\n api_response = api_instance.get_outcomes(app_id, outcome_names, outcome_names2=outcome_names2, outcome_time_range=outcome_time_range, outcome_platforms=outcome_platforms, outcome_attribution=outcome_attribution)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_outcomes: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$outcome_names = 'os__session_duration.count,os__click.count'; // string | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum\n$outcome_names2 = 'os__session_duration.count'; // string | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name.\n$outcome_time_range = '1d'; // string | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted.\n$outcome_platforms = '0,1'; // string | Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted.\n$outcome_attribution = 'direct'; // string | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted.\n\ntry {\n $result = $apiInstance->getOutcomes($app_id, $outcome_names, $outcome_names2, $outcome_time_range, $outcome_platforms, $outcome_attribution);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getOutcomes: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getOutcomes: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n outcomeNames := \"os__session_duration.count,os__click.count\" // string | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \n outcomeNames2 := \"os__session_duration.count\" // string | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. (optional)\n outcomeTimeRange := \"1d\" // string | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. (optional)\n outcomePlatforms := \"0,1\" // string | Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. (optional)\n outcomeAttribution := \"direct\" // string | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetOutcomes(restAuth, appId).OutcomeNames(outcomeNames).OutcomeNames2(outcomeNames2).OutcomeTimeRange(outcomeTimeRange).OutcomePlatforms(outcomePlatforms).OutcomeAttribution(outcomeAttribution).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetOutcomes``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetOutcomes`: OutcomesData\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetOutcomes`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\noutcome_names = 'os__session_duration.count,os__click.count' # String | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \nopts = {\n outcome_names2: 'os__session_duration.count', # String | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. \n outcome_time_range: '1d', # String | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. \n outcome_platforms: '0,1', # String | Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. \n outcome_attribution: 'direct' # String | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. \n}\n\nbegin\n # View Outcomes\n result = api_instance.get_outcomes(app_id, outcome_names, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_outcomes: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n String outcomeNames = \"os__session_duration.count,os__click.count\"; // String | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \n String outcomeNames2 = \"os__session_duration.count\"; // String | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. \n String outcomeTimeRange = \"1d\"; // String | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. \n String outcomePlatforms = \"0,1\"; // String | Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. \n String outcomeAttribution = \"direct\"; // String | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. \n try {\n OutcomesData result = apiInstance.getOutcomes(appId, outcomeNames, outcomeNames2, outcomeTimeRange, outcomePlatforms, outcomeAttribution);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getOutcomes\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetOutcomesExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var outcomeNames = \"os__session_duration.count,os__click.count\"; // string | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the \\\"os\\\" prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum \n var outcomeNames2 = \"os__session_duration.count\"; // string | Optional If outcome names contain any commas, then please specify only one value at a time. Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count where \\\"Sales, Purchase\\\" is the custom outcomes with a comma in the name. (optional) \n var outcomeTimeRange = \"1d\"; // string | Optional Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data). Default is 1h if the parameter is omitted. (optional) \n var outcomePlatforms = \"0,1\"; // string | Optional Platform id. Refer device's platform ids for values. Example: outcome_platform=0 for iOS outcome_platform=7,8 for Safari and Firefox Default is data from all platforms if the parameter is omitted. (optional) \n var outcomeAttribution = \"direct\"; // string | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted. (optional) \n\n try\n {\n // View Outcomes\n OutcomesData result = apiInstance.GetOutcomes(appId, outcomeNames, outcomeNames2, outcomeTimeRange, outcomePlatforms, outcomeAttribution);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetOutcomes: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let outcome_names: &str = \"os__session_duration.count,os__click.count\";\n let outcome_names2: Option<&str> = None;\n let outcome_time_range: Option<&str> = None;\n let outcome_platforms: Option<&str> = None;\n let outcome_attribution: Option<&str> = None;\n\n match default_api::get_outcomes(&configuration, app_id, outcome_names, outcome_names2, outcome_time_range, outcome_platforms, outcome_attribution).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_outcomes failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_outcomes failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "outcome_names", "in": "query", "description": "The name and aggregation type of the outcome(s) you want to fetch. Example: `my_outcome.count` or `my_outcome.sum`. For clicks, use `os__click.count`. For confirmed deliveries, use `os__confirmed_delivery.count`. For session duration, use `os__session_duration.count`.", "schema": { "type": "array", "items": { "type": "string", "default": [ "os__click.count", "os__confirmed_delivery.count", "os__session_duration.count" ] } } }, { "name": "outcome_time_range", "in": "query", "description": "Time range for the returned data. Available values: `1h` (1 hour), `1d` (1 day), `1mo` (1 month)", "schema": { "type": "string", "enum": [ "1h", "1d", "1mo" ], "default": "1h" } }, { "name": "outcome_platforms", "in": "query", "description": "The platforms in which you want to pull the data represented as the `device_type` integer.", "schema": { "type": "string", "default": "0,1,2,5,8,11,14,17" } }, { "name": "outcome_attribution", "in": "query", "description": "Attribution type for the outcomes.", "schema": { "type": "string", "enum": [ "direct", "influenced", "unattributed", "total" ], "default": "total" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "os__session_duration" }, "value": { "type": "integer", "example": 100, "default": 0 }, "aggregation": { "type": "string", "example": "sum" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Add .sum or .count to every requested outcome id" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Access denied. Please include an 'Authorization: ...' header with a valid API key (/docs/accounts-and-keys)." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/subscriptions/{subscription_id}": { "patch": { "summary": "Update subscription", "description": "Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.", "operationId": "update-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst subscriptionId: string = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n// SubscriptionBody\nconst subscriptionBody: Onesignal.SubscriptionBody = {\n subscription: {\n id: \"id_example\",\n type: \"iOSPush\",\n token: \"token_example\",\n enabled: true,\n notification_types: 1,\n session_time: 1,\n session_count: 1,\n sdk: \"sdk_example\",\n device_model: \"device_model_example\",\n device_os: \"device_os_example\",\n rooted: true,\n test_type: 1,\n app_version: \"app_version_example\",\n net_type: 1,\n carrier: \"carrier_example\",\n web_auth: \"web_auth_example\",\n web_p256: \"web_p256_example\",\n },\n };\n\ntry {\n const response = await apiInstance.updateSubscription(appId, subscriptionId, subscriptionBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateSubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n subscription_id = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" \n subscription_body = SubscriptionBody(\n subscription=Subscription(\n id=\"id_example\",\n type=\"iOSPush\",\n token=\"token_example\",\n enabled=True,\n notification_types=1,\n session_time=1,\n session_count=1,\n sdk=\"sdk_example\",\n device_model=\"device_model_example\",\n device_os=\"device_os_example\",\n rooted=True,\n test_type=1,\n app_version=\"app_version_example\",\n net_type=1,\n carrier=\"carrier_example\",\n web_auth=\"web_auth_example\",\n web_p256=\"web_p256_example\",\n ),\n ) \n\n try:\n api_instance.update_subscription(app_id, subscription_id, subscription_body)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$subscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51'; // string\n$subscription_body = new \\onesignal\\client\\model\\SubscriptionBody(); // \\onesignal\\client\\model\\SubscriptionBody\n\ntry {\n $apiInstance->updateSubscription($app_id, $subscription_id, $subscription_body);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateSubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateSubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n subscriptionId := \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" // string | \n subscriptionBody := *onesignal.NewSubscriptionBody() // SubscriptionBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n r, err := apiClient.DefaultApi.UpdateSubscription(restAuth, appId, subscriptionId).SubscriptionBody(subscriptionBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateSubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nsubscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51' # String | \nsubscription_body = OneSignal::SubscriptionBody.new # SubscriptionBody | \n\nbegin\n \n api_instance.update_subscription(app_id, subscription_id, subscription_body)\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // String | \n SubscriptionBody subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n try {\n apiInstance.updateSubscription(appId, subscriptionId, subscriptionBody);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateSubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateSubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // string | \n var subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n\n try\n {\n apiInstance.UpdateSubscription(appId, subscriptionId, subscriptionBody);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateSubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let subscription_id: &str = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n let subscription_body: models::SubscriptionBody = todo!();\n\n match default_api::update_subscription(&configuration, app_id, subscription_id, subscription_body).await {\n Ok(_) => println!(\"update_subscription succeeded\"),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "subscription_id", "in": "path", "description": "The unique Subscription ID in UUID v4 format generated by OneSignal. See [Subscriptions](/docs/subscriptions).", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "description": "The subscription's properties.", "required": [ "type", "token" ], "properties": { "type": { "type": "string", "description": "The subscription channel type. Must match the format of the token.", "enum": [ "Email", "SMS", "iOSPush", "AndroidPush", "HuaweiPush", "FireOSPush", "WindowsPush", "macOSPush", "ChromeExtensionPush", "ChromePush", "SafariLegacyPush", "FirefoxPush", "SafariPush" ] }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore." }, "enabled": { "type": "boolean", "description": "Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).", "format": "int32" }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version." }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "description": "The Subscription updated successfully. This process is asynchronous and may take a few seconds to complete." } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } } }, "delete": { "summary": "Delete subscription", "description": "Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.", "operationId": "delete-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst subscriptionId: string = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n\ntry {\n const response = await apiInstance.deleteSubscription(appId, subscriptionId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteSubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n subscription_id = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" \n\n try:\n api_instance.delete_subscription(app_id, subscription_id)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$subscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51'; // string\n\ntry {\n $apiInstance->deleteSubscription($app_id, $subscription_id);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteSubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteSubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n subscriptionId := \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n r, err := apiClient.DefaultApi.DeleteSubscription(restAuth, appId, subscriptionId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteSubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nsubscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51' # String | \n\nbegin\n \n api_instance.delete_subscription(app_id, subscription_id)\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // String | \n try {\n apiInstance.deleteSubscription(appId, subscriptionId);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteSubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteSubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // string | \n\n try\n {\n apiInstance.DeleteSubscription(appId, subscriptionId);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteSubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let subscription_id: &str = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n\n match default_api::delete_subscription(&configuration, app_id, subscription_id).await {\n Ok(_) => println!(\"delete_subscription succeeded\"),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "subscription_id", "in": "path", "description": "The unique Subscription ID in UUID v4 format generated by OneSignal. See [Subscriptions](/docs/subscriptions).", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "202", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Details about the error." ] } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Forbidden" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "subscription-0", "title": "Subscription not found" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/apps/{app_id}/subscriptions_by_token/{token_type}/{token}": { "patch": { "summary": "Update subscription By Token", "description": "Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.", "operationId": "update-subscription-by-token", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | Your OneSignal App ID in UUID v4 format.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | The type of token to use when looking up the subscription. See Subscription Types.\nconst tokenType: string = \"Email\";\n// string | The value of the token to lookup by (e.g., email address, phone number).\nconst token: string = \"user@example.com\";\n// SubscriptionBody\nconst subscriptionBody: Onesignal.SubscriptionBody = {\n subscription: {\n id: \"id_example\",\n type: \"iOSPush\",\n token: \"token_example\",\n enabled: true,\n notification_types: 1,\n session_time: 1,\n session_count: 1,\n sdk: \"sdk_example\",\n device_model: \"device_model_example\",\n device_os: \"device_os_example\",\n rooted: true,\n test_type: 1,\n app_version: \"app_version_example\",\n net_type: 1,\n carrier: \"carrier_example\",\n web_auth: \"web_auth_example\",\n web_p256: \"web_p256_example\",\n },\n };\n\ntry {\n const response = await apiInstance.updateSubscriptionByToken(appId, tokenType, token, subscriptionBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateSubscriptionByToken failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # Your OneSignal App ID in UUID v4 format. \n token_type = \"Email\" # The type of token to use when looking up the subscription. See Subscription Types. \n token = \"user@example.com\" # The value of the token to lookup by (e.g., email address, phone number). \n subscription_body = SubscriptionBody(\n subscription=Subscription(\n id=\"id_example\",\n type=\"iOSPush\",\n token=\"token_example\",\n enabled=True,\n notification_types=1,\n session_time=1,\n session_count=1,\n sdk=\"sdk_example\",\n device_model=\"device_model_example\",\n device_os=\"device_os_example\",\n rooted=True,\n test_type=1,\n app_version=\"app_version_example\",\n net_type=1,\n carrier=\"carrier_example\",\n web_auth=\"web_auth_example\",\n web_p256=\"web_p256_example\",\n ),\n ) \n\n try:\n # Update subscription by token\n api_response = api_instance.update_subscription_by_token(app_id, token_type, token, subscription_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_subscription_by_token: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | Your OneSignal App ID in UUID v4 format.\n$token_type = 'Email'; // string | The type of token to use when looking up the subscription. See Subscription Types.\n$token = 'user@example.com'; // string | The value of the token to lookup by (e.g., email address, phone number).\n$subscription_body = new \\onesignal\\client\\model\\SubscriptionBody(); // \\onesignal\\client\\model\\SubscriptionBody\n\ntry {\n $result = $apiInstance->updateSubscriptionByToken($app_id, $token_type, $token, $subscription_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateSubscriptionByToken: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateSubscriptionByToken: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | Your OneSignal App ID in UUID v4 format.\n tokenType := \"Email\" // string | The type of token to use when looking up the subscription. See Subscription Types.\n token := \"user@example.com\" // string | The value of the token to lookup by (e.g., email address, phone number).\n subscriptionBody := *onesignal.NewSubscriptionBody() // SubscriptionBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateSubscriptionByToken(restAuth, appId, tokenType, token).SubscriptionBody(subscriptionBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateSubscriptionByToken``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateSubscriptionByToken`: map[string]interface{}\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateSubscriptionByToken`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | Your OneSignal App ID in UUID v4 format.\ntoken_type = 'Email' # String | The type of token to use when looking up the subscription. See Subscription Types.\ntoken = 'user@example.com' # String | The value of the token to lookup by (e.g., email address, phone number).\nsubscription_body = OneSignal::SubscriptionBody.new # SubscriptionBody | \n\nbegin\n # Update subscription by token\n result = api_instance.update_subscription_by_token(app_id, token_type, token, subscription_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_subscription_by_token: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | Your OneSignal App ID in UUID v4 format.\n String tokenType = \"Email\"; // String | The type of token to use when looking up the subscription. See Subscription Types.\n String token = \"user@example.com\"; // String | The value of the token to lookup by (e.g., email address, phone number).\n SubscriptionBody subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n try {\n Object result = apiInstance.updateSubscriptionByToken(appId, tokenType, token, subscriptionBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateSubscriptionByToken\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateSubscriptionByTokenExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | Your OneSignal App ID in UUID v4 format.\n var tokenType = \"Email\"; // string | The type of token to use when looking up the subscription. See Subscription Types.\n var token = \"user@example.com\"; // string | The value of the token to lookup by (e.g., email address, phone number).\n var subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n\n try\n {\n // Update subscription by token\n Object result = apiInstance.UpdateSubscriptionByToken(appId, tokenType, token, subscriptionBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateSubscriptionByToken: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let token_type: &str = \"Email\";\n let token: &str = \"user@example.com\";\n let subscription_body: models::SubscriptionBody = todo!();\n\n match default_api::update_subscription_by_token(&configuration, app_id, token_type, token, subscription_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_subscription_by_token failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_subscription_by_token failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "token_type", "in": "path", "description": "The subscription channel type. Must match the format of the token.", "schema": { "type": "string", "enum": [ "Email", "SMS", "iOSPush", "AndroidPush", "HuaweiPush", "FireOSPush", "WindowsPush", "macOSPush", "ChromeExtensionPush", "ChromePush", "FirefoxPush", "SafariPush" ] }, "required": true }, { "name": "token", "in": "path", "description": "The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "description": "The subscription's properties.", "required": [ "type", "token" ], "properties": { "enabled": { "type": "boolean", "description": "Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).", "format": "int32" }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version." }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." } } } } } } } }, "responses": { "202": { "description": "202", "content": { "application/json": { "schema": { "type": "object", "description": "The Subscription update request has been accepted successfully. This process is asynchronous and may take a few seconds to complete." } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } } } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions": { "post": { "summary": "Create Subscription by alias", "description": "Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.", "operationId": "create-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n// SubscriptionBody\nconst subscriptionBody: Onesignal.SubscriptionBody = {\n subscription: {\n id: \"id_example\",\n type: \"iOSPush\",\n token: \"token_example\",\n enabled: true,\n notification_types: 1,\n session_time: 1,\n session_count: 1,\n sdk: \"sdk_example\",\n device_model: \"device_model_example\",\n device_os: \"device_os_example\",\n rooted: true,\n test_type: 1,\n app_version: \"app_version_example\",\n net_type: 1,\n carrier: \"carrier_example\",\n web_auth: \"web_auth_example\",\n web_p256: \"web_p256_example\",\n },\n };\n\ntry {\n const response = await apiInstance.createSubscription(appId, aliasLabel, aliasId, subscriptionBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createSubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n subscription_body = SubscriptionBody(\n subscription=Subscription(\n id=\"id_example\",\n type=\"iOSPush\",\n token=\"token_example\",\n enabled=True,\n notification_types=1,\n session_time=1,\n session_count=1,\n sdk=\"sdk_example\",\n device_model=\"device_model_example\",\n device_os=\"device_os_example\",\n rooted=True,\n test_type=1,\n app_version=\"app_version_example\",\n net_type=1,\n carrier=\"carrier_example\",\n web_auth=\"web_auth_example\",\n web_p256=\"web_p256_example\",\n ),\n ) \n\n try:\n api_response = api_instance.create_subscription(app_id, alias_label, alias_id, subscription_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n$subscription_body = new \\onesignal\\client\\model\\SubscriptionBody(); // \\onesignal\\client\\model\\SubscriptionBody\n\ntry {\n $result = $apiInstance->createSubscription($app_id, $alias_label, $alias_id, $subscription_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createSubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createSubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n subscriptionBody := *onesignal.NewSubscriptionBody() // SubscriptionBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateSubscription(restAuth, appId, aliasLabel, aliasId).SubscriptionBody(subscriptionBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateSubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateSubscription`: SubscriptionBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateSubscription`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \nsubscription_body = OneSignal::SubscriptionBody.new # SubscriptionBody | \n\nbegin\n \n result = api_instance.create_subscription(app_id, alias_label, alias_id, subscription_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n SubscriptionBody subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n try {\n SubscriptionBody result = apiInstance.createSubscription(appId, aliasLabel, aliasId, subscriptionBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createSubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateSubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n var subscriptionBody = new SubscriptionBody(); // SubscriptionBody | \n\n try\n {\n SubscriptionBody result = apiInstance.CreateSubscription(appId, aliasLabel, aliasId, subscriptionBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateSubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n let subscription_body: models::SubscriptionBody = todo!();\n\n match default_api::create_subscription(&configuration, app_id, alias_label, alias_id, subscription_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string", "default": "external_id" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "type": "object", "description": "The subscription's properties.", "required": [ "type", "token" ], "properties": { "type": { "type": "string", "description": "The subscription channel type. Must match the format of the token.", "enum": [ "Email", "SMS", "iOSPush", "AndroidPush", "HuaweiPush", "FireOSPush", "WindowsPush", "macOSPush", "ChromeExtensionPush", "ChromePush", "SafariLegacyPush", "FirefoxPush", "SafariPush" ] }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore." }, "enabled": { "type": "boolean", "description": "Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).", "format": "int32" }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version." }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "New subscription created": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "202": { "description": "202", "content": { "application/json": { "examples": { "Existing subscription transferred": { "value": { "subscription": { "id": "29131af9-ccfc-4398-89bb-9a4663941f14", "app_id": "1db1662c-7609-4a90-b0ad-15b45407d628", "type": "Email", "token": "new-email@test.com", "enabled": true, "notification_types": -99, "session_time": 0, "session_count": 1, "sdk": "", "device_model": "", "device_os": "", "rooted": false, "test_type": 0, "app_version": "", "net_type": 0, "carrier": "", "web_auth": "", "web_p256": "" } } } }, "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique Subscription ID in UUID v4 format." }, "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids)." }, "type": { "type": "string", "description": "The subscription channel type." }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription." }, "enabled": { "type": "boolean", "description": "Indicates if the Subscription is subscribed (`true`) or unsubscribed (`false`)." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types)." }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Indicates the OneSignal SDK version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "rooted": { "type": "boolean", "description": "Indicates if the Android device is jail-broken." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "net_type": { "type": "integer", "example": 0, "default": 0 }, "carrier": { "type": "string", "example": "" }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK." } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Details about the error." ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Details about the error." ] } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "subscription-0", "title": "Subscription not found" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}": { "patch": { "summary": "Update user", "description": "Modify a user's properties.", "operationId": "update-user", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n// UpdateUserRequest\nconst updateUserRequest: Onesignal.UpdateUserRequest = {\n properties: {\n tags: {},\n language: \"language_example\",\n timezone_id: \"timezone_id_example\",\n lat: 3.14,\n long: 3.14,\n country: \"country_example\",\n first_active: 1,\n last_active: 1,\n amount_spent: 3.14,\n purchases: [\n {\n sku: \"sku_example\",\n amount: \"amount_example\",\n iso: \"iso_example\",\n count: 1,\n },\n ],\n ip: \"ip_example\",\n },\n refresh_device_metadata: false,\n deltas: {\n session_time: 1,\n session_count: 1,\n purchases: [\n {\n sku: \"sku_example\",\n amount: \"amount_example\",\n iso: \"iso_example\",\n count: 1,\n },\n ],\n },\n };\n\ntry {\n const response = await apiInstance.updateUser(appId, aliasLabel, aliasId, updateUserRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateUser failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n update_user_request = UpdateUserRequest(\n properties=PropertiesObject(\n tags={},\n language=\"language_example\",\n timezone_id=\"timezone_id_example\",\n lat=3.14,\n long=3.14,\n country=\"country_example\",\n first_active=1,\n last_active=1,\n amount_spent=3.14,\n purchases=[\n Purchase(\n sku=\"sku_example\",\n amount=\"amount_example\",\n iso=\"iso_example\",\n count=1,\n ),\n ],\n ip=\"ip_example\",\n ),\n refresh_device_metadata=False,\n deltas=PropertiesDeltas(\n session_time=1,\n session_count=1,\n purchases=[\n Purchase(\n sku=\"sku_example\",\n amount=\"amount_example\",\n iso=\"iso_example\",\n count=1,\n ),\n ],\n ),\n ) \n\n try:\n api_response = api_instance.update_user(app_id, alias_label, alias_id, update_user_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_user: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n$update_user_request = new \\onesignal\\client\\model\\UpdateUserRequest(); // \\onesignal\\client\\model\\UpdateUserRequest\n\ntry {\n $result = $apiInstance->updateUser($app_id, $alias_label, $alias_id, $update_user_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateUser: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateUser: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n updateUserRequest := *onesignal.NewUpdateUserRequest() // UpdateUserRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateUser(restAuth, appId, aliasLabel, aliasId).UpdateUserRequest(updateUserRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateUser``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateUser`: PropertiesBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateUser`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \nupdate_user_request = OneSignal::UpdateUserRequest.new # UpdateUserRequest | \n\nbegin\n \n result = api_instance.update_user(app_id, alias_label, alias_id, update_user_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_user: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n UpdateUserRequest updateUserRequest = new UpdateUserRequest(); // UpdateUserRequest | \n try {\n PropertiesBody result = apiInstance.updateUser(appId, aliasLabel, aliasId, updateUserRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateUser\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateUserExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n var updateUserRequest = new UpdateUserRequest(); // UpdateUserRequest | \n\n try\n {\n PropertiesBody result = apiInstance.UpdateUser(appId, aliasLabel, aliasId, updateUserRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateUser: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n let update_user_request: models::UpdateUserRequest = todo!();\n\n match default_api::update_user(&configuration, app_id, alias_label, alias_id, update_user_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_user failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_user failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "onesignal-subscription-id", "in": "header", "description": "Optional. Identifies a specific subscription to update. Some user properties, such as Session Time and Session Count, will update values on both the User and the Subscription.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "type": "object", "description": "Represents user profile data for a given user, including tags, preferences, user activity, and other valuable properties.", "properties": { "tags": { "type": "object", "description": "Custom user events or properties made of key-value pairs of string values. See [Tags](/docs/en/add-user-data-tags). Does not support arrays or other nested objects. Example: `{'foo':'bar','this':'that'}`", "format": "json" }, "language": { "type": "string", "description": "Language Abbreviation in ISO 639-1 format. See [supported languages](/docs/en/multi-language-messaging#supported-languages). Must be lower-case.", "default": "en" }, "timezone_id": { "type": "string", "description": "Timezone ID based on the [tz database \"TZ identifier\"](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).", "default": "America/Los_Angeles" }, "lat": { "type": "number", "description": "User's current latitude. Acceptable values range between `-90` to `90`.", "format": "float" }, "long": { "type": "number", "description": "User's current longitude. Acceptable values range between `-180` to `180`.", "format": "float" }, "country": { "type": "string", "description": "Country code in [ISO 3166-1 Alpha 2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Must be upper-case.", "default": "US" }, "first_active": { "type": "integer", "description": "Unix timestamp in seconds representing when the user was created.", "format": "int32" }, "last_active": { "type": "integer", "description": "Unix timestamp in seconds representing the most recent time the user was active in your app.", "format": "int32" }, "ip": { "type": "string", "description": "IPv4 or IPv6, response only" }, "test_user_name": { "type": "string", "description": "A label for marking this user as a [Test user](/docs/en/test-users)." } } }, "deltas": { "type": "object", "description": "User properties that change frequently and generally only increment.", "properties": { "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "purchases": { "type": "array", "description": "List of purchases", "items": { "properties": { "sku": { "type": "string", "description": "The SKU of the item purchased." }, "iso": { "type": "string", "description": "The Currency Code", "default": "USD" }, "amount": { "type": "string", "description": "The amount spent on the item." }, "count": { "type": "integer", "description": "The number of times the item has been purchased." } }, "type": "object" } } } } } } } } }, "responses": { "202": { "description": "202", "content": { "application/json": { "examples": { "Result": { "value": { "properties": { "language": "en", "timezone_id": "PST", "lat": 90, "long": 135, "country": "US", "first_active": 1678215680, "last_active": 1678215682, "test_user_name": "QA Device - Jane", "purchases": [ { "amount": "$33.33", "count": 3, "iso": "USD", "sku": "item" } ] } } } }, "schema": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "language": { "type": "string", "example": "en" }, "timezone_id": { "type": "string", "example": "PST" }, "lat": { "type": "integer", "example": 90, "default": 0 }, "long": { "type": "integer", "example": 135, "default": 0 }, "country": { "type": "string", "example": "US" }, "first_active": { "type": "integer", "example": 1678215680, "default": 0 }, "last_active": { "type": "integer", "example": 1678215682, "default": 0 }, "test_user_name": { "type": "string", "example": "QA Device - Jane" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "example": "$33.33" }, "count": { "type": "integer", "example": 3, "default": 0 }, "iso": { "type": "string", "example": "USD" }, "sku": { "type": "string", "example": "item" } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "auth-1", "title": "This operation requires 'Authorization' in the HTTP header" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "409": { "description": "409", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Subscription Limit Exceeded", "title": "Example error title" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "get": { "summary": "View user", "description": "Retrieve a user including aliases, properties, and subscriptions.", "operationId": "view-user", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n\ntry {\n const response = await apiInstance.getUser(appId, aliasLabel, aliasId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getUser failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n\n try:\n api_response = api_instance.get_user(app_id, alias_label, alias_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_user: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n\ntry {\n $result = $apiInstance->getUser($app_id, $alias_label, $alias_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getUser: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getUser: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetUser(restAuth, appId, aliasLabel, aliasId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetUser``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetUser`: User\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetUser`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \n\nbegin\n \n result = api_instance.get_user(app_id, alias_label, alias_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_user: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n try {\n User result = apiInstance.getUser(appId, aliasLabel, aliasId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getUser\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetUserExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n\n try\n {\n User result = apiInstance.GetUser(appId, aliasLabel, aliasId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetUser: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n\n match default_api::get_user(&configuration, app_id, alias_label, alias_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_user failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_user failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "properties": { "tags": { "KEY": "VALUE" }, "country": "US", "first_active": 1673449251, "last_active": 1678126124, "test_user_name": "QA Device - Jane" }, "identity": { "external_id": "example123", "onesignal_id": "ONESIGNAL_ID" }, "subscriptions": [ { "id": "SUBSCRIPTION_ID", "app_id": "APP_ID", "type": "Email", "token": "example@example.com", "enabled": true, "notification_types": -99, "session_time": 3670, "session_count": 129, "sdk": "", "device_model": "", "device_os": "", "rooted": false, "test_type": 0, "app_version": "", "net_type": 0, "carrier": "", "web_auth": "", "web_p256": "" } ] } } }, "schema": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "tags": { "type": "object", "properties": { "KEY": { "type": "string", "example": "VALUE" } } }, "country": { "type": "string", "example": "US" }, "first_active": { "type": "integer", "example": 1673449251, "default": 0 }, "last_active": { "type": "integer", "example": 1678126124, "default": 0 }, "test_user_name": { "type": "string", "example": "QA Device - Jane" } } }, "identity": { "type": "object", "properties": { "external_id": { "type": "string", "example": "example123" }, "onesignal_id": { "type": "string", "example": "ONESIGNAL_ID" } } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique Subscription ID in UUID v4 format." }, "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids)." }, "type": { "type": "string", "description": "The subscription channel type." }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription." }, "enabled": { "type": "boolean", "description": "Indicates if the Subscription is subscribed (`true`) or unsubscribed (`false`)." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the Subscription's status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types)." }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Indicates the OneSignal SDK version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "rooted": { "type": "boolean", "description": "Indicates if the Android device is jail-broken." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "net_type": { "type": "integer", "example": 0, "default": 0 }, "carrier": { "type": "string", "example": "" }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK." } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "auth-1", "title": "This operation requires 'Authorization' in the HTTP header" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "delete": { "summary": "Delete user", "description": "Delete a user including all associated properties, subscriptions, and identity.", "operationId": "delete-user", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n\ntry {\n const response = await apiInstance.deleteUser(appId, aliasLabel, aliasId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteUser failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n\n try:\n api_instance.delete_user(app_id, alias_label, alias_id)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_user: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n\ntry {\n $apiInstance->deleteUser($app_id, $alias_label, $alias_id);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteUser: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteUser: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n r, err := apiClient.DefaultApi.DeleteUser(restAuth, appId, aliasLabel, aliasId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteUser``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \n\nbegin\n \n api_instance.delete_user(app_id, alias_label, alias_id)\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_user: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n try {\n apiInstance.deleteUser(appId, aliasLabel, aliasId);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteUser\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteUserExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n\n try\n {\n apiInstance.DeleteUser(appId, aliasLabel, aliasId);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteUser: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n\n match default_api::delete_user(&configuration, app_id, alias_label, alias_id).await {\n Ok(_) => println!(\"delete_user succeeded\"),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_user failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_user failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "202": { "description": "202", "content": { "application/json": { "examples": { "Result": { "value": { "identity": { "onesignal_id": "567491ee-9105-4a87-9cbc-ed78a571645b" } } } }, "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "example": "567491ee-9105-4a87-9cbc-ed78a571645b" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "auth-1", "title": "This operation requires 'Authorization' in the HTTP header" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "409": { "description": "409", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Subscription Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users": { "x-mcp": { "enabled": true }, "post": { "summary": "Create user", "description": "Create a new user or modify the subscriptions associated with an existing User.", "operationId": "create-user", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// User\nconst user: Onesignal.User = {\n properties: {\n tags: {},\n language: \"language_example\",\n timezone_id: \"timezone_id_example\",\n lat: 3.14,\n long: 3.14,\n country: \"country_example\",\n first_active: 1,\n last_active: 1,\n amount_spent: 3.14,\n purchases: [\n {\n sku: \"sku_example\",\n amount: \"amount_example\",\n iso: \"iso_example\",\n count: 1,\n },\n ],\n ip: \"ip_example\",\n },\n identity: {\n \"key\": \"key_example\",\n },\n subscriptions: [\n {\n id: \"id_example\",\n type: \"iOSPush\",\n token: \"token_example\",\n enabled: true,\n notification_types: 1,\n session_time: 1,\n session_count: 1,\n sdk: \"sdk_example\",\n device_model: \"device_model_example\",\n device_os: \"device_os_example\",\n rooted: true,\n test_type: 1,\n app_version: \"app_version_example\",\n net_type: 1,\n carrier: \"carrier_example\",\n web_auth: \"web_auth_example\",\n web_p256: \"web_p256_example\",\n },\n ],\n };\n\ntry {\n const response = await apiInstance.createUser(appId, user);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createUser failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n user = User(\n properties=PropertiesObject(\n tags={},\n language=\"language_example\",\n timezone_id=\"timezone_id_example\",\n lat=3.14,\n long=3.14,\n country=\"country_example\",\n first_active=1,\n last_active=1,\n amount_spent=3.14,\n purchases=[\n Purchase(\n sku=\"sku_example\",\n amount=\"amount_example\",\n iso=\"iso_example\",\n count=1,\n ),\n ],\n ip=\"ip_example\",\n ),\n identity=IdentityObject(\n key=\"key_example\",\n ),\n subscriptions=[\n Subscription(\n id=\"id_example\",\n type=\"iOSPush\",\n token=\"token_example\",\n enabled=True,\n notification_types=1,\n session_time=1,\n session_count=1,\n sdk=\"sdk_example\",\n device_model=\"device_model_example\",\n device_os=\"device_os_example\",\n rooted=True,\n test_type=1,\n app_version=\"app_version_example\",\n net_type=1,\n carrier=\"carrier_example\",\n web_auth=\"web_auth_example\",\n web_p256=\"web_p256_example\",\n ),\n ],\n ) \n\n try:\n api_response = api_instance.create_user(app_id, user)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_user: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$user = new \\onesignal\\client\\model\\User(); // \\onesignal\\client\\model\\User\n\ntry {\n $result = $apiInstance->createUser($app_id, $user);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createUser: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createUser: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n user := *onesignal.NewUser() // User | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateUser(restAuth, appId).User(user).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateUser``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateUser`: User\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateUser`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nuser = OneSignal::User.new # User | \n\nbegin\n \n result = api_instance.create_user(app_id, user)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_user: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n User user = new User(); // User | \n try {\n User result = apiInstance.createUser(appId, user);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createUser\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateUserExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var user = new User(); // User | \n\n try\n {\n User result = apiInstance.CreateUser(appId, user);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateUser: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let user: models::User = todo!();\n\n match default_api::create_user(&configuration, app_id, user).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_user failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_user failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "type": "object", "description": "Represents user profile data for a given user, including tags, preferences, user activity, and other valuable properties.", "properties": { "tags": { "type": "object", "description": "Custom user events or properties made of key-value pairs of string values. See [Tags](/docs/en/add-user-data-tags). Does not support arrays or other nested objects. Example: `{'foo':'bar','this':'that'}`", "format": "json" }, "language": { "type": "string", "description": "Language Abbreviation in ISO 639-1 format. See [supported languages](/docs/en/multi-language-messaging#supported-languages). Must be lower-case.", "default": "en" }, "timezone_id": { "type": "string", "description": "Timezone ID based on the [tz database \"TZ identifier\"](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).", "default": "America/Los_Angeles" }, "lat": { "type": "number", "description": "User's current latitude. Acceptable values range between `-90` to `90`.", "format": "float" }, "long": { "type": "number", "description": "User's current longitude. Acceptable values range between `-180` to `180`.", "format": "float" }, "country": { "type": "string", "description": "Country code in [ISO 3166-1 Alpha 2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Must be upper-case.", "default": "US" }, "first_active": { "type": "integer", "description": "Unix timestamp in seconds representing when the user was created.", "format": "int32" }, "last_active": { "type": "integer", "description": "Unix timestamp in seconds representing the most recent time the user was active in your app.", "format": "int32" }, "ip": { "type": "string", "description": "IPv4 or IPv6, response only" }, "test_user_name": { "type": "string", "description": "A label for marking this user as a [Test user](/docs/en/test-users)." } } }, "identity": { "type": "object", "description": "Defines identifiers for the user. The `external_id` must be used and should be unique across users.", "properties": { "external_id": { "type": "string", "description": "The main user ID to identify the user. See [Users](/docs/users)." } } }, "subscriptions": { "type": "array", "description": "The subscriptions object allows for creating or transferring subscriptions to a specified user. See [Subscriptions](/docs/subscriptions).", "items": { "properties": { "type": { "type": "string", "description": "The subscription channel type. Must match the format of the token..", "enum": [ "Email", "SMS", "iOSPush", "AndroidPush", "HuaweiPush", "FireOSPush", "WindowsPush", "macOSPush", "ChromePush", "FirefoxPush", "SafariPush" ] }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore." }, "enabled": { "type": "boolean", "description": "Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed." }, "notification_types": { "type": "integer", "description": "Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).", "format": "int32" }, "session_time": { "type": "integer", "description": "The total amount of time the user has had the app open in seconds.", "format": "int32" }, "session_count": { "type": "integer", "description": "The total amount of times the user has opened the app.", "format": "int32" }, "app_version": { "type": "string", "description": "The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version." }, "device_model": { "type": "string", "description": "The model of the user's device (e.g., iPhone 16)." }, "device_os": { "type": "string", "description": "The device or browser's system version." }, "test_type": { "type": "integer", "description": "Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.", "format": "int32" }, "sdk": { "type": "string", "description": "Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version." }, "web_auth": { "type": "string", "description": "The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." }, "web_p256": { "type": "string", "description": "The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal)." } }, "required": [ "type", "token" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "New user created": { "value": { "identity": { "onesignal_id": "567491ee-9105-4a87-9cbc-ed78a571645b" }, "properties": { "tags": { "first_name": "John", "last_name": "Smith" } } } } }, "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "example": "567491ee-9105-4a87-9cbc-ed78a571645b" } } }, "properties": { "type": "object", "properties": { "tags": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" } } } } } } } } } }, "202": { "description": "202", "content": { "application/json": { "examples": { "Existing user modified": { "value": { "identity": { "onesignal_id": "567491ee-9105-4a87-9cbc-ed78a571645b", "external_id": "test_external_id-101101" }, "subscriptions": [ { "id": "f67491ee-9105-4a87-9cbc-ed78a571645b", "app_id": "a67491ee-9105-4a87-9cbc-ed78a571645b", "token": "joe@example.com", "type": "email" } ], "properties": { "tags": { "color": "red" } } } } }, "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "example": "567491ee-9105-4a87-9cbc-ed78a571645b" }, "external_id": { "type": "string", "example": "test_external_id-101101" } } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique Subscription ID in UUID v4 format." }, "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format." }, "token": { "type": "string", "description": "The push token, email address, or phone number associated with the subscription." }, "type": { "type": "string", "description": "The subscription channel type." } } } }, "properties": { "type": "object", "properties": { "tags": { "type": "object", "properties": { "color": { "type": "string", "example": "red" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "409": { "description": "Conflict. The request's claimed identity (one or more aliases or external_id) is already bound to a different user. `errors[].meta.conflicting_aliases` lists each colliding alias label and the conflicting alias ID.", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/CreateUserConflictResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity": { "get": { "summary": "View user identity", "description": "Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.", "operationId": "fetch-aliases", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n\ntry {\n const response = await apiInstance.getAliases(appId, aliasLabel, aliasId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getAliases failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n\n try:\n api_response = api_instance.get_aliases(app_id, alias_label, alias_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_aliases: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n\ntry {\n $result = $apiInstance->getAliases($app_id, $alias_label, $alias_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getAliases: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getAliases: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetAliases(restAuth, appId, aliasLabel, aliasId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetAliases``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetAliases`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetAliases`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \n\nbegin\n \n result = api_instance.get_aliases(app_id, alias_label, alias_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_aliases: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n try {\n UserIdentityBody result = apiInstance.getAliases(appId, aliasLabel, aliasId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getAliases\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetAliasesExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n\n try\n {\n UserIdentityBody result = apiInstance.GetAliases(appId, aliasLabel, aliasId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetAliases: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n\n match default_api::get_aliases(&configuration, app_id, alias_label, alias_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_aliases failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_aliases failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "description": "The OneSignal ID of the user. See [Users](/docs/users).", "example": "OneSignal-ID-in-UUID-v4-format" }, "external_id": { "type": "string", "description": "The External ID of the user. See [Users](/docs/users).", "example": "the-users-external-id" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "patch": { "summary": "Create or update alias", "description": "Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.", "operationId": "create-alias", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n// UserIdentityBody\nconst userIdentityBody: Onesignal.UserIdentityBody = {\n identity: {\n \"key\": \"key_example\",\n },\n };\n\ntry {\n const response = await apiInstance.createAlias(appId, aliasLabel, aliasId, userIdentityBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createAlias failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n user_identity_body = UserIdentityBody(\n identity=IdentityObject(\n key=\"key_example\",\n ),\n ) \n\n try:\n api_response = api_instance.create_alias(app_id, alias_label, alias_id, user_identity_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_alias: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n$user_identity_body = new \\onesignal\\client\\model\\UserIdentityBody(); // \\onesignal\\client\\model\\UserIdentityBody\n\ntry {\n $result = $apiInstance->createAlias($app_id, $alias_label, $alias_id, $user_identity_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createAlias: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createAlias: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n userIdentityBody := *onesignal.NewUserIdentityBody() // UserIdentityBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateAlias(restAuth, appId, aliasLabel, aliasId).UserIdentityBody(userIdentityBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateAlias``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateAlias`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateAlias`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \nuser_identity_body = OneSignal::UserIdentityBody.new # UserIdentityBody | \n\nbegin\n \n result = api_instance.create_alias(app_id, alias_label, alias_id, user_identity_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_alias: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n UserIdentityBody userIdentityBody = new UserIdentityBody(); // UserIdentityBody | \n try {\n UserIdentityBody result = apiInstance.createAlias(appId, aliasLabel, aliasId, userIdentityBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createAlias\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateAliasExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n var userIdentityBody = new UserIdentityBody(); // UserIdentityBody | \n\n try\n {\n UserIdentityBody result = apiInstance.CreateAlias(appId, aliasLabel, aliasId, userIdentityBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateAlias: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n let user_identity_body: models::UserIdentityBody = todo!();\n\n match default_api::create_alias(&configuration, app_id, alias_label, alias_id, user_identity_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_alias failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_alias failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "description": "One or more aliases to be created for this user.", "properties": { "external_id": { "type": "string", "description": "The main user ID to identify the user. See [Users](/docs/users).", "default": "test_external_id" }, "onesignal_id": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "description": "The OneSignal ID of the user. See [Users](/docs/users).", "example": "OneSignal-ID-in-UUID-v4-format" }, "custom_alias_label": { "type": "string", "description": "A custom alias of the user. See [Aliases](/docs/aliases).", "example": "the-users-custom-alias-id" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "request-1", "title": "Invalid UUID", "meta": { "onesignal_id": "123" } } ] } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "request-1" }, "title": { "type": "string", "example": "Invalid UUID" }, "meta": { "type": "object", "properties": { "onesignal_id": { "type": "string", "example": "123" } } } } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "409": { "description": "409", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Subscription Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/subscriptions/{subscription_id}/owner": { "patch": { "summary": "Transfer subscription", "description": "Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.", "operationId": "transfer-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst subscriptionId: string = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n// TransferSubscriptionRequestBody\nconst transferSubscriptionRequestBody: Onesignal.TransferSubscriptionRequestBody = {\n identity: {\n \"key\": \"key_example\",\n },\n };\n\ntry {\n const response = await apiInstance.transferSubscription(appId, subscriptionId, transferSubscriptionRequestBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"transferSubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n subscription_id = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" \n transfer_subscription_request_body = TransferSubscriptionRequestBody(\n identity={\n \"key\": \"key_example\",\n },\n ) \n\n try:\n api_response = api_instance.transfer_subscription(app_id, subscription_id, transfer_subscription_request_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->transfer_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$subscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51'; // string\n$transfer_subscription_request_body = new \\onesignal\\client\\model\\TransferSubscriptionRequestBody(); // \\onesignal\\client\\model\\TransferSubscriptionRequestBody\n\ntry {\n $result = $apiInstance->transferSubscription($app_id, $subscription_id, $transfer_subscription_request_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->transferSubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->transferSubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n subscriptionId := \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" // string | \n transferSubscriptionRequestBody := *onesignal.NewTransferSubscriptionRequestBody() // TransferSubscriptionRequestBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.TransferSubscription(restAuth, appId, subscriptionId).TransferSubscriptionRequestBody(transferSubscriptionRequestBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.TransferSubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `TransferSubscription`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.TransferSubscription`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nsubscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51' # String | \ntransfer_subscription_request_body = OneSignal::TransferSubscriptionRequestBody.new # TransferSubscriptionRequestBody | \n\nbegin\n \n result = api_instance.transfer_subscription(app_id, subscription_id, transfer_subscription_request_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->transfer_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // String | \n TransferSubscriptionRequestBody transferSubscriptionRequestBody = new TransferSubscriptionRequestBody(); // TransferSubscriptionRequestBody | \n try {\n UserIdentityBody result = apiInstance.transferSubscription(appId, subscriptionId, transferSubscriptionRequestBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#transferSubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class TransferSubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // string | \n var transferSubscriptionRequestBody = new TransferSubscriptionRequestBody(); // TransferSubscriptionRequestBody | \n\n try\n {\n UserIdentityBody result = apiInstance.TransferSubscription(appId, subscriptionId, transferSubscriptionRequestBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.TransferSubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let subscription_id: &str = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n let transfer_subscription_request_body: models::TransferSubscriptionRequestBody = todo!();\n\n match default_api::transfer_subscription(&configuration, app_id, subscription_id, transfer_subscription_request_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"transfer_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"transfer_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "subscription_id", "in": "path", "description": "The unique Subscription ID in UUID v4 format to transfer to the new user.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "description": "Identifies the user that this subscription is moved to. Must contain exactly one alias.", "properties": { "external_id": { "type": "string", "description": "The main user ID to identify the user. See [Users](/docs/users).", "default": "test_external_id" }, "onesignal_id": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "identity": { "external_id": "the-external-id-transferred-to", "onesignal_id": "the-onesignal-id-transferred-to" } } } }, "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "external_id": { "type": "string", "example": "the-external-id-transferred-to" }, "onesignal_id": { "type": "string", "example": "the-onesignal-id-transferred-to" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Details about the error." ] } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Forbidden" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "subscription-0", "title": "Subscription not found" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/subscriptions/{subscription_id}/user/identity": { "get": { "summary": "View user identity (by subscription)", "description": "Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.", "operationId": "fetch-identity-by-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst subscriptionId: string = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n\ntry {\n const response = await apiInstance.getAliasesBySubscription(appId, subscriptionId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getAliasesBySubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n subscription_id = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" \n\n try:\n api_response = api_instance.get_aliases_by_subscription(app_id, subscription_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_aliases_by_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$subscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51'; // string\n\ntry {\n $result = $apiInstance->getAliasesBySubscription($app_id, $subscription_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getAliasesBySubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getAliasesBySubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n subscriptionId := \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetAliasesBySubscription(restAuth, appId, subscriptionId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetAliasesBySubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetAliasesBySubscription`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetAliasesBySubscription`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nsubscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51' # String | \n\nbegin\n \n result = api_instance.get_aliases_by_subscription(app_id, subscription_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_aliases_by_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // String | \n try {\n UserIdentityBody result = apiInstance.getAliasesBySubscription(appId, subscriptionId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getAliasesBySubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetAliasesBySubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // string | \n\n try\n {\n UserIdentityBody result = apiInstance.GetAliasesBySubscription(appId, subscriptionId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetAliasesBySubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let subscription_id: &str = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n\n match default_api::get_aliases_by_subscription(&configuration, app_id, subscription_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_aliases_by_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_aliases_by_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "subscription_id", "in": "path", "description": "The unique Subscription ID in UUID v4 format generated by OneSignal. See [Subscriptions](/docs/subscriptions).", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "description": "The OneSignal ID of the user. See [Users](/docs/users).", "example": "OneSignal-ID-in-UUID-v4-format" }, "external_id": { "type": "string", "description": "The External ID of the user. See [Users](/docs/users).", "example": "the-users-external-id" }, "custom_alias_label": { "type": "string", "description": "A custom alias of the user. See [Aliases](/docs/aliases).", "example": "the-users-custom-alias-id" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "patch": { "summary": "Create alias (by subscription)", "description": "Create or update an alias for a user using a known subscription ID.", "operationId": "create-alias-by-subscription", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst subscriptionId: string = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n// UserIdentityBody\nconst userIdentityBody: Onesignal.UserIdentityBody = {\n identity: {\n \"key\": \"key_example\",\n },\n };\n\ntry {\n const response = await apiInstance.createAliasBySubscription(appId, subscriptionId, userIdentityBody);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createAliasBySubscription failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n subscription_id = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" \n user_identity_body = UserIdentityBody(\n identity=IdentityObject(\n key=\"key_example\",\n ),\n ) \n\n try:\n api_response = api_instance.create_alias_by_subscription(app_id, subscription_id, user_identity_body)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_alias_by_subscription: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$subscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51'; // string\n$user_identity_body = new \\onesignal\\client\\model\\UserIdentityBody(); // \\onesignal\\client\\model\\UserIdentityBody\n\ntry {\n $result = $apiInstance->createAliasBySubscription($app_id, $subscription_id, $user_identity_body);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createAliasBySubscription: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createAliasBySubscription: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n subscriptionId := \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\" // string | \n userIdentityBody := *onesignal.NewUserIdentityBody() // UserIdentityBody | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateAliasBySubscription(restAuth, appId, subscriptionId).UserIdentityBody(userIdentityBody).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateAliasBySubscription``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateAliasBySubscription`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateAliasBySubscription`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nsubscription_id = '7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51' # String | \nuser_identity_body = OneSignal::UserIdentityBody.new # UserIdentityBody | \n\nbegin\n \n result = api_instance.create_alias_by_subscription(app_id, subscription_id, user_identity_body)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_alias_by_subscription: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // String | \n UserIdentityBody userIdentityBody = new UserIdentityBody(); // UserIdentityBody | \n try {\n UserIdentityBody result = apiInstance.createAliasBySubscription(appId, subscriptionId, userIdentityBody);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createAliasBySubscription\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateAliasBySubscriptionExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var subscriptionId = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\"; // string | \n var userIdentityBody = new UserIdentityBody(); // UserIdentityBody | \n\n try\n {\n UserIdentityBody result = apiInstance.CreateAliasBySubscription(appId, subscriptionId, userIdentityBody);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateAliasBySubscription: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let subscription_id: &str = \"7e4c5b9a-1f60-4d07-9b1a-2e8c8d2cae51\";\n let user_identity_body: models::UserIdentityBody = todo!();\n\n match default_api::create_alias_by_subscription(&configuration, app_id, subscription_id, user_identity_body).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_alias_by_subscription failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_alias_by_subscription failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "subscription_id", "in": "path", "description": "The unique Subscription ID in UUID v4 format generated by OneSignal. See [Subscriptions](/docs/subscriptions).", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "description": "One or more aliases to be created for this user.", "properties": { "external_id": { "type": "string", "description": "The main user ID to identify the user. See [Users](/docs/users).", "default": "test_external_id" }, "onesignal_id": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "identity": { "external_id": "example123", "onesignal_id": "ONESIGNAL_ID" } } } }, "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "external_id": { "type": "string", "example": "example123" }, "onesignal_id": { "type": "string", "example": "ONESIGNAL_ID" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "internal error code", "title": "example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Subscription Limit Exceeded", "title": "Example error title" } ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}": { "delete": { "summary": "Delete alias", "description": "Remove a specific alias from a user.", "operationId": "delete-alias", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst aliasLabel: string = \"external_id\";\n// string\nconst aliasId: string = \"YOUR_USER_EXTERNAL_ID\";\n// string\nconst aliasLabelToDelete: string = \"external_id\";\n\ntry {\n const response = await apiInstance.deleteAlias(appId, aliasLabel, aliasId, aliasLabelToDelete);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteAlias failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n alias_label = \"external_id\" \n alias_id = \"YOUR_USER_EXTERNAL_ID\" \n alias_label_to_delete = \"external_id\" \n\n try:\n api_response = api_instance.delete_alias(app_id, alias_label, alias_id, alias_label_to_delete)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_alias: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$alias_label = 'external_id'; // string\n$alias_id = 'YOUR_USER_EXTERNAL_ID'; // string\n$alias_label_to_delete = 'external_id'; // string\n\ntry {\n $result = $apiInstance->deleteAlias($app_id, $alias_label, $alias_id, $alias_label_to_delete);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteAlias: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteAlias: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n aliasLabel := \"external_id\" // string | \n aliasId := \"YOUR_USER_EXTERNAL_ID\" // string | \n aliasLabelToDelete := \"external_id\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.DeleteAlias(restAuth, appId, aliasLabel, aliasId, aliasLabelToDelete).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteAlias``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `DeleteAlias`: UserIdentityBody\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.DeleteAlias`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nalias_label = 'external_id' # String | \nalias_id = 'YOUR_USER_EXTERNAL_ID' # String | \nalias_label_to_delete = 'external_id' # String | \n\nbegin\n \n result = api_instance.delete_alias(app_id, alias_label, alias_id, alias_label_to_delete)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_alias: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String aliasLabel = \"external_id\"; // String | \n String aliasId = \"YOUR_USER_EXTERNAL_ID\"; // String | \n String aliasLabelToDelete = \"external_id\"; // String | \n try {\n UserIdentityBody result = apiInstance.deleteAlias(appId, aliasLabel, aliasId, aliasLabelToDelete);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteAlias\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteAliasExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var aliasLabel = \"external_id\"; // string | \n var aliasId = \"YOUR_USER_EXTERNAL_ID\"; // string | \n var aliasLabelToDelete = \"external_id\"; // string | \n\n try\n {\n UserIdentityBody result = apiInstance.DeleteAlias(appId, aliasLabel, aliasId, aliasLabelToDelete);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteAlias: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let alias_label: &str = \"external_id\";\n let alias_id: &str = \"YOUR_USER_EXTERNAL_ID\";\n let alias_label_to_delete: &str = \"external_id\";\n\n match default_api::delete_alias(&configuration, app_id, alias_label, alias_id, alias_label_to_delete).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_alias failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_alias failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string", "default": "external_id" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The specific identifier for the given alias to identify the user.", "schema": { "type": "string" }, "required": true }, { "name": "alias_label_to_delete", "in": "path", "description": "The name of the alias to remove.", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "onesignal_id": { "type": "string", "description": "The OneSignal ID of the user. See [Users](/docs/users).", "example": "OneSignal-ID-in-UUID-v4-format" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "internal error code", "title": "example error title" } ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/notifications/{message_id}/export_events": { "post": { "summary": "Export audience activity CSV", "description": "Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.", "operationId": "export-csv-of-events", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The ID of the notification to export events from.\nconst notificationId: string = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n// string | The ID of the app that the notification belongs to.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n\ntry {\n const response = await apiInstance.exportEvents(notificationId, appId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"exportEvents failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n notification_id = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" # The ID of the notification to export events from. \n app_id = \"00000000-0000-0000-0000-000000000000\" # The ID of the app that the notification belongs to. \n\n try:\n # Export CSV of Events\n api_response = api_instance.export_events(notification_id, app_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->export_events: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string | The ID of the notification to export events from.\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The ID of the app that the notification belongs to.\n\ntry {\n $result = $apiInstance->exportEvents($notification_id, $app_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->exportEvents: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->exportEvents: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n notificationId := \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" // string | The ID of the notification to export events from.\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The ID of the app that the notification belongs to.\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.ExportEvents(restAuth, notificationId).AppId(appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.ExportEvents``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `ExportEvents`: ExportEventsSuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.ExportEvents`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nnotification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | The ID of the notification to export events from.\napp_id = '00000000-0000-0000-0000-000000000000' # String | The ID of the app that the notification belongs to.\n\nbegin\n # Export CSV of Events\n result = api_instance.export_events(notification_id, app_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->export_events: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // String | The ID of the notification to export events from.\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The ID of the app that the notification belongs to.\n try {\n ExportEventsSuccessResponse result = apiInstance.exportEvents(notificationId, appId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#exportEvents\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class ExportEventsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // string | The ID of the notification to export events from.\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The ID of the app that the notification belongs to.\n\n try\n {\n // Export CSV of Events\n ExportEventsSuccessResponse result = apiInstance.ExportEvents(notificationId, appId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.ExportEvents: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let notification_id: &str = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n\n match default_api::export_events(&configuration, notification_id, app_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"export_events failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"export_events failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "message_id", "in": "path", "description": "The identifier of the message in UUID v4 format. Get this `id` in the response of your Create Message API request, the [View Messages API](/reference/view-messages), and in your OneSignal dashboard Message Reports.", "schema": { "type": "string", "default": "YOUR_NOTIFICATION_ID" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "csv_file_url": { "type": "string", "description": "The URL to download the CSV file. The file is available for 3 days after generation." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "The reason for the error. Usually an invalid `message_id` format or missing required path parameter." ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Missing or invalid REST API key for the app." ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "No message exists with the provided `message_id` in this app, or the message is older than 30 days and its audience activity has been purged." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/templates/{template_id}?app_id={app_id}": { "get": { "summary": "View template", "description": "Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.", "operationId": "view-template", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst templateId: string = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n\ntry {\n const response = await apiInstance.viewTemplate(templateId, appId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"viewTemplate failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n template_id = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" \n app_id = \"00000000-0000-0000-0000-000000000000\" \n\n try:\n # View template\n api_response = api_instance.view_template(template_id, app_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->view_template: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$template_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c'; // string\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n\ntry {\n $result = $apiInstance->viewTemplate($template_id, $app_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->viewTemplate: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->viewTemplate: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n templateId := \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" // string | \n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.ViewTemplate(restAuth, templateId).AppId(appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.ViewTemplate``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `ViewTemplate`: TemplateResource\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.ViewTemplate`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\ntemplate_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c' # String | \napp_id = '00000000-0000-0000-0000-000000000000' # String | \n\nbegin\n # View template\n result = api_instance.view_template(template_id, app_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->view_template: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // String | \n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n try {\n TemplateResource result = apiInstance.viewTemplate(templateId, appId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#viewTemplate\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class ViewTemplateExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // string | \n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n\n try\n {\n // View template\n TemplateResource result = apiInstance.ViewTemplate(templateId, appId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.ViewTemplate: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let template_id: &str = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n\n match default_api::view_template(&configuration, template_id, app_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"view_template failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"view_template failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "template_id", "in": "path", "description": "The template ID in UUID v4 format. See [Templates](/docs/en/templates).", "schema": { "type": "string", "default": "YOUR_TEMPLATE_ID" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "title": "200 OK - Push", "type": "object", "properties": { "id": { "type": "string", "description": "The template ID in UUID v4 format.", "example": "Template-ID-in-UUID-v4-format" }, "name": { "type": "string", "description": "An internal name you set to help organize and track Templates. Maximum 128 characters." }, "channel": { "type": "string", "description": "Options are: `push`, `email`, and `SMS`.", "example": "push" }, "created_at": { "type": "string", "description": "The date and time the template was created in ISO 8601 format.", "example": "2023-07-20T19:16:55Z" }, "updated_at": { "type": "string", "description": "The date and time the template was last updated in ISO 8601 format.", "example": "2023-07-20T19:16:55Z" }, "content": { "type": "object", "description": "The template content.", "properties": { "isAndroid": { "type": "boolean", "description": "Template enabled for Android." }, "isIos": { "type": "boolean", "description": "Template enabled for iOS." }, "isMacOSX": { "type": "boolean", "description": "Template enabled for macOS." }, "isAdm": { "type": "boolean", "description": "Template enabled for Amazon." }, "isWP_WNS": { "type": "boolean", "description": "Template enabled for Windows." }, "isChromeWeb": { "type": "boolean", "description": "Template enabled for Chrome Web." }, "isSafari": { "type": "boolean", "description": "Template enabled for Safari." }, "isFirefox": { "type": "boolean", "description": "Template enabled for Firefox." }, "isEdge": { "type": "boolean", "description": "Template enabled for Edge." }, "headings": { "type": "object", "properties": { "en": { "type": "string", "description": "The push message title in each set language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Personalization](/docs/en/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "global_image": {}, "url": { "type": "string", "example": "https://example.com" }, "isEmail": { "type": "boolean", "description": "Required to be set `true` for email templates." }, "email_body": { "type": "string", "description": "The body of the email in HTML format. Required if `template_id` is not set. Supports [Message Personalization](/docs/message-personalization)." }, "email_subject": { "description": "The subject of the email. Supports [Message Personalization](/docs/message-personalization).", "default": "This is your email subject." }, "email_preheader": { "description": "The preheader text of the email. Supports [Message Personalization](/docs/message-personalization)." }, "email_from_address": { "type": "string", "description": "The full email address shown in the 'From' field of the email (e.g., `promotions@news.example.com`). This is what recipients see as the sender. If not specified, OneSignal uses the default 'Sender Email' set in your Dashboard's Email Settings. See [Senders](/docs/senders)." }, "email_from_name": { "description": "The name of the sender." }, "isSMS": { "type": "boolean", "description": "Required to be set `true` for SMS templates." }, "sms_from": {}, "sms_media_urls": {}, "email_reply_to_address": {}, "disable_email_click_tracking": {} } } } }, { "title": "200 OK - Email", "type": "object", "properties": { "id": { "type": "string", "example": "05b5d060-5e07-40ec-953c-4f2b8be0c83e" }, "name": { "type": "string", "example": "An internal name you set to help organize and track Templates. Maximum 128 characters." }, "created_at": { "type": "string", "example": "2022-06-30T23:23:22Z" }, "updated_at": { "type": "string", "example": "2023-06-29T23:34:07Z" }, "content": { "type": "object", "properties": { "isAndroid": {}, "isIos": {}, "isMacOSX": {}, "isAdm": {}, "isAlexa": {}, "isWP": {}, "isWP_WNS": {}, "isChrome": {}, "isChromeWeb": {}, "isSafari": {}, "isFirefox": {}, "isEdge": {}, "headings": { "type": "object", "properties": {} }, "subtitle": {}, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "global_image": {}, "url": {}, "isEmail": { "type": "boolean", "description": "Required to be set `true` for email templates." }, "email_body": { "type": "string", "description": "The body of the email in HTML format. Required if `template_id` is not set. Supports [Message Personalization](/docs/message-personalization)." }, "email_subject": { "type": "string", "description": "The subject of the email. Supports [Message Personalization](/docs/message-personalization)." }, "email_preheader": { "type": "string", "example": "" }, "isSMS": { "type": "boolean", "description": "Required to be set `true` for SMS templates." }, "sms_from": {}, "sms_media_urls": {}, "email_reply_to_address": { "type": "string", "example": "" }, "disable_email_click_tracking": { "type": "boolean", "example": false, "default": true }, "email_from_address": { "type": "string", "example": "" }, "email_from_name": { "type": "string", "example": "" }, "email_bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 5, "description": "BCC recipients for the email template. Maximum 5 addresses. Only supported when the email service provider is OneSignal Email." } } } } } ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Request is malformed: Failed to parse app_id from request" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "template not found" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title" } ] } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] }, "delete": { "summary": "Delete template", "description": "Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.", "operationId": "delete-template", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst templateId: string = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n\ntry {\n const response = await apiInstance.deleteTemplate(templateId, appId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteTemplate failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n template_id = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" \n app_id = \"00000000-0000-0000-0000-000000000000\" \n\n try:\n # Delete template\n api_response = api_instance.delete_template(template_id, app_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_template: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$template_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c'; // string\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n\ntry {\n $result = $apiInstance->deleteTemplate($template_id, $app_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteTemplate: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteTemplate: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n templateId := \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" // string | \n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.DeleteTemplate(restAuth, templateId).AppId(appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteTemplate``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `DeleteTemplate`: GenericSuccessBoolResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.DeleteTemplate`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\ntemplate_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c' # String | \napp_id = '00000000-0000-0000-0000-000000000000' # String | \n\nbegin\n # Delete template\n result = api_instance.delete_template(template_id, app_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_template: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // String | \n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n try {\n GenericSuccessBoolResponse result = apiInstance.deleteTemplate(templateId, appId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteTemplate\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteTemplateExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // string | \n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n\n try\n {\n // Delete template\n GenericSuccessBoolResponse result = apiInstance.DeleteTemplate(templateId, appId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteTemplate: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let template_id: &str = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n\n match default_api::delete_template(&configuration, template_id, app_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_template failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_template failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "template_id", "in": "path", "description": "The template ID in UUID v4 format. See [Templates](/docs/en/templates).", "schema": { "type": "string", "default": "YOUR_TEMPLATE_ID" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App's API key found in [Settings > Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad Request (Missing App ID)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "example": "Request is malformed: Failed to parse app_id from request" } } } }, { "title": "Bad Request (Template In Use)", "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "string", "example": "Can not delete a template that has journeys using it." } } } } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "template not found" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title" } ] } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] }, "patch": { "summary": "Update template", "description": "Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.", "operationId": "update-template", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst templateId: string = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// UpdateTemplateRequest\nconst updateTemplateRequest: Onesignal.UpdateTemplateRequest = {\n name: \"name_example\",\n contents: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n headings: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n subtitle: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n is_email: true,\n email_subject: \"email_subject_example\",\n email_body: \"email_body_example\",\n email_bcc: [\n \"email_bcc_example\",\n ],\n is_sms: true,\n dynamic_content: \"dynamic_content_example\",\n };\n\ntry {\n const response = await apiInstance.updateTemplate(templateId, appId, updateTemplateRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateTemplate failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n template_id = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" \n app_id = \"00000000-0000-0000-0000-000000000000\" \n update_template_request = UpdateTemplateRequest(\n name=\"name_example\",\n contents=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n headings=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n subtitle=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n is_email=True,\n email_subject=\"email_subject_example\",\n email_body=\"email_body_example\",\n email_bcc=[\n \"email_bcc_example\",\n ],\n is_sms=True,\n dynamic_content=\"dynamic_content_example\",\n ) \n\n try:\n # Update template\n api_response = api_instance.update_template(template_id, app_id, update_template_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_template: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$template_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c'; // string\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$update_template_request = new \\onesignal\\client\\model\\UpdateTemplateRequest(); // \\onesignal\\client\\model\\UpdateTemplateRequest\n\ntry {\n $result = $apiInstance->updateTemplate($template_id, $app_id, $update_template_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateTemplate: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateTemplate: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n templateId := \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" // string | \n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n updateTemplateRequest := *onesignal.NewUpdateTemplateRequest() // UpdateTemplateRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateTemplate(restAuth, templateId).AppId(appId).UpdateTemplateRequest(updateTemplateRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateTemplate``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateTemplate`: TemplateResource\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateTemplate`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\ntemplate_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c' # String | \napp_id = '00000000-0000-0000-0000-000000000000' # String | \nupdate_template_request = OneSignal::UpdateTemplateRequest.new # UpdateTemplateRequest | \n\nbegin\n # Update template\n result = api_instance.update_template(template_id, app_id, update_template_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_template: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // String | \n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n UpdateTemplateRequest updateTemplateRequest = new UpdateTemplateRequest(); // UpdateTemplateRequest | \n try {\n TemplateResource result = apiInstance.updateTemplate(templateId, appId, updateTemplateRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateTemplate\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateTemplateExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // string | \n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var updateTemplateRequest = new UpdateTemplateRequest(); // UpdateTemplateRequest | \n\n try\n {\n // Update template\n TemplateResource result = apiInstance.UpdateTemplate(templateId, appId, updateTemplateRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateTemplate: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let template_id: &str = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let update_template_request: models::UpdateTemplateRequest = todo!();\n\n match default_api::update_template(&configuration, template_id, app_id, update_template_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_template failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_template failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "template_id", "in": "path", "description": "The template ID in UUID v4 format. See [Templates](/docs/en/templates).", "schema": { "type": "string", "default": "YOUR_TEMPLATE_ID" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track Templates. Maximum 128 characters.", "default": "YOUR_TEMPLATE_NAME" }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "isEmail": { "type": "boolean", "description": "Required to be set `true` for email templates." }, "email_body": { "type": "string", "description": "The body of the email in HTML format. Required for email templates. Supports [Message Personalization](/docs/message-personalization)." }, "isSMS": { "type": "boolean", "description": "Required to be set `true` for SMS templates." }, "dynamic_content": { "type": "object", "description": "Add personalization to your templates programmatically. No need to upload a CSV. See [Dynamic Content](/docs/dynamic-content) for details.", "example": { "campaign_id": { "A": { "title": "Custom Title A", "message": "Custom Message A", "url": "https://www.onesignal.com" }, "B": { "title": "Custom Title B", "message": "Custom Message B", "url": "https://www.onesignal.com/login" } } } } } } } } }, "responses": { "200": { "description": "The updated template record. Same shape as POST /templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResource" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "string", "example": "'message' Notifications must have Any/English language content" } } } }, { "title": "Bad Request (Email)", "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "string", "example": "'message' Email body can not be blank" } } } } ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/templates?app_id={app_id}&limit={limit}&offset={offset}": { "get": { "summary": "View templates", "description": "Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.", "operationId": "view-templates", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | Your OneSignal App ID in UUID v4 format.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// number | Maximum number of templates. Default and max is 50. (optional)\nconst limit: number = 10;\n// number | Pagination offset. (optional)\nconst offset: number = 0;\n// 'push' | 'email' | 'sms' | Filter by delivery channel. (optional)\nconst channel: 'push' | 'email' | 'sms' = \"push\";\n\ntry {\n const response = await apiInstance.viewTemplates(appId, limit, offset, channel);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"viewTemplates failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # Your OneSignal App ID in UUID v4 format. \n limit = 10 # Maximum number of templates. Default and max is 50. (optional) \n offset = 0 # Pagination offset. (optional) \n channel = \"push\" # Filter by delivery channel. (optional) \n\n try:\n # View templates\n api_response = api_instance.view_templates(app_id, limit=limit, offset=offset, channel=channel)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->view_templates: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | Your OneSignal App ID in UUID v4 format.\n$limit = 10; // int | Maximum number of templates. Default and max is 50.\n$offset = 0; // int | Pagination offset.\n$channel = 'push'; // string | Filter by delivery channel.\n\ntry {\n $result = $apiInstance->viewTemplates($app_id, $limit, $offset, $channel);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->viewTemplates: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->viewTemplates: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | Your OneSignal App ID in UUID v4 format.\n limit := int32(10) // int32 | Maximum number of templates. Default and max is 50. (optional) (default to 50)\n offset := int32(0) // int32 | Pagination offset. (optional) (default to 0)\n channel := \"push\" // string | Filter by delivery channel. (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.ViewTemplates(restAuth).AppId(appId).Limit(limit).Offset(offset).Channel(channel).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.ViewTemplates``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `ViewTemplates`: TemplatesListResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.ViewTemplates`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | Your OneSignal App ID in UUID v4 format.\nopts = {\n limit: 10, # Integer | Maximum number of templates. Default and max is 50.\n offset: 0, # Integer | Pagination offset.\n channel: 'push' # String | Filter by delivery channel.\n}\n\nbegin\n # View templates\n result = api_instance.view_templates(app_id, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->view_templates: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | Your OneSignal App ID in UUID v4 format.\n Integer limit = 10; // Integer | Maximum number of templates. Default and max is 50.\n Integer offset = 0; // Integer | Pagination offset.\n String channel = \"push\"; // String | Filter by delivery channel.\n try {\n TemplatesListResponse result = apiInstance.viewTemplates(appId, limit, offset, channel);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#viewTemplates\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class ViewTemplatesExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | Your OneSignal App ID in UUID v4 format.\n var limit = 10; // int? | Maximum number of templates. Default and max is 50. (optional) (default to 50)\n var offset = 0; // int? | Pagination offset. (optional) (default to 0)\n var channel = \"push\"; // string | Filter by delivery channel. (optional) \n\n try\n {\n // View templates\n TemplatesListResponse result = apiInstance.ViewTemplates(appId, limit, offset, channel);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.ViewTemplates: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let limit: Option = None;\n let offset: Option = None;\n let channel: Option<&str> = None;\n\n match default_api::view_templates(&configuration, app_id, limit, offset, channel).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"view_templates failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"view_templates failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "limit", "in": "query", "description": "The maximum number of templates returned per request. The default (if omitted) and maximum is 50 templates per request.", "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "offset", "in": "query", "description": "The pagination or \"starting point\" of the templates to be returned. Setting it to 0 with a limit of 50 will retrieve the first 50 templates. Increasing the offset by 50 will return the next set of templates, and so on.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } }, { "name": "channel", "in": "query", "description": "Filter the fetched templates by the delivery channel. Available options are: `push`, `email`, and `SMS`.", "schema": { "type": "string", "enum": [ "push", "email", "sms" ] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "limit": 50, "offset": 0, "templates": [ { "id": "9e778dd4-6453-40d7-888d-9d9f327b9b66", "name": "OneSignal Push: New Feature Announcement (Template)", "created_at": "2021-07-23T18:02:23.956Z", "updated_at": "2021-07-23T18:02:23.956Z" }, { "id": "806b4356-67af-4d33-8133-75e502f6d3b7", "name": "OneSignal Push: User Action Notification (Template)", "created_at": "2021-07-23T18:02:23.963Z", "updated_at": "2021-07-23T18:02:23.963Z" }, { "id": "172f55b5-df07-49ae-8a8d-67037679487f", "name": "OneSignal Push: Rating (Template)", "created_at": "2021-07-23T18:02:23.984Z", "updated_at": "2021-07-23T18:02:23.984Z" } ], "total_count": 3 } } }, "schema": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50, "default": 0 }, "offset": { "type": "integer", "example": 0, "default": 0 }, "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the template in UUID v4 format." }, "name": { "type": "string", "description": "An internal name you set to help organize and track Templates. Maximum 128 characters." }, "created_at": { "type": "string", "description": "The date and time the template was created in ISO 8601 format." }, "updated_at": { "type": "string", "description": "The date and time the template was last updated in ISO 8601 format." } } } }, "total_count": { "type": "integer", "example": 3, "default": 0 } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Bad Request (Missing App ID)": { "value": { "errors": [ "Request is malformed: Failed to parse app_id from request", "JSON body is None for app_id_location=body request" ] } }, "Bad Request (Invalid Limit)": { "value": { "errors": [ "Invalid limit, must be within 1 to 50" ] } }, "Bad Request (Invalid Channel)": { "value": { "errors": [ "Invalid channel" ] } } }, "schema": { "oneOf": [ { "title": "Bad Request (Missing App ID)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "example": "Request is malformed: Failed to parse app_id from request" } } } }, { "title": "Bad Request (Invalid Limit)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "example": "Invalid limit, must be within 1 to 50" } } } }, { "title": "Bad Request (Invalid Channel)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "example": "Invalid channel" } } } } ] } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/templates": { "post": { "summary": "Create template", "description": "Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.", "operationId": "create-template", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// CreateTemplateRequest\nconst createTemplateRequest: Onesignal.CreateTemplateRequest = {\n app_id: \"app_id_example\",\n name: \"name_example\",\n contents: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n headings: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n subtitle: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n is_email: true,\n email_subject: \"email_subject_example\",\n email_body: \"email_body_example\",\n email_bcc: [\n \"email_bcc_example\",\n ],\n is_sms: true,\n dynamic_content: \"dynamic_content_example\",\n };\n\ntry {\n const response = await apiInstance.createTemplate(createTemplateRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createTemplate failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n create_template_request = CreateTemplateRequest(\n app_id=\"app_id_example\",\n name=\"name_example\",\n contents=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n headings=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n subtitle=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n is_email=True,\n email_subject=\"email_subject_example\",\n email_body=\"email_body_example\",\n email_bcc=[\n \"email_bcc_example\",\n ],\n is_sms=True,\n dynamic_content=\"dynamic_content_example\",\n ) \n\n try:\n # Create template\n api_response = api_instance.create_template(create_template_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_template: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$create_template_request = new \\onesignal\\client\\model\\CreateTemplateRequest(); // \\onesignal\\client\\model\\CreateTemplateRequest\n\ntry {\n $result = $apiInstance->createTemplate($create_template_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createTemplate: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createTemplate: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n createTemplateRequest := *onesignal.NewCreateTemplateRequest(\"AppId_example\", \"Name_example\", *onesignal.NewLanguageStringMap()) // CreateTemplateRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateTemplate(restAuth).CreateTemplateRequest(createTemplateRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateTemplate``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateTemplate`: TemplateResource\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateTemplate`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\ncreate_template_request = OneSignal::CreateTemplateRequest.new({app_id: 'app_id_example', name: 'name_example', contents: OneSignal::LanguageStringMap.new}) # CreateTemplateRequest | \n\nbegin\n # Create template\n result = api_instance.create_template(create_template_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_template: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n CreateTemplateRequest createTemplateRequest = new CreateTemplateRequest(); // CreateTemplateRequest | \n try {\n TemplateResource result = apiInstance.createTemplate(createTemplateRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createTemplate\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateTemplateExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var createTemplateRequest = new CreateTemplateRequest(); // CreateTemplateRequest | \n\n try\n {\n // Create template\n TemplateResource result = apiInstance.CreateTemplate(createTemplateRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateTemplate: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let create_template_request: models::CreateTemplateRequest = todo!();\n\n match default_api::create_template(&configuration, create_template_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_template failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_template failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json; charset=utf-8" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "name" ], "properties": { "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "default": "YOUR_APP_ID" }, "name": { "type": "string", "description": "An internal name you set to help organize and track Templates. Maximum 128 characters.", "default": "YOUR_TEMPLATE_NAME" }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Required for push and SMS templates. Supports [Message Personalization](/docs/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "isEmail": { "type": "boolean", "description": "Required to be set `true` for email templates." }, "email_subject": { "type": "string", "description": "Required for email templates. The subject of the email. Supports [Message Personalization](/docs/message-personalization)." }, "email_body": { "type": "string", "description": "The body of the email in HTML format. Required for email templates. Supports [Message Personalization](/docs/message-personalization)." }, "isSMS": { "type": "boolean", "description": "Required to be set `true` for SMS templates." }, "dynamic_content": { "type": "object", "description": "Add personalization to your templates programmatically. No need to upload a CSV. See [Dynamic Content](/docs/dynamic-content) for details.", "example": { "campaign_id": { "A": { "title": "Custom Title A", "message": "Custom Message A", "url": "https://www.onesignal.com" }, "B": { "title": "Custom Title B", "message": "Custom Message B", "url": "https://www.onesignal.com/login" } } } } } } } } }, "responses": { "200": { "description": "The created template record. `content` reflects the configuration as stored — fields not relevant to the chosen channel are returned as null.", "content": { "application/json": { "examples": { "Result": { "value": { "id": "b17ebe45-ae35-4dce-11f8-8c3b3894a432", "name": "new template created via the API", "created_at": "2023-08-02T18:09:02Z", "updated_at": "2023-08-02T18:09:02Z", "content": { "isAndroid": true, "isIos": true, "isMacOSX": true, "isAdm": true, "isAlexa": null, "isWP": true, "isWP_WNS": true, "isChrome": true, "isChromeWeb": true, "isSafari": true, "isFirefox": true, "isEdge": true, "headings": { "en": "hello from the api!" }, "subtitle": null, "contents": { "en": "why hello there!" }, "global_image": null, "url": "https://example.com", "isEmail": null, "email_body": null, "email_subject": null, "email_preheader": null, "isSMS": null, "sms_from": null, "sms_media_urls": null, "email_reply_to_address": null, "disable_email_click_tracking": null } } } }, "schema": { "$ref": "#/components/schemas/TemplateResource" } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Bad Request (Email)": { "value": { "success": false, "errors": [ "'message' Email body can not be blank" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "422": { "description": "422", "content": { "text/plain": { "examples": { "Result": { "value": "\n\nThe change you wanted was rejected (422)" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}": { "post": { "summary": "Unsubscribe email (with token)", "description": "Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.", "operationId": "unsubscribe-with-token", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\nconst notificationId: string = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n// string | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\nconst token: string = \"YOUR_TOKEN_ID\";\n\ntry {\n const response = await apiInstance.unsubscribeEmailWithToken(appId, notificationId, token);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"unsubscribeEmailWithToken failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n notification_id = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" # The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report. \n token = \"YOUR_TOKEN_ID\" # The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email. \n\n try:\n # Unsubscribe with token\n api_response = api_instance.unsubscribe_email_with_token(app_id, notification_id, token)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->unsubscribe_email_with_token: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\n$token = 'YOUR_TOKEN_ID'; // string | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\n\ntry {\n $result = $apiInstance->unsubscribeEmailWithToken($app_id, $notification_id, $token);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->unsubscribeEmailWithToken: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->unsubscribeEmailWithToken: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n notificationId := \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" // string | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\n token := \"YOUR_TOKEN_ID\" // string | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.UnsubscribeEmailWithToken(restAuth, appId, notificationId).Token(token).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UnsubscribeEmailWithToken``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UnsubscribeEmailWithToken`: GenericSuccessBoolResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UnsubscribeEmailWithToken`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\nnotification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\ntoken = 'YOUR_TOKEN_ID' # String | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\n\nbegin\n # Unsubscribe with token\n result = api_instance.unsubscribe_email_with_token(app_id, notification_id, token)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->unsubscribe_email_with_token: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n String notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // String | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\n String token = \"YOUR_TOKEN_ID\"; // String | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\n try {\n GenericSuccessBoolResponse result = apiInstance.unsubscribeEmailWithToken(appId, notificationId, token);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#unsubscribeEmailWithToken\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UnsubscribeEmailWithTokenExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // string | The id of the message found in the creation notification POST response, View Notifications GET response, or URL within the Message Report.\n var token = \"YOUR_TOKEN_ID\"; // string | The unsubscribe token that is generated via liquid syntax in {{subscription.unsubscribe_token}} when personalizing an email.\n\n try\n {\n // Unsubscribe with token\n GenericSuccessBoolResponse result = apiInstance.UnsubscribeEmailWithToken(appId, notificationId, token);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UnsubscribeEmailWithToken: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let notification_id: &str = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n let token: &str = \"YOUR_TOKEN_ID\";\n\n match default_api::unsubscribe_email_with_token(&configuration, app_id, notification_id, token).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"unsubscribe_email_with_token failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"unsubscribe_email_with_token failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "token", "in": "query", "description": "The unsubscribe token that is generated via liquid syntax `{{subscription.unsubscribe_token}}` when personalizing an email. See [Create a Custom Unsubscribe Page](/docs/create-custom-unsubscribe-page) for setup details.", "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "notification_id", "in": "path", "description": "The \"id\" of the email message. Can be passed into the request from the email received by the user with liquid syntax `{{message.id}}`. See [Create a Custom Unsubscribe Page](/docs/create-custom-unsubscribe-page) for setup details.", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "202", "content": { "application/json": { "examples": { "Result": { "value": { "success": "true" } } }, "schema": { "type": "object", "properties": { "success": { "type": "string", "example": "true" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Details about the error." ] } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Forbidden" ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "subscription-0", "title": "Subscription not found" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "code": "Rate Limit Exceeded", "title": "Example error title", "meta": {} } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false, "security": [] } }, "/notifications?c=email": { "post": { "summary": "Email", "description": "Send a message using the email channel.", "operationId": "email", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\nimport { randomUUID } from 'node:crypto';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\nconst notification = new Onesignal.Notification();\nnotification.app_id = 'YOUR_APP_ID';\nnotification.email_subject = 'Welcome to OneSignal';\nnotification.email_body = '

Hello!

Thanks for signing up.

';\n// Target by External ID: alias keys must match the API (external_id, not externalId).\nnotification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };\nnotification.target_channel = 'email';\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. `randomUUID` is imported from `node:crypto`\n// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.\nnotification.idempotency_key = randomUUID();\n\ntry {\n const response = await apiInstance.createNotification(notification);\n if (!response.id) {\n console.warn(\"Notification was not sent:\", response.errors);\n } else if (response.errors) {\n console.log(\"Notification created:\", response.id, \"(partial failures:\", response.errors, \")\");\n } else {\n console.log(\"Notification created:\", response.id);\n }\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createNotification failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import uuid\nimport onesignal\nfrom onesignal.api import default_api\nfrom onesignal.model.notification import Notification\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\nwith onesignal.ApiClient(configuration) as api_client:\n api_instance = default_api.DefaultApi(api_client)\n notification = Notification(\n app_id='YOUR_APP_ID',\n email_subject='Welcome to OneSignal',\n email_body='

Hello!

Thanks for signing up.

',\n include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},\n target_channel='email',\n # Idempotency key: a client-generated UUID that lets you safely retry on network\n # failure. If two requests arrive with the same key inside the 30-day window, only\n # the first is sent and the second returns the original response. Use uuid.uuid4()\n # or a similar source of randomness — DO NOT reuse keys across logically distinct\n # sends.\n idempotency_key=str(uuid.uuid4()),\n )\n try:\n api_response = api_instance.create_notification(notification)\n # `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or\n # a dict keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped. Access via `.get('errors')` rather than\n # attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises\n # `ApiAttributeError` for optional fields that the server omitted, so plain\n # `api_response.errors` would crash on the pure-success path.\n response_id = api_response.get('id')\n response_errors = api_response.get('errors')\n if not response_id:\n print('Notification was not sent:', response_errors)\n elif response_errors:\n print('Notification created:', response_id, '(partial failures:', response_errors, ')')\n else:\n print('Notification created:', response_id)\n except onesignal.ApiException as e:\n print('Exception when calling DefaultApi->create_notification: %s\\n' % e)\n print('Status Code: %s' % e.status)\n # `e.error_messages` flattens any error-envelope shape to a list[str];\n # the raw body remains on `e.body`.\n print('Error Messages: %s' % e.error_messages)\n print('Response Body: %s' % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n new GuzzleHttp\\Client(),\n $config\n);\n\n$notification = new onesignal\\client\\Model\\Notification();\n$notification->setAppId('YOUR_APP_ID');\n$notification->setEmailSubject('Welcome to OneSignal');\n$notification->setEmailBody('

Hello!

Thanks for signing up.

');\n$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);\n$notification->setTargetChannel('email');\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. Use a strong source of randomness — DO NOT\n// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here\n// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with\n// no extra install; projects that already pull in ramsey/uuid can swap in\n// `\\Ramsey\\Uuid\\Uuid::uuid4()->toString()` instead.\n$idempotencyKeyBytes = random_bytes(16);\n$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);\n$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);\n$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));\n$notification->setIdempotencyKey($idempotencyKey);\n\ntry {\n $result = $apiInstance->createNotification($notification);\n // `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty\n // string or null) means no notification was created (e.g. all targets were\n // unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`\n // in the no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (!$result->getId()) {\n echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;\n } elseif ($result->getErrors()) {\n echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;\n } else {\n echo 'Notification created: ', $result->getId(), PHP_EOL;\n }\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/google/uuid\"\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\")\n\n notification := onesignal.NewNotification(\"YOUR_APP_ID\")\n notification.SetEmailSubject(\"Welcome to OneSignal\")\n notification.SetEmailBody(\"

Hello!

Thanks for signing up.

\")\n notification.SetIncludeAliases(map[string][]string{\"external_id\": {\"YOUR_USER_EXTERNAL_ID\"}})\n notification.SetTargetChannel(\"email\")\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `github.com/google/uuid` module\n // is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`\n // after importing it) before building. DO NOT reuse keys across logically distinct sends.\n notification.SetIdempotencyKey(uuid.NewString())\n\n resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateNotification``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n return\n }\n // `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in\n // the no-subscribers case, or a map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if resp.GetId() == \"\" {\n fmt.Fprintf(os.Stderr, \"Notification was not sent: %v\\n\", resp.GetErrors())\n } else if errors := resp.GetErrors(); errors != nil {\n fmt.Fprintf(os.Stdout, \"Notification created: %s (partial failures: %v)\\n\", resp.GetId(), errors)\n } else {\n fmt.Fprintf(os.Stdout, \"Notification created: %s\\n\", resp.GetId())\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nrequire 'securerandom'\n\nnotification = OneSignal::Notification.new\nnotification.app_id = 'YOUR_APP_ID'\nnotification.email_subject = 'Welcome to OneSignal'\nnotification.email_body = '

Hello!

Thanks for signing up.

'\nnotification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }\nnotification.target_channel = 'email'\n# Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n# If two requests arrive with the same key inside the 30-day window, only the first is sent\n# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys\n# across logically distinct sends.\nnotification.idempotency_key = SecureRandom.uuid\n\nbegin\n # Create notification\n result = api_instance.create_notification(notification)\n # `result.id` discriminates the two HTTP 200 shapes. An empty string means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `result.errors` is polymorphic: an `Array` in the no-subscribers case, or\n # a Hash keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped.\n if result.id.to_s.empty?\n puts \"Notification was not sent: #{result.errors}\"\n elsif result.errors\n puts \"Notification created: #{result.id} (partial failures: #{result.errors})\"\n else\n puts \"Notification created: #{result.id}\"\n end\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_notification: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport java.util.Arrays;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.UUID;\n\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n Notification notification = new Notification();\n notification.setAppId(\"YOUR_APP_ID\");\n notification.setEmailSubject(\"Welcome to OneSignal\");\n notification.setEmailBody(\"

Hello!

Thanks for signing up.

\");\n Map> aliases = new HashMap<>();\n aliases.put(\"external_id\", Arrays.asList(\"YOUR_USER_EXTERNAL_ID\"));\n notification.setIncludeAliases(aliases);\n notification.setTargetChannel(Notification.TargetChannelEnum.EMAIL);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. Use UUID.randomUUID() — DO NOT\n // reuse keys across logically distinct sends.\n notification.setIdempotencyKey(UUID.randomUUID().toString());\n\n try {\n CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);\n // `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `result.getErrors()` is polymorphic (declared as `Object`): a `List` in the\n // no-subscribers case, or a Map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (result.getId() == null || result.getId().isEmpty()) {\n System.out.println(\"Notification was not sent: \" + result.getErrors());\n } else if (result.getErrors() != null) {\n System.out.println(\"Notification created: \" + result.getId() + \" (partial failures: \" + result.getErrors() + \")\");\n } else {\n System.out.println(\"Notification created: \" + result.getId());\n }\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createNotification\");\n System.err.println(\"Status code: \" + e.getCode());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateNotificationExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n\n var notification = new Notification\n {\n AppId = \"YOUR_APP_ID\",\n EmailSubject = \"Welcome to OneSignal\",\n EmailBody = \"

Hello!

Thanks for signing up.

\",\n IncludeAliases = new Dictionary>\n {\n { \"external_id\", new List { \"YOUR_USER_EXTERNAL_ID\" } }\n },\n TargetChannel = Notification.TargetChannelEnum.Email,\n // Idempotency key: a client-generated UUID that lets you safely retry on\n // network failure. If two requests arrive with the same key inside the\n // 30-day window, only the first is sent and the second returns the original\n // response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct\n // sends.\n IdempotencyKey = Guid.NewGuid().ToString()\n };\n\n try\n {\n CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);\n // `result.Id` discriminates the two HTTP 200 shapes. An empty string means\n // no notification was created (e.g. all targets were unreachable / not\n // subscribed). `result.Errors` is polymorphic: a `List` in the\n // no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)\n // when the notification WAS created but some recipients were skipped.\n if (string.IsNullOrEmpty(result.Id))\n {\n Debug.WriteLine(\"Notification was not sent: \" + result.Errors);\n }\n else if (result.Errors != null)\n {\n Debug.WriteLine(\"Notification created: \" + result.Id + \" (partial failures: \" + result.Errors + \")\");\n }\n else\n {\n Debug.WriteLine(\"Notification created: \" + result.Id);\n }\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateNotification: \" + e.Message);\n Debug.Print(\"Status Code: \" + e.ErrorCode);\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\nuse onesignal_rust_api::models::notification::TargetChannelType;\nuse onesignal_rust_api::models::Notification;\nuse uuid::Uuid;\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n let mut notification = Notification::new(\"YOUR_APP_ID\".to_string());\n notification.email_subject = Some(\"Welcome to OneSignal\".to_string());\n notification.email_body = Some(\"

Hello!

Thanks for signing up.

\".to_string());\n let mut aliases = std::collections::HashMap::new();\n aliases.insert(\n \"external_id\".to_string(),\n vec![\"YOUR_USER_EXTERNAL_ID\".to_string()],\n );\n notification.include_aliases = Some(aliases);\n notification.target_channel = Some(TargetChannelType::Email);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `uuid` crate must be declared\n // in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream\n // code) — add `uuid = { version = \"1\", features = [\"v4\"] }` to your `[dependencies]`.\n // DO NOT reuse keys across logically distinct sends.\n notification.idempotency_key = Some(Uuid::new_v4().to_string());\n\n match default_api::create_notification(&configuration, notification).await {\n Ok(resp) => {\n // `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`\n // means no notification was created (e.g. all targets were unreachable / not\n // subscribed). `resp.errors` is polymorphic (typed as `Option`):\n // a `Vec` in the no-subscribers case, or an object keyed by\n // recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,\n // `invalid_aliases`, ...) when the notification WAS created but some recipients\n // were skipped.\n match resp.id.as_deref() {\n Some(\"\") | None => eprintln!(\"Notification was not sent: {:?}\", resp.errors),\n Some(id) if resp.errors.is_some() => {\n println!(\"Notification created: {} (partial failures: {:?})\", id, resp.errors)\n }\n Some(id) => println!(\"Notification created: {}\", id),\n }\n }\n Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {\n eprintln!(\"create_notification failed: HTTP {}\", content.status);\n eprintln!(\"Response Body: {}\", content.content);\n }\n Err(e) => eprintln!(\"create_notification failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "email_subject", "email_body" ], "properties": { "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "default": "YOUR_APP_ID" }, "include_aliases": { "type": "object", "description": "Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).", "format": "json", "properties": { "external_id": { "description": "An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).", "type": "array", "items": { "type": "string" } } } }, "target_channel": { "type": "string", "description": "The targeted delivery channel. Required when using `include_aliases`. Accepts `push`, `email`, or `sms`.", "enum": [ "push", "email", "sms" ], "default": "email" }, "include_subscription_ids": { "type": "array", "description": "Target users' specific [subscriptions](/docs/subscriptions) by ID. Include up to 20,000 `subscription_id` per API call. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "email_to": { "type": "array", "description": "Send email to specific users by their email address. Include up to 20,000 email addresses per API call. If the email address does not exist within the OneSignal App, then a new email Subscription will be created. Can only be used when sending [Email](/reference/email). Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "included_segments": { "type": "array", "description": "Target predefined [Segments](/docs/segmentation). Users that are in multiple segments will only be sent the message once. Can be combined with `excluded_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "excluded_segments": { "type": "array", "description": "Exclude users in predefined [Segments](/docs/segmentation). Overrides membership in any segment specified in the `included_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "filters": { "type": "array", "description": "Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).", "items": { "oneOf": [ { "title": "Filter", "description": "Required. The fitler object.", "required": [ "field", "relation" ], "type": "object", "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "enum": [ "tag", "last_session", "first_session", "session_count", "session_time", "language", "app_version", "location", "country" ] }, "relation": { "type": "string", "description": "Used with most filters. See details on the specific filter.", "enum": [ "=", "!=", ">", "<", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with." } } }, { "title": "Operator", "type": "object", "properties": { "operator": { "type": "string", "description": "Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.", "enum": [ "AND", "OR" ], "default": "AND" } } } ] }, "minItems": 1, "maxItems": 200 }, "email_subject": { "type": "string", "description": "The subject of the email. Supports [Message Personalization](/docs/message-personalization).", "default": "This is your email subject." }, "email_preheader": { "type": "string", "description": "Preview text displayed after the email subject." }, "email_body": { "type": "string", "description": "The body of the email in HTML format. Required if `template_id` is not set. Supports [Message Personalization](/docs/message-personalization)." }, "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters." }, "template_id": { "type": "string", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates)." }, "custom_data": { "type": "object", "description": "Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email)." }, "email_from_name": { "type": "string", "description": "The name the email is sent from. Defaults to the 'Sender Name' in the Email Settings of your OneSignal Dashboard. See [Email setup](/docs/email-setup) and [Senders](/docs/senders).", "default": "Your Company" }, "email_from_address": { "type": "string", "description": "The full email address shown in the 'From' field of the email (e.g., `promotions@news.example.com`). This is what recipients see as the sender. If not specified, OneSignal uses the default 'Sender Email' set in your Dashboard's Email Settings. See [Senders](/docs/senders)." }, "email_sender_domain": { "type": "string", "description": "The authenticated sending domain used for email delivery. This domain must be verified in your DNS records and will determine which domain handles the mail transfer. It may not always exactly match the domain in the `email_from_address` (e.g., `email_from_address = news@example.com` while `email_sender_domain = mail.example.com`), but the root domain must align for DMARC compliance. If not specified, OneSignal uses the default sender email's domain configured in your Dashboard. See [Email setup](/docs/email-setup) and [Senders](/docs/senders)." }, "email_reply_to_address": { "type": "string", "description": "The email address users reply to. Defaults to the 'Reply-To' address in the Email Settings of your OneSignal Dashboard. See [Email setup](/docs/email-setup)." }, "email_bcc": { "type": "array", "description": "BCC recipients for the email. Maximum 5 addresses. Only supported when the email service provider is OneSignal Email. For every email sent, an additional billable email is sent to each BCC address. See [BCC Emails](/docs/en/email-bcc).", "items": { "type": "string" } }, "include_unsubscribed": { "type": "boolean", "description": "Used for important account-related, non-marking emails. If set to `true` it will send the email to unsubscribed email addresses. Defaults to `false`. See [Email unsubscribe links & headers](/docs/unsubscribe-links-email-subscriptions)." }, "disable_email_click_tracking": { "type": "boolean", "description": "If set to `true`, the URLs sent within the email will not include link tracking and will be the same as originally set; otherwise, all the URLs in the email will be tracked. See [Email unsubscribe links & headers](/docs/unsubscribe-links-email-subscriptions). Defaults to `false`." }, "send_after": { "type": "string", "description": "Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`" }, "delayed_option": { "type": "string", "description": "Controls how messages are delivered on a per-user basis: `'timezone'` — Sends at the same local time across time zones. `'last-active'` — Delivers based on each user’s most recent session. Not compatible with [Push Throttling](/docs/throttling). If enabled, set `throttle_rate_per_minute` to `0`." }, "delivery_time_of_day": { "type": "string", "description": "Use with `delayed_option: 'timezone'` to set a consistent local delivery time. Accepted formats: `'9:00AM'` (12-hour), `'21:45'` (24-hour), `'09:45:30'` (HH:mm:ss)." }, "idempotency_key": { "type": "string", "description": "A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Message Sent", "type": "object", "properties": { "id": { "type": "string", "description": "Notification ID in UUID v4 format. If `id` is an empty string, then the message was not sent.", "format": "uuid" }, "external_id": { "type": [ "string", "null" ], "description": "The `idempotency_key` parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see [Idempotent message requests](/reference/idempotent-notification-requests)." }, "errors": { "type": "object", "description": "Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.", "properties": { "invalid_email_tokens": { "type": "array", "items": { "type": "string", "description": "The listed email addresses used in the `email_to` parameter that were unsubscribed from the email message channel before the message was sent." } }, "invalid_aliases": { "type": "object", "description": "The alias label that was used in the `include_aliases` parameter.", "properties": { "external_id": { "type": "array", "items": { "type": "string", "description": "The alias IDs associated with the unsubscribed Subscriptions. The listed aliases were unsubscribed before the message was sent. In this example, `user_id_1` has two unsubscribed Subscriptions while `user_id_2` has one unsubscribed Subscription.", "example": "[\"user_id_1\", \"user_id_1\", \"user_id_2\"]" } }, "onesignal_id": { "type": "array", "items": { "type": "string", "description": "The OneSignal ID associated with the unsubscribed Subscription. The listed OneSignal IDs were unsubscribed before the message was sent. In this example, the user with OneSignal ID `1589641e-bed1-4325-bce4-d2234e578884` has three unsubscribed Subscriptions.", "example": "[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]" } } } }, "invalid_player_ids": { "type": "array", "items": { "type": "string", "description": "The Subscription ID exists in the OneSignal app but is unsubscribed from the message channel. If the Subscription ID did not exist, it will not be reported." } } } }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).", "required": [ "id" ] }, { "title": "Message Not Sent", "type": "object", "properties": { "id": { "type": "string", "description": "If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.", "example": "", "enum": [ "" ] }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Reasons the message was not dispatched. The most common value is `\"All included players are not subscribed\"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.", "example": [ "All included players are not subscribed" ] }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.", "required": [ "id", "errors" ] } ], "description": "Two variants are possible with HTTP 200, distinguished by the `id` field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect `errors` when `id` is empty." } } }, "headers": { "Idempotent-Replayed": { "description": "Present and set to `true` when this response is a replay of a previous successful request that used the same `idempotency_key`. Absent on fresh executions. Use this to distinguish \"new send\" from \"deduplicated retry\" without inspecting the body.", "schema": { "type": "boolean", "enum": [ true ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The reason for the bad request.", "items": { "properties": { "Message Notifications must have English language content": { "type": "string", "description": "Make sure the request or template has English language ('en')content. This is required but can be any language desired." }, "Incorrect subscription_id format in include_subscription_ids (not a valid UUID):": { "type": "string", "description": "The provided `subscription_id` is not a valid UUID." }, "Platforms You may only send to one delivery channel at a time. Make sure you are only including one of push platforms, Email, or SMS.": { "type": "string", "description": "You are attempting to send a message to a Subscription for a different channel. Make sure you are only targeting one channel at a time." } } } } } } } } }, "403": { "description": "Forbidden. The Authorization key cannot send email for this app, or the request targets a feature the app's plan does not enable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "This API is not available for applications on your plan." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/notifications?c=push": { "post": { "summary": "Push notification", "description": "Send a message using the push notification channel.", "operationId": "push-notification", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\nimport { randomUUID } from 'node:crypto';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\nconst notification = new Onesignal.Notification();\nnotification.app_id = 'YOUR_APP_ID';\nnotification.contents = { en: 'Hello from OneSignal!' };\nnotification.headings = { en: 'Push Notification' };\n// Target by External ID: alias keys must match the API (external_id, not externalId).\nnotification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };\nnotification.target_channel = 'push';\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. `randomUUID` is imported from `node:crypto`\n// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.\nnotification.idempotency_key = randomUUID();\n\ntry {\n const response = await apiInstance.createNotification(notification);\n // `response.id` discriminates the two HTTP 200 shapes. A falsy value (empty string,\n // null, or undefined) means no notification was created (e.g. all targets were\n // unreachable / not subscribed). `response.errors` is polymorphic: a `string[]` in the\n // no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, …) when the\n // notification WAS created but some recipients were skipped.\n if (!response.id) {\n console.warn(\"Notification was not sent:\", response.errors);\n } else if (response.errors) {\n console.log(\"Notification created:\", response.id, \"(partial failures:\", response.errors, \")\");\n } else {\n console.log(\"Notification created:\", response.id);\n }\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createNotification failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import uuid\nimport onesignal\nfrom onesignal.api import default_api\nfrom onesignal.model.language_string_map import LanguageStringMap\nfrom onesignal.model.notification import Notification\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\nwith onesignal.ApiClient(configuration) as api_client:\n api_instance = default_api.DefaultApi(api_client)\n notification = Notification(\n app_id='YOUR_APP_ID',\n contents=LanguageStringMap(en='Hello from OneSignal!'),\n include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},\n target_channel='push',\n # Idempotency key: a client-generated UUID that lets you safely retry on network\n # failure. If two requests arrive with the same key inside the 30-day window, only\n # the first is sent and the second returns the original response. Use uuid.uuid4()\n # or a similar source of randomness — DO NOT reuse keys across logically distinct\n # sends.\n idempotency_key=str(uuid.uuid4()),\n )\n try:\n api_response = api_instance.create_notification(notification)\n # `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or\n # a dict keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped. Access via `.get('errors')` rather than\n # attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises\n # `ApiAttributeError` for optional fields that the server omitted, so plain\n # `api_response.errors` would crash on the pure-success path.\n response_id = api_response.get('id')\n response_errors = api_response.get('errors')\n if not response_id:\n print('Notification was not sent:', response_errors)\n elif response_errors:\n print('Notification created:', response_id, '(partial failures:', response_errors, ')')\n else:\n print('Notification created:', response_id)\n except onesignal.ApiException as e:\n print('Exception when calling DefaultApi->create_notification: %s\\n' % e)\n print('Status Code: %s' % e.status)\n # `e.error_messages` flattens any error-envelope shape to a list[str];\n # the raw body remains on `e.body`.\n print('Error Messages: %s' % e.error_messages)\n print('Response Body: %s' % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n new GuzzleHttp\\Client(),\n $config\n);\n\n$notification = new onesignal\\client\\Model\\Notification();\n$notification->setAppId('YOUR_APP_ID');\n$contents = new onesignal\\client\\Model\\LanguageStringMap();\n$contents->setEn('Hello from OneSignal!');\n$notification->setContents($contents);\n$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);\n$notification->setTargetChannel('push');\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. Use a strong source of randomness — DO NOT\n// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here\n// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with\n// no extra install; projects that already pull in ramsey/uuid can swap in\n// `\\Ramsey\\Uuid\\Uuid::uuid4()->toString()` instead.\n$idempotencyKeyBytes = random_bytes(16);\n$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);\n$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);\n$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));\n$notification->setIdempotencyKey($idempotencyKey);\n\ntry {\n $result = $apiInstance->createNotification($notification);\n // `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty\n // string or null) means no notification was created (e.g. all targets were\n // unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`\n // in the no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (!$result->getId()) {\n echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;\n } elseif ($result->getErrors()) {\n echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;\n } else {\n echo 'Notification created: ', $result->getId(), PHP_EOL;\n }\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/google/uuid\"\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\")\n\n notification := onesignal.NewNotification(\"YOUR_APP_ID\")\n contents := onesignal.NewLanguageStringMap()\n contents.SetEn(\"Hello from OneSignal!\")\n notification.SetContents(*contents)\n notification.SetIncludeAliases(map[string][]string{\"external_id\": {\"YOUR_USER_EXTERNAL_ID\"}})\n notification.SetTargetChannel(\"push\")\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `github.com/google/uuid` module\n // is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`\n // after importing it) before building. DO NOT reuse keys across logically distinct sends.\n notification.SetIdempotencyKey(uuid.NewString())\n\n resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateNotification``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n return\n }\n // `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in\n // the no-subscribers case, or a map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if resp.GetId() == \"\" {\n fmt.Fprintf(os.Stderr, \"Notification was not sent: %v\\n\", resp.GetErrors())\n } else if errors := resp.GetErrors(); errors != nil {\n fmt.Fprintf(os.Stdout, \"Notification created: %s (partial failures: %v)\\n\", resp.GetId(), errors)\n } else {\n fmt.Fprintf(os.Stdout, \"Notification created: %s\\n\", resp.GetId())\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nrequire 'securerandom'\n\nnotification = OneSignal::Notification.new\nnotification.app_id = 'YOUR_APP_ID'\nnotification.contents = OneSignal::LanguageStringMap.new({ en: 'Hello from OneSignal!' })\nnotification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }\nnotification.target_channel = 'push'\n# Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n# If two requests arrive with the same key inside the 30-day window, only the first is sent\n# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys\n# across logically distinct sends.\nnotification.idempotency_key = SecureRandom.uuid\n\nbegin\n # Create notification\n result = api_instance.create_notification(notification)\n # `result.id` discriminates the two HTTP 200 shapes. An empty string means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `result.errors` is polymorphic: an `Array` in the no-subscribers case, or\n # a Hash keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped.\n if result.id.to_s.empty?\n puts \"Notification was not sent: #{result.errors}\"\n elsif result.errors\n puts \"Notification created: #{result.id} (partial failures: #{result.errors})\"\n else\n puts \"Notification created: #{result.id}\"\n end\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_notification: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport java.util.Arrays;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.UUID;\n\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n Notification notification = new Notification();\n notification.setAppId(\"YOUR_APP_ID\");\n LanguageStringMap contents = new LanguageStringMap();\n contents.setEn(\"Hello from OneSignal!\");\n notification.setContents(contents);\n Map> aliases = new HashMap<>();\n aliases.put(\"external_id\", Arrays.asList(\"YOUR_USER_EXTERNAL_ID\"));\n notification.setIncludeAliases(aliases);\n notification.setTargetChannel(Notification.TargetChannelEnum.PUSH);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. Use UUID.randomUUID() — DO NOT\n // reuse keys across logically distinct sends.\n notification.setIdempotencyKey(UUID.randomUUID().toString());\n\n try {\n CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);\n // `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `result.getErrors()` is polymorphic (declared as `Object`): a `List` in the\n // no-subscribers case, or a Map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (result.getId() == null || result.getId().isEmpty()) {\n System.out.println(\"Notification was not sent: \" + result.getErrors());\n } else if (result.getErrors() != null) {\n System.out.println(\"Notification created: \" + result.getId() + \" (partial failures: \" + result.getErrors() + \")\");\n } else {\n System.out.println(\"Notification created: \" + result.getId());\n }\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createNotification\");\n System.err.println(\"Status code: \" + e.getCode());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateNotificationExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n\n var notification = new Notification\n {\n AppId = \"YOUR_APP_ID\",\n Contents = new LanguageStringMap(en: \"Hello from OneSignal!\"),\n IncludeAliases = new Dictionary>\n {\n { \"external_id\", new List { \"YOUR_USER_EXTERNAL_ID\" } }\n },\n TargetChannel = Notification.TargetChannelEnum.Push,\n // Idempotency key: a client-generated UUID that lets you safely retry on\n // network failure. If two requests arrive with the same key inside the\n // 30-day window, only the first is sent and the second returns the original\n // response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct\n // sends.\n IdempotencyKey = Guid.NewGuid().ToString()\n };\n\n try\n {\n CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);\n // `result.Id` discriminates the two HTTP 200 shapes. An empty string means\n // no notification was created (e.g. all targets were unreachable / not\n // subscribed). `result.Errors` is polymorphic: a `List` in the\n // no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)\n // when the notification WAS created but some recipients were skipped.\n if (string.IsNullOrEmpty(result.Id))\n {\n Debug.WriteLine(\"Notification was not sent: \" + result.Errors);\n }\n else if (result.Errors != null)\n {\n Debug.WriteLine(\"Notification created: \" + result.Id + \" (partial failures: \" + result.Errors + \")\");\n }\n else\n {\n Debug.WriteLine(\"Notification created: \" + result.Id);\n }\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateNotification: \" + e.Message);\n Debug.Print(\"Status Code: \" + e.ErrorCode);\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\nuse onesignal_rust_api::models::notification::TargetChannelType;\nuse onesignal_rust_api::models::{LanguageStringMap, Notification};\nuse uuid::Uuid;\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n let mut notification = Notification::new(\"YOUR_APP_ID\".to_string());\n notification.contents = Some(Box::new(LanguageStringMap {\n en: Some(\"Hello from OneSignal!\".to_string()),\n ..Default::default()\n }));\n let mut aliases = std::collections::HashMap::new();\n aliases.insert(\n \"external_id\".to_string(),\n vec![\"YOUR_USER_EXTERNAL_ID\".to_string()],\n );\n notification.include_aliases = Some(aliases);\n notification.target_channel = Some(TargetChannelType::Push);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `uuid` crate must be declared\n // in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream\n // code) — add `uuid = { version = \"1\", features = [\"v4\"] }` to your `[dependencies]`.\n // DO NOT reuse keys across logically distinct sends.\n notification.idempotency_key = Some(Uuid::new_v4().to_string());\n\n match default_api::create_notification(&configuration, notification).await {\n Ok(resp) => {\n // `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`\n // means no notification was created (e.g. all targets were unreachable / not\n // subscribed). `resp.errors` is polymorphic (typed as `Option`):\n // a `Vec` in the no-subscribers case, or an object keyed by\n // recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,\n // `invalid_aliases`, ...) when the notification WAS created but some recipients\n // were skipped.\n match resp.id.as_deref() {\n Some(\"\") | None => eprintln!(\"Notification was not sent: {:?}\", resp.errors),\n Some(id) if resp.errors.is_some() => {\n println!(\"Notification created: {} (partial failures: {:?})\", id, resp.errors)\n }\n Some(id) => println!(\"Notification created: {}\", id),\n }\n }\n Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {\n eprintln!(\"create_notification failed: HTTP {}\", content.status);\n eprintln!(\"Response Body: {}\", content.content);\n }\n Err(e) => eprintln!(\"create_notification failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "contents" ], "properties": { "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "default": "YOUR_APP_ID" }, "include_aliases": { "type": "object", "description": "Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).", "format": "json", "properties": { "external_id": { "description": "An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).", "type": "array", "items": { "type": "string" } } } }, "target_channel": { "type": "string", "description": "The targeted delivery channel. Required when using `include_aliases`. Accepts `push`, `email`, or `sms`.", "enum": [ "push", "email", "sms" ], "default": "push" }, "include_subscription_ids": { "type": "array", "description": "Target users' specific [subscriptions](/docs/subscriptions) by ID. Include up to 20,000 `subscription_id` per API call. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "included_segments": { "type": "array", "description": "Target predefined [Segments](/docs/segmentation). Users that are in multiple segments will only be sent the message once. Can be combined with `excluded_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "excluded_segments": { "type": "array", "description": "Exclude users in predefined [Segments](/docs/segmentation). Overrides membership in any segment specified in the `included_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "filters": { "type": "array", "description": "Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).", "items": { "oneOf": [ { "title": "Filter", "description": "Required. The fitler object.", "required": [ "field", "relation" ], "type": "object", "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "enum": [ "tag", "last_session", "first_session", "session_count", "session_time", "language", "app_version", "location", "country" ] }, "relation": { "type": "string", "description": "Used with most filters. See details on the specific filter.", "enum": [ "=", "!=", ">", "<", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with." } } }, { "title": "Operator", "type": "object", "properties": { "operator": { "type": "string", "description": "Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.", "enum": [ "AND", "OR" ], "default": "AND" } } } ] }, "minItems": 1, "maxItems": 200 }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages).", "default": "Default message." } } }, "headings": { "type": "object", "description": "The message title with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Required for Huawei and Web Push. If not set for Web Push, it defaults to your 'Site Name'. Not required if using `template_id` or `content_available`. Supports [Message Personalization](/docs/message-personalization) and must include the same languages as `contents` to ensure localization consistency.", "properties": { "en": { "type": "string", "description": "The title in English. If used, must include the same languages as `contents`." } } }, "subtitle": { "type": "object", "description": "iOS only. The subtitle with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization) and must include the same languages as `contents` to ensure localization consistency.", "properties": { "en": { "type": "string", "description": "The subtitle for iOS push only. If used, must include the same languages as `contents`." } } }, "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters." }, "template_id": { "type": "string", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates)." }, "custom_data": { "type": "object", "description": "Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email)." }, "ios_attachments": { "type": "object", "description": "The local name or URL of the media attachment to include in your notification. Users can expand the notification to view images, videos, or other supported attachments. See [Images & Rich Media](/docs/rich-media).", "properties": { "id": { "type": "string", "description": "The URL of the media to display in the notification. Example: `https://avatars.githubusercontent.com/u/11823027?s=200&v=4`" } } }, "big_picture": { "type": "string", "description": "The local name or URL of the image to include in your Google Android notification. Users can expand the notification to view the images. See [Images & Rich Media](/docs/rich-media)." }, "huawei_big_picture": { "type": "string", "description": "The local name or URL of the image to include in your Huawei Android notification. Users can expand the notification to view the images. See [Images & Rich Media](/docs/rich-media)." }, "adm_big_picture": { "type": "string", "description": "The local name or URL of the image to include in your Amazon Android notification. Users can expand the notification to view the images. See [Images & Rich Media](/docs/rich-media)." }, "chrome_web_image": { "type": "string", "description": "The URL of the image to include in your Chrome notification. Users can expand the notification to view the images. Supported on Chrome for Windows and Android. macOS does not support this parameter and instead expands the `chrome_web_icon`. See [Images & Rich Media](/docs/rich-media)." }, "small_icon": { "type": "string", "description": "The local name of the small icon to display in the Google Android notification. See [Notification icons](/docs/notification-icons)." }, "huawei_small_icon": { "type": "string", "description": "The local name of the small icon to display in the Huawei Android notification. See [Notification icons](/docs/notification-icons)." }, "adm_small_icon": { "type": "string", "description": "The local name of the small icon to display in the Amazon Android notification. See [Notification icons](/docs/notification-icons)." }, "large_icon": { "type": "string", "description": "The local name or URL of the large icon to display in the Google Android notification. See [Notification icons](/docs/notification-icons)." }, "huawei_large_icon": { "type": "string", "description": "The local name or URL of the large icon to display in the Huawei Android notification. See [Notification icons](/docs/notification-icons)." }, "adm_large_icon": { "type": "string", "description": "The local name or URL of the large icon to display in the Amazon Android notification. See [Notification icons](/docs/notification-icons)." }, "chrome_web_icon": { "type": "string", "description": "The URL of the icon to display in the Chrome web notification. Defaults to the resource set in the OneSignal dashboard. See [Notification icons](/docs/notification-icons)." }, "firefox_icon": { "type": "string", "description": "The URL of the icon to display in the Firefox web notification. Defaults to the resource set in the OneSignal dashboard. See [Notification icons](/docs/notification-icons)." }, "chrome_web_badge": { "type": "string", "description": "The URL of the icon to display in the Android notification tray for Chrome web notifications. Defaults to the Chrome icon. See [Push](/docs/push#badges)." }, "android_channel_id": { "type": "string", "description": "The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your OneSignal app." }, "existing_android_channel_id": { "type": "string", "description": "The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your Android app." }, "huawei_channel_id": { "type": "string", "description": "The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your OneSignal app." }, "huawei_existing_channel_id": { "type": "string", "description": "The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your Huawei app." }, "huawei_category": { "type": "string", "description": "The category you set for notifications sent to Huawei devices. The category chosen must align with an approved [self-classification application](https://developer.huawei.com/consumer/cn/doc/HMSCore-Guides/message-classification-0000001149358835#section1653845862216). Subject to daily send limitations ranging from 2 to 5, depending on the specific [third-level classifications](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-restriction-description-0000001361648361#section199311418515) the message falls under.", "enum": [ "MARKETING", "IM", "VOIP", "SUBSCRIPTION", "TRAVEL", "HEALTH", "WORK", "ACCOUNT", "EXPRESS", "FINANCE", "DEVICE_REMINDER", "MAIL" ], "default": "MARKETING" }, "huawei_msg_type": { "type": "string", "description": "Controls how OneSignal delivers the push to Huawei (HMS) devices. Both options can display a visible notification. Options: `message` - (default) HMS Core renders the notification server-side. Supports title and body only (no images, buttons, or other rich features). Displays even if the app is force quit, and if the device is offline it displays when the device reconnects within the `ttl` timeframe (usually 3 days). Does **not** support [Confirmed delivery](/docs/confirmed-delivery#huawei) — Huawei reports receipts only in their own dashboard. `data` - HMS Core delivers the payload to the device and the OneSignal SDK renders the notification client-side. This enables the full OneSignal feature set (large images, action buttons, etc.) and supports [Confirmed delivery](/docs/confirmed-delivery#huawei). Because the SDK must run to render it, the notification is **not** shown if the app has been force quit (HMS Core will not start the app). This is also the type to use for silent [data & background notifications](/docs/data-notifications) on Huawei. Note: `data` here refers to the HMS transport type, not a silent notification — a `data`-type push with visible content still shows a full notification.", "enum": [ "message", "data" ], "default": "message" }, "huawei_bi_tag": { "type": "string", "description": "Define a tag for associating messages in a batch delivery, facilitating precise monitoring and analysis of delivery stats. This tag is returned to your server when Huawei's Push Kit sends a message receipt. You can set this parameter to track your push campaigns' performance and optimize your messaging strategy." }, "huawei_badge_class": { "type": "string", "description": "Required for Huawei badge. The fully qualified class name of the app's entry Activity in the format `.` (e.g., `com.example.myapp.MainActivity`). Tells the Huawei system which app icon to apply the badge to. See [Badges](/docs/badges#huawei-badges)." }, "huawei_badge_set_num": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 99, "description": "Sets the badge count to this exact number on Huawei devices. Range: 0–99. Set to `0` to clear the badge. If both `huawei_badge_set_num` and `huawei_badge_add_num` are provided, `huawei_badge_set_num` takes priority. Requires EMUI 10.0.0+ and Push SDK 10.1.0+. See [Badges](/docs/badges#huawei-badges)." }, "huawei_badge_add_num": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 99, "description": "Increments the existing badge count by this number on Huawei devices. Range: 1–99. If omitted along with `huawei_badge_set_num`, defaults to incrementing by 1. See [Badges](/docs/badges#huawei-badges)." }, "priority": { "type": "integer", "description": "Set the priority based on the urgency of the message. `10` - High priority. `5` - Normal priority. Recommended and default value is `10`. APNs and FCM use this parameter to determine how quickly a notification is delivered and processed, particularly in power-saving modes. If sending data/background notifications, `5` (Normal priority) is recommended. For details, see [APNs `apns-priority`](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns) and [FCM `priority`](https://firebase.google.com/docs/cloud-messaging/android/message-priority).", "format": "int32", "enum": [ 10, 5 ], "default": 10 }, "ios_interruption_level": { "type": "string", "description": "The priority and delivery timing of iOS notifications based on their importance and the urgency with which they should interrupt the user. See [iOS Focus modes and interruption levels](/docs/ios-focus-modes-and-interruption-levels).", "enum": [ "active", "passive", "time_sensitive", "critical" ], "default": "active" }, "ios_sound": { "type": "string", "description": "The local name of the custom sound file to play when the notification is received instead of the default sound. See [Notification sounds](/docs/notification-sounds)." }, "ios_badgeType": { "type": "string", "description": "Set or increment the badge count on iOS devices. Use with `ios_badgeCount`. See [Badges](/docs/badges).", "enum": [ "None", "SetTo", "Increase" ], "default": "None" }, "ios_badgeCount": { "type": "integer", "description": "Use with `ios_badgeType` to determine the numerical change to your app's badge count. See [Badges](/docs/badges).", "format": "int32" }, "android_accent_color": { "type": "string", "description": "The ARGB Hex formatted color of the Android small icon background. For Android 8+ use [Android notification channel category](/docs/android-notification-categories) and `android_channel_id`." }, "huawei_accent_color": { "type": "string", "description": "The ARGB Hex formatted color of the Huawei small icon background. For Android 8+ use [Android notification channel category](/docs/android-notification-categories) and `huawei_channel_id`." }, "url": { "type": "string", "description": "The `https`URL that opens in the browser when a user interacts with the notification. See [URLs, Links and Deep Links](/docs/links). Supports [Message Personalization](/docs/message-personalization)." }, "app_url": { "type": "string", "description": "Similar to the `url` parameter but exclusively targets mobile platforms like iOS, Android. Accepts values other than `https` but must use `your-app-scheme://` protocol." }, "web_url": { "type": "string", "description": "Use with `app_url` if your app and website need different URLs. Accepts URLs with protocol `https://`" }, "target_content_identifier": { "type": "string", "description": "Direct the notification to a specific user experience within your app, such as an App Clip, or target a particular window in applications that use multiple scenes. See [Apple's documentation](https://developer.apple.com/documentation/foundation/nsuseractivity/3238062-targetcontentidentifier)." }, "buttons": { "type": "array", "description": "Add a maximum of 3 Action Buttons to Android and iOS push notifications. See [Action Buttons](/docs/action-buttons).", "maxItems": 3, "items": { "properties": { "id": { "type": "string", "description": "The ID to reference the button clicked event in your app." }, "text": { "type": "string", "description": "The text to display on the button." }, "icon": { "type": "string", "description": "The local name of the icon to display on the button." } }, "required": [ "id", "text" ], "additionalProperties": false } }, "web_buttons": { "type": "array", "description": "Add a maximum of 2 Action Buttons to Chrome web push notifications. See [Action Buttons](/docs/action-buttons).", "maxItems": 2, "items": { "properties": { "id": { "type": "string", "description": "The ID to reference the button clicked event in your app." }, "text": { "type": "string", "description": "The text to display on the button." }, "url": { "type": "string", "description": "The URL to open when the button is clicked." } }, "required": [ "id", "text", "url" ], "additionalProperties": false } }, "thread_id": { "type": "string", "description": "An ID to group notifications on Apple devices. Notifications with the same identifier are organized together in the notification center." }, "ios_relevance_score": { "type": "number", "description": "A value between `0` and `1`, to sort the notifications from your app. The highest score gets featured in the notification summary. See [iOS Relevance Score](/docs/ios-relevance-score)", "format": "double" }, "android_group": { "type": "string", "description": "An ID to group notifications on Google Android devices. Notifications with the same identifier are organized together in the notification center." }, "adm_group": { "type": "string", "description": "An ID to group notifications on Amazon Android devices. Notifications with the same identifier are organized together in the notification center." }, "ttl": { "type": "integer", "description": "The duration in seconds for which a notification remains valid if the device is offline. Any number between `0` and `2419200` (28 days). Defaults to 3 days. See [Push: Time to Live](/docs/push#time-to-live).", "format": "int32", "default": 259200 }, "collapse_id": { "type": "string", "description": "An ID that replaces older notifications with newer ones that have the same identifier. For mobile push only. See [Push: Collapse ID](/docs/push#collapse-id)." }, "web_push_topic": { "type": "string", "description": "An ID that prevents replacement of older notifications with newer ones that have different identifiers. For web push only. See [Push: Web Push Topic](/docs/push#web-push-topic)." }, "data": { "type": "object", "description": "Bundle a custom data map within your notification, which is then passed to your app. See [Push: Additional Data](/docs/push#additional-data).", "format": "json" }, "content_available": { "type": "boolean", "description": "Allows for sending data/background notifications to the Android and iOS apps. Set to `true` and omit `contents`. Apple interprets this as `content-available=1`. See [Data & background notifications](/docs/data-notifications)." }, "ios_category": { "type": "string", "description": "Enable users to respond directly to a notification without launching the app. The [Category](https://developer.apple.com/documentation/usernotifications/unnotificationcategory) will activate the corresponding [Notification Content Extension](https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension/) in your app when the push is interacted with." }, "apns_push_type_override": { "type": "string", "description": "Use only for VoIP notifications. Corresponds to the [`apns-push-type`](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns#Send-a-POST-request-to-APNs). OneSignal automatically sets this value to `alert` or `background` based on the notification content. Pass `voip` to initiate VoIP calls or alert the user to incoming VoIP calls." }, "isIos": { "type": "boolean", "description": "Specifies if the notification should target iOS mobile apps only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isAndroid": { "type": "boolean", "description": "Specifies if the notification should target Google Android mobile apps only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isHuawei": { "type": "boolean", "description": "Specifies if the notification should target Huawei mobile apps only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isAnyWeb": { "type": "boolean", "description": "Specifies if the notification should target web push only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isChromeWeb": { "type": "boolean", "description": "Specifies if the notification should target Chrome only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isFirefox": { "type": "boolean", "description": "Specifies if the notification should target Firefox only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled." }, "isSafari": { "type": "boolean", "description": "Specifies if the notification should target Safari only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled" }, "isWP_WNS": { "type": "boolean", "description": "Specifies if the notification should target Windows apps only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled" }, "isAdm": { "type": "boolean", "description": "Specifies if the notification should target Amazon devices only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled" }, "send_after": { "type": "string", "description": "Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`" }, "delayed_option": { "type": "string", "description": "Controls how messages are delivered on a per-user basis: `'timezone'` — Sends at the same local time across time zones. `'last-active'` — Delivers based on each user’s most recent session. Not compatible with [Push Throttling](/docs/throttling). If enabled, set `throttle_rate_per_minute` to `0`." }, "delivery_time_of_day": { "type": "string", "description": "Use with `delayed_option: 'timezone'` to set a consistent local delivery time. Accepted formats: `'9:00AM'` (12-hour), `'21:45'` (24-hour), `'09:45:30'` (HH:mm:ss)." }, "throttle_rate_per_minute": { "type": "number", "description": "Overrides the throttle limit set in the OneSignal dashboard settings. Must be enabled through the dashboard. Only available with push notifications. See [Push Throttling](/docs/throttling). If `throttle_rate_per_minute` is set to `0`, then the message will be sent immediately without any rate limiting." }, "enable_frequency_cap": { "type": "boolean", "description": "Overrides the frequency cap set in the OneSignal dashboard settings. Must be enabled through the dashboard first. Only available with push notifications. See [Frequency Capping](/docs/frequency-capping). Set to `false` to disable frequency capping." }, "idempotency_key": { "type": "string", "description": "A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Message Sent", "type": "object", "properties": { "id": { "type": "string", "description": "Notification ID in UUID v4 format. If `id` is an empty string, then the message was not sent.", "format": "uuid" }, "external_id": { "type": [ "string", "null" ], "description": "The `idempotency_key` parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see [Idempotent message requests](/reference/idempotent-notification-requests)." }, "errors": { "type": "object", "description": "Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.", "properties": { "invalid_aliases": { "type": "object", "description": "The alias label that was used in the `include_aliases` parameter.", "properties": { "external_id": { "type": "array", "items": { "type": "string", "description": "The alias IDs associated with the unsubscribed Subscriptions. The Subscriptions associated with the listed aliases were unsubscribed before the message was sent. In this example, `user_id_1` has two unsubscribed Subscriptions while `user_id_2` has one unsubscribed Subscription.", "example": "[\"user_id_1\", \"user_id_1\", \"user_id_2\"]" } }, "onesignal_id": { "type": "array", "items": { "type": "string", "description": "The OneSignal ID associated with the unsubscribed Subscription. The Subscriptions associated with the listed OneSignal IDs were unsubscribed before the message was sent. In this example, the user with OneSignal ID `1589641e-bed1-4325-bce4-d2234e578884` has three unsubscribed Subscriptions.", "example": "[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]" } } } }, "invalid_player_ids": { "type": "array", "items": { "type": "string", "description": "The Subscription ID exists in the OneSignal app but is unsubscribed from the message channel. If the Subscription ID did not exist, it will not be reported." } } } }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).", "required": [ "id" ] }, { "title": "Message Not Sent", "type": "object", "properties": { "id": { "type": "string", "description": "If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.", "example": "", "enum": [ "" ] }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Reasons the message was not dispatched. The most common value is `\"All included players are not subscribed\"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.", "example": [ "All included players are not subscribed" ] }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.", "required": [ "id", "errors" ] } ], "description": "Two variants are possible with HTTP 200, distinguished by the `id` field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect `errors` when `id` is empty." } } }, "headers": { "Idempotent-Replayed": { "description": "Present and set to `true` when this response is a replay of a previous successful request that used the same `idempotency_key`. Absent on fresh executions. Use this to distinguish \"new send\" from \"deduplicated retry\" without inspecting the body.", "schema": { "type": "boolean", "enum": [ true ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The reason for the bad request.", "items": { "properties": { "Message Notifications must have English language content": { "type": "string", "description": "Make sure the request or template has English language ('en')content. This is required but can be any language desired." }, "Incorrect subscription_id format in include_subscription_ids (not a valid UUID):": { "type": "string", "description": "The provided `subscription_id` is not a valid UUID." }, "Platforms You may only send to one delivery channel at a time. Make sure you are only including one of push platforms, Email, or SMS.": { "type": "string", "description": "You are attempting to send a message to a Subscription for a different channel. Make sure you are only targeting one channel at a time." } } } } } } } } }, "403": { "description": "Forbidden. The Authorization key cannot send notifications for this app, or the request targets a feature the app's plan does not enable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "This API is not available for applications on your plan." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/notifications?c=sms": { "post": { "summary": "SMS", "description": "Send a message using the SMS channel.", "operationId": "sms", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\nimport { randomUUID } from 'node:crypto';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\nconst notification = new Onesignal.Notification();\nnotification.app_id = 'YOUR_APP_ID';\nnotification.contents = { en: 'Hello from OneSignal!' };\nnotification.sms_from = '+15551234567';\n// Target by External ID: alias keys must match the API (external_id, not externalId).\nnotification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };\nnotification.target_channel = 'sms';\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. `randomUUID` is imported from `node:crypto`\n// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.\nnotification.idempotency_key = randomUUID();\n\ntry {\n const response = await apiInstance.createNotification(notification);\n if (!response.id) {\n console.warn(\"Notification was not sent:\", response.errors);\n } else if (response.errors) {\n console.log(\"Notification created:\", response.id, \"(partial failures:\", response.errors, \")\");\n } else {\n console.log(\"Notification created:\", response.id);\n }\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createNotification failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import uuid\nimport onesignal\nfrom onesignal.api import default_api\nfrom onesignal.model.language_string_map import LanguageStringMap\nfrom onesignal.model.notification import Notification\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\nwith onesignal.ApiClient(configuration) as api_client:\n api_instance = default_api.DefaultApi(api_client)\n notification = Notification(\n app_id='YOUR_APP_ID',\n contents=LanguageStringMap(en='Hello from OneSignal!'),\n sms_from='+15551234567',\n include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},\n target_channel='sms',\n # Idempotency key: a client-generated UUID that lets you safely retry on network\n # failure. If two requests arrive with the same key inside the 30-day window, only\n # the first is sent and the second returns the original response. Use uuid.uuid4()\n # or a similar source of randomness — DO NOT reuse keys across logically distinct\n # sends.\n idempotency_key=str(uuid.uuid4()),\n )\n try:\n api_response = api_instance.create_notification(notification)\n # `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or\n # a dict keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped. Access via `.get('errors')` rather than\n # attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises\n # `ApiAttributeError` for optional fields that the server omitted, so plain\n # `api_response.errors` would crash on the pure-success path.\n response_id = api_response.get('id')\n response_errors = api_response.get('errors')\n if not response_id:\n print('Notification was not sent:', response_errors)\n elif response_errors:\n print('Notification created:', response_id, '(partial failures:', response_errors, ')')\n else:\n print('Notification created:', response_id)\n except onesignal.ApiException as e:\n print('Exception when calling DefaultApi->create_notification: %s\\n' % e)\n print('Status Code: %s' % e.status)\n # `e.error_messages` flattens any error-envelope shape to a list[str];\n # the raw body remains on `e.body`.\n print('Error Messages: %s' % e.error_messages)\n print('Response Body: %s' % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n new GuzzleHttp\\Client(),\n $config\n);\n\n$notification = new onesignal\\client\\Model\\Notification();\n$notification->setAppId('YOUR_APP_ID');\n$contents = new onesignal\\client\\Model\\LanguageStringMap();\n$contents->setEn('Hello from OneSignal!');\n$notification->setContents($contents);\n$notification->setSmsFrom('+15551234567');\n$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);\n$notification->setTargetChannel('sms');\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. Use a strong source of randomness — DO NOT\n// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here\n// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with\n// no extra install; projects that already pull in ramsey/uuid can swap in\n// `\\Ramsey\\Uuid\\Uuid::uuid4()->toString()` instead.\n$idempotencyKeyBytes = random_bytes(16);\n$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);\n$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);\n$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));\n$notification->setIdempotencyKey($idempotencyKey);\n\ntry {\n $result = $apiInstance->createNotification($notification);\n // `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty\n // string or null) means no notification was created (e.g. all targets were\n // unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`\n // in the no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (!$result->getId()) {\n echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;\n } elseif ($result->getErrors()) {\n echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;\n } else {\n echo 'Notification created: ', $result->getId(), PHP_EOL;\n }\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/google/uuid\"\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\")\n\n notification := onesignal.NewNotification(\"YOUR_APP_ID\")\n contents := onesignal.NewLanguageStringMap()\n contents.SetEn(\"Hello from OneSignal!\")\n notification.SetContents(*contents)\n notification.SetSmsFrom(\"+15551234567\")\n notification.SetIncludeAliases(map[string][]string{\"external_id\": {\"YOUR_USER_EXTERNAL_ID\"}})\n notification.SetTargetChannel(\"sms\")\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `github.com/google/uuid` module\n // is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`\n // after importing it) before building. DO NOT reuse keys across logically distinct sends.\n notification.SetIdempotencyKey(uuid.NewString())\n\n resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateNotification``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n return\n }\n // `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in\n // the no-subscribers case, or a map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if resp.GetId() == \"\" {\n fmt.Fprintf(os.Stderr, \"Notification was not sent: %v\\n\", resp.GetErrors())\n } else if errors := resp.GetErrors(); errors != nil {\n fmt.Fprintf(os.Stdout, \"Notification created: %s (partial failures: %v)\\n\", resp.GetId(), errors)\n } else {\n fmt.Fprintf(os.Stdout, \"Notification created: %s\\n\", resp.GetId())\n }\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nrequire 'securerandom'\n\nnotification = OneSignal::Notification.new\nnotification.app_id = 'YOUR_APP_ID'\nnotification.contents = OneSignal::LanguageStringMap.new({ en: 'Hello from OneSignal!' })\nnotification.sms_from = '+15551234567'\nnotification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }\nnotification.target_channel = 'sms'\n# Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n# If two requests arrive with the same key inside the 30-day window, only the first is sent\n# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys\n# across logically distinct sends.\nnotification.idempotency_key = SecureRandom.uuid\n\nbegin\n # Create notification\n result = api_instance.create_notification(notification)\n # `result.id` discriminates the two HTTP 200 shapes. An empty string means no\n # notification was created (e.g. all targets were unreachable / not subscribed).\n # `result.errors` is polymorphic: an `Array` in the no-subscribers case, or\n # a Hash keyed by recipient-identifier type (`invalid_player_ids`,\n # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n # created but some recipients were skipped.\n if result.id.to_s.empty?\n puts \"Notification was not sent: #{result.errors}\"\n elsif result.errors\n puts \"Notification created: #{result.id} (partial failures: #{result.errors})\"\n else\n puts \"Notification created: #{result.id}\"\n end\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_notification: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport java.util.Arrays;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.UUID;\n\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n Notification notification = new Notification();\n notification.setAppId(\"YOUR_APP_ID\");\n LanguageStringMap contents = new LanguageStringMap();\n contents.setEn(\"Hello from OneSignal!\");\n notification.setContents(contents);\n notification.setSmsFrom(\"+15551234567\");\n Map> aliases = new HashMap<>();\n aliases.put(\"external_id\", Arrays.asList(\"YOUR_USER_EXTERNAL_ID\"));\n notification.setIncludeAliases(aliases);\n notification.setTargetChannel(Notification.TargetChannelEnum.SMS);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. Use UUID.randomUUID() — DO NOT\n // reuse keys across logically distinct sends.\n notification.setIdempotencyKey(UUID.randomUUID().toString());\n\n try {\n CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);\n // `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no\n // notification was created (e.g. all targets were unreachable / not subscribed).\n // `result.getErrors()` is polymorphic (declared as `Object`): a `List` in the\n // no-subscribers case, or a Map keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n // the notification WAS created but some recipients were skipped.\n if (result.getId() == null || result.getId().isEmpty()) {\n System.out.println(\"Notification was not sent: \" + result.getErrors());\n } else if (result.getErrors() != null) {\n System.out.println(\"Notification created: \" + result.getId() + \" (partial failures: \" + result.getErrors() + \")\");\n } else {\n System.out.println(\"Notification created: \" + result.getId());\n }\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createNotification\");\n System.err.println(\"Status code: \" + e.getCode());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateNotificationExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n\n var notification = new Notification\n {\n AppId = \"YOUR_APP_ID\",\n Contents = new LanguageStringMap(en: \"Hello from OneSignal!\"),\n SmsFrom = \"+15551234567\",\n IncludeAliases = new Dictionary>\n {\n { \"external_id\", new List { \"YOUR_USER_EXTERNAL_ID\" } }\n },\n TargetChannel = Notification.TargetChannelEnum.Sms,\n // Idempotency key: a client-generated UUID that lets you safely retry on\n // network failure. If two requests arrive with the same key inside the\n // 30-day window, only the first is sent and the second returns the original\n // response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct\n // sends.\n IdempotencyKey = Guid.NewGuid().ToString()\n };\n\n try\n {\n CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);\n // `result.Id` discriminates the two HTTP 200 shapes. An empty string means\n // no notification was created (e.g. all targets were unreachable / not\n // subscribed). `result.Errors` is polymorphic: a `List` in the\n // no-subscribers case, or an object keyed by recipient-identifier type\n // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)\n // when the notification WAS created but some recipients were skipped.\n if (string.IsNullOrEmpty(result.Id))\n {\n Debug.WriteLine(\"Notification was not sent: \" + result.Errors);\n }\n else if (result.Errors != null)\n {\n Debug.WriteLine(\"Notification created: \" + result.Id + \" (partial failures: \" + result.Errors + \")\");\n }\n else\n {\n Debug.WriteLine(\"Notification created: \" + result.Id);\n }\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateNotification: \" + e.Message);\n Debug.Print(\"Status Code: \" + e.ErrorCode);\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\nuse onesignal_rust_api::models::notification::TargetChannelType;\nuse onesignal_rust_api::models::{LanguageStringMap, Notification};\nuse uuid::Uuid;\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n let mut notification = Notification::new(\"YOUR_APP_ID\".to_string());\n notification.contents = Some(Box::new(LanguageStringMap {\n en: Some(\"Hello from OneSignal!\".to_string()),\n ..Default::default()\n }));\n notification.sms_from = Some(\"+15551234567\".to_string());\n let mut aliases = std::collections::HashMap::new();\n aliases.insert(\n \"external_id\".to_string(),\n vec![\"YOUR_USER_EXTERNAL_ID\".to_string()],\n );\n notification.include_aliases = Some(aliases);\n notification.target_channel = Some(TargetChannelType::Sms);\n // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n // If two requests arrive with the same key inside the 30-day window, only the first is\n // sent and the second returns the original response. The `uuid` crate must be declared\n // in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream\n // code) — add `uuid = { version = \"1\", features = [\"v4\"] }` to your `[dependencies]`.\n // DO NOT reuse keys across logically distinct sends.\n notification.idempotency_key = Some(Uuid::new_v4().to_string());\n\n match default_api::create_notification(&configuration, notification).await {\n Ok(resp) => {\n // `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`\n // means no notification was created (e.g. all targets were unreachable / not\n // subscribed). `resp.errors` is polymorphic (typed as `Option`):\n // a `Vec` in the no-subscribers case, or an object keyed by\n // recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,\n // `invalid_aliases`, ...) when the notification WAS created but some recipients\n // were skipped.\n match resp.id.as_deref() {\n Some(\"\") | None => eprintln!(\"Notification was not sent: {:?}\", resp.errors),\n Some(id) if resp.errors.is_some() => {\n println!(\"Notification created: {} (partial failures: {:?})\", id, resp.errors)\n }\n Some(id) => println!(\"Notification created: {}\", id),\n }\n }\n Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {\n eprintln!(\"create_notification failed: HTTP {}\", content.status);\n eprintln!(\"Response Body: {}\", content.content);\n }\n Err(e) => eprintln!(\"create_notification failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "contents", "target_channel" ], "properties": { "app_id": { "type": "string", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "default": "YOUR_APP_ID" }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Too many characters may result in multiple messages and increased costs. See [SMS](/docs/sms-messaging). Required unless using `template_id`. Supports [Message Personalization](/docs/message-personalization). You can add trackable links to your SMS via the API by including liquid syntax in your message contents. For example: {{'your_url' | track_link}} The liquid syntax block will be replaced with a trackable short link in the following format: 1sgnl.co/XXXX. Using trackable links allows you to see the click through rates of your SMS.", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "include_aliases": { "type": "object", "description": "Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).", "format": "json", "properties": { "external_id": { "description": "An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).", "type": "array", "items": { "type": "string" } } } }, "target_channel": { "type": "string", "description": "The targeted delivery channel. Required when using `include_aliases` and `included_segments` for SMS/RCS. Accepts `push`, `email`, or `sms`.", "enum": [ "push", "email", "sms" ], "default": "sms" }, "include_subscription_ids": { "type": "array", "description": "Target users' specific [subscriptions](/docs/subscriptions) by ID. Include up to 20,000 `subscription_id` per API call. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "include_phone_numbers": { "type": "array", "description": "Send SMS/MMS to specific users by their phone number in [E.164 format](/docs/sms-setup#what-is-e164-format). Can only be used when sending [SMS/MMS](/reference/sms). Include up to 20,000 phone numbers per API call. If the phone number does not exist within the OneSignal App, then a new SMS Subscription will be created. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "included_segments": { "type": "array", "description": "Target predefined [Segments](/docs/segmentation). Users that are in multiple segments will only be sent the message once. Can be combined with `excluded_segments`. Requires `target_channel` to be set to `'sms'` or `isSms=true` when sending SMS/RCS. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "excluded_segments": { "type": "array", "description": "Exclude users in predefined [Segments](/docs/segmentation). Overrides membership in any segment specified in the `included_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "filters": { "type": "array", "description": "Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).", "items": { "oneOf": [ { "title": "Filter", "description": "Required. The fitler object.", "required": [ "field", "relation" ], "type": "object", "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "enum": [ "tag", "last_session", "first_session", "session_count", "session_time", "language", "app_version", "location", "country" ] }, "relation": { "type": "string", "description": "Used with most filters. See details on the specific filter.", "enum": [ "=", "!=", ">", "<", "exists", "not_exists", "in_array", "not_in_array", "time_elapsed_gt", "time_elapsed_lt" ] }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with." } } }, { "title": "Operator", "type": "object", "properties": { "operator": { "type": "string", "description": "Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.", "enum": [ "AND", "OR" ], "default": "AND" } } } ] }, "minItems": 1, "maxItems": 200 }, "sms_from": { "type": "string", "description": "The [Messaging Service ID](/docs/en/sms-setup#step-2-create-senders) or phone number used to send the SMS or MMS. Its recommended to use Messaging Service SIDs (e.g., `MGxxxxxxxxxxxxxxx`) but also accepts E.164 phone numbers (e.g., `+12065551234`). Defaults to the sender selected in [SMS Setup](/docs/en/sms-setup). If using [per-sender opt-out](/docs/en/sms-consent-keyword-management), you must use a Messaging Service ID." }, "sms_media_urls": { "type": "array", "description": "URLs for the media files to be sent as MMS. Additional rates apply. `sms_from` must support sending MMS messages. See [SMS](/docs/sms-messaging).", "items": { "type": "string" } }, "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters." }, "template_id": { "type": "string", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates)." }, "custom_data": { "type": "object", "description": "Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email)." }, "send_after": { "type": "string", "description": "Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`" }, "idempotency_key": { "type": "string", "description": "A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Message Sent", "type": "object", "properties": { "id": { "type": "string", "description": "Notification ID in UUID v4 format. If `id` is an empty string, then the message was not sent.", "format": "uuid" }, "external_id": { "type": [ "string", "null" ], "description": "The `idempotency_key` parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see [Idempotent message requests](/reference/idempotent-notification-requests)." }, "errors": { "type": "object", "description": "Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.", "properties": { "invalid_phone_numbers": { "type": "array", "items": { "type": "string", "description": "The listed phone numbers used in the `include_phone_numbers` parameter that were unsubscribed from the message channel before the message was sent." } }, "invalid_aliases": { "type": "object", "description": "The alias label that was used in the `include_aliases` parameter.", "properties": { "external_id": { "type": "array", "items": { "type": "string", "description": "The alias IDs associated with the unsubscribed Subscriptions. The Subscriptions associated with the listed aliases were unsubscribed before the message was sent. In this example, `user_id_1` has two unsubscribed Subscriptions while `user_id_2` has one unsubscribed Subscription.", "example": "[\"user_id_1\", \"user_id_1\", \"user_id_2\"]" } }, "onesignal_id": { "type": "array", "items": { "type": "string", "description": "The OneSignal ID associated with the unsubscribed Subscription. The Subscriptions associated with the listed OneSignal IDs were unsubscribed before the message was sent. In this example, the user with OneSignal ID `1589641e-bed1-4325-bce4-d2234e578884` has three unsubscribed Subscriptions.", "example": "[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]" } } } }, "invalid_player_ids": { "type": "array", "items": { "type": "string", "description": "The Subscription ID exists in the OneSignal app but is unsubscribed from the message channel. If the Subscription ID did not exist, it will not be reported." } } } }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).", "required": [ "id" ] }, { "title": "Message Not Sent", "type": "object", "properties": { "id": { "type": "string", "description": "If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.", "example": "", "enum": [ "" ] }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Reasons the message was not dispatched. The most common value is `\"All included players are not subscribed\"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.", "example": [ "All included players are not subscribed" ] }, "warnings": { "oneOf": [ { "type": "object", "description": "Object form.", "properties": { "invalid_external_user_ids": { "type": "string", "description": "external_ids whose subscriptions are unsubscribed." } }, "additionalProperties": true }, { "type": "array", "items": { "type": "string" }, "description": "Array form. Contains non-fatal warning messages." } ], "description": "Non-fatal warnings emitted alongside a successful send." } }, "description": "Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.", "required": [ "id", "errors" ] } ], "description": "Two variants are possible with HTTP 200, distinguished by the `id` field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect `errors` when `id` is empty." } } }, "headers": { "Idempotent-Replayed": { "description": "Present and set to `true` when this response is a replay of a previous successful request that used the same `idempotency_key`. Absent on fresh executions. Use this to distinguish \"new send\" from \"deduplicated retry\" without inspecting the body.", "schema": { "type": "boolean", "enum": [ true ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The reason for the bad request.", "items": { "properties": { "Message Notifications must have English language content": { "type": "string", "description": "Make sure the request or template has English language ('en')content. This is required but can be any language desired." }, "Incorrect subscription_id format in include_subscription_ids (not a valid UUID):": { "type": "string", "description": "The provided `subscription_id` is not a valid UUID." }, "Platforms You may only send to one delivery channel at a time. Make sure you are only including one of push platforms, Email, or SMS.": { "type": "string", "description": "You are attempting to send a message to a Subscription for a different channel. Make sure you are only targeting one channel at a time." } } } } } } } } }, "403": { "description": "Forbidden. The Authorization key cannot send SMS for this app, or the request targets a feature the app's plan does not enable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "This API is not available for applications on your plan." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/live_activities/{activity_id}/notifications": { "post": { "summary": "Update Live Activity", "description": "Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.", "operationId": "update-live-activity-api", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The OneSignal App ID for your app. Available in Keys & IDs.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | Live Activity record ID\nconst activityId: string = \"12345\";\n// UpdateLiveActivityRequest\nconst updateLiveActivityRequest: Onesignal.UpdateLiveActivityRequest = {\n name: \"name_example\",\n event: \"update\",\n event_updates: {},\n contents: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n headings: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n sound: \"sound_example\",\n stale_date: 1,\n dismissal_date: 1,\n priority: 1,\n };\n\ntry {\n const response = await apiInstance.updateLiveActivity(appId, activityId, updateLiveActivityRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateLiveActivity failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The OneSignal App ID for your app. Available in Keys & IDs. \n activity_id = \"12345\" # Live Activity record ID \n update_live_activity_request = UpdateLiveActivityRequest(\n name=\"name_example\",\n event=\"update\",\n event_updates={},\n contents=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n headings=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n sound=\"sound_example\",\n stale_date=1,\n dismissal_date=1,\n priority=1,\n ) \n\n try:\n # Update a Live Activity via Push\n api_response = api_instance.update_live_activity(app_id, activity_id, update_live_activity_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_live_activity: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n$activity_id = '12345'; // string | Live Activity record ID\n$update_live_activity_request = new \\onesignal\\client\\model\\UpdateLiveActivityRequest(); // \\onesignal\\client\\model\\UpdateLiveActivityRequest\n\ntry {\n $result = $apiInstance->updateLiveActivity($app_id, $activity_id, $update_live_activity_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateLiveActivity: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateLiveActivity: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The OneSignal App ID for your app. Available in Keys & IDs.\n activityId := \"12345\" // string | Live Activity record ID\n updateLiveActivityRequest := *onesignal.NewUpdateLiveActivityRequest(\"Name_example\", \"Event_example\", map[string]interface{}{\"key\": \"value\"}) // UpdateLiveActivityRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateLiveActivity(restAuth, appId, activityId).UpdateLiveActivityRequest(updateLiveActivityRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateLiveActivity``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateLiveActivity`: UpdateLiveActivitySuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateLiveActivity`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The OneSignal App ID for your app. Available in Keys & IDs.\nactivity_id = '12345' # String | Live Activity record ID\nupdate_live_activity_request = OneSignal::UpdateLiveActivityRequest.new({name: 'name_example', event: 'update', event_updates: 3.56}) # UpdateLiveActivityRequest | \n\nbegin\n # Update a Live Activity via Push\n result = api_instance.update_live_activity(app_id, activity_id, update_live_activity_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_live_activity: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The OneSignal App ID for your app. Available in Keys & IDs.\n String activityId = \"12345\"; // String | Live Activity record ID\n UpdateLiveActivityRequest updateLiveActivityRequest = new UpdateLiveActivityRequest(); // UpdateLiveActivityRequest | \n try {\n UpdateLiveActivitySuccessResponse result = apiInstance.updateLiveActivity(appId, activityId, updateLiveActivityRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateLiveActivity\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateLiveActivityExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The OneSignal App ID for your app. Available in Keys & IDs.\n var activityId = \"12345\"; // string | Live Activity record ID\n var updateLiveActivityRequest = new UpdateLiveActivityRequest(); // UpdateLiveActivityRequest | \n\n try\n {\n // Update a Live Activity via Push\n UpdateLiveActivitySuccessResponse result = apiInstance.UpdateLiveActivity(appId, activityId, updateLiveActivityRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateLiveActivity: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let activity_id: &str = \"12345\";\n let update_live_activity_request: models::UpdateLiveActivityRequest = todo!();\n\n match default_api::update_live_activity(&configuration, app_id, activity_id, update_live_activity_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_live_activity failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_live_activity failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "activity_id", "in": "path", "description": "An identifier you set when starting the Live Activity to uniquely identify it and associated devices with the event. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.", "schema": { "type": "string" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "event_updates", "name" ], "properties": { "event": { "type": "string", "description": "The action to perform on the Live Activity. Options:`update` - Updates the content of an existing Live Activity without ending it. `end` — Ends the Live Activity and removes it from the user's view. See Apple's developer docs on [Starting and updating Live Activities](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications).", "enum": [ "update", "end" ] }, "event_updates": { "type": "object", "description": "The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/live-activities-developer-setup).", "format": "json" }, "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters." }, "contents": { "type": "object", "description": "The push message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "stale_date": { "type": "integer", "description": "A Unix timestamp (in seconds) that indicates the date the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to [`ActivityState.stale`](https://developer.apple.com/documentation/activitykit/activitystate/stale) at which point you can update the Live Activity to indicate that its content is out of date.", "format": "int32" }, "dismissal_date": { "type": "integer", "description": "A Unix timestamp (in seconds) indicating when the Live Activity should be removed from user's device. Use with the `end` event. If not set, the Live Activity will be dismissed automatically after 4 hours. To dismiss the Live Activity immediately, the user must have allowed the Live Activity first. Then you can set a date that’s in the past — for example, `1663177260`. Alternatively, provide a date within a four-hour window to set a custom dismissal date before the default 4 hour period. See [Apple's documentation](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#End-the-Live-Activity-with-a-custom-dismissal-date) for more.", "format": "int32" }, "priority": { "type": "integer", "description": "Set the priority based on the urgency of the message. `10` - High priority. `5` - Normal priority. Apple allows a certain budget of High priority updates per hour. Exceeding the budget may throttle your messages. Apple recommends choosing a mix of priority `5` and `10` to prevent throttling. If your app needs more frequent updates, use `NSSupportsLiveActivitiesFrequentUpdates` entry as directed in [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).", "format": "int32", "enum": [ 5, 10 ] }, "ios_sound": { "type": "string", "description": "The name of a sound file in your app bundle to play when the Live Activity receives an update. If excluded, the system plays the default notification sound. Using the value `\"nil\"` will silence the sound." }, "ios_relevance_score": { "type": "number", "description": "A value between `0` and `1`. If you start more than one Live Activity for your app, the Live Activity with the highest relevance score appears in the Dynamic Island. If Live Activities have the same relevance score, the system displays the Live Activity that started first. Additionally, the Relevance Score determines the order of your Live Activities on the Lock Screen.", "format": "double" } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the Live Activity update request." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Reason for the message not being started. Usually due to the activity type not being found in the app." ] } } } }, "404": { "description": "Activity type was not found in the app, or the Authorization key cannot reach this app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "activity_id not found in this app" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}": { "get": { "summary": "View messages", "description": "View the details for a collection of messages.", "operationId": "view-messages", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | The app ID that you want to view notifications from\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// number | How many notifications to return. Max is 50. Default is 50. (optional)\nconst limit: number = 10;\n// number | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional)\nconst offset: number = 0;\n// 0 | 1 | 3 | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional)\nconst kind: 0 | 1 | 3 = 0;\n// string | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional)\nconst timeOffset: string = \"2025-01-01T00:00:00.000Z\";\n\ntry {\n const response = await apiInstance.getNotifications(appId, limit, offset, kind, timeOffset);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getNotifications failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # The app ID that you want to view notifications from \n limit = 10 # How many notifications to return. Max is 50. Default is 50. (optional) \n offset = 0 # Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) \n kind = 0 # Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) \n time_offset = \"2025-01-01T00:00:00.000Z\" # Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) \n\n try:\n # View notifications\n api_response = api_instance.get_notifications(app_id, limit=limit, offset=offset, kind=kind, time_offset=time_offset)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_notifications: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | The app ID that you want to view notifications from\n$limit = 10; // int | How many notifications to return. Max is 50. Default is 50.\n$offset = 0; // int | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at.\n$kind = 0; // int | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only\n$time_offset = '2025-01-01T00:00:00.000Z'; // string | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned.\n\ntry {\n $result = $apiInstance->getNotifications($app_id, $limit, $offset, $kind, $time_offset);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getNotifications: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getNotifications: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | The app ID that you want to view notifications from\n limit := int32(10) // int32 | How many notifications to return. Max is 50. Default is 50. (optional)\n offset := int32(0) // int32 | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional)\n kind := int32(0) // int32 | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional)\n timeOffset := \"2025-01-01T00:00:00.000Z\" // string | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional)\n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetNotifications(restAuth).AppId(appId).Limit(limit).Offset(offset).Kind(kind).TimeOffset(timeOffset).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetNotifications``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetNotifications`: NotificationSlice\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetNotifications`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | The app ID that you want to view notifications from\nopts = {\n limit: 10, # Integer | How many notifications to return. Max is 50. Default is 50.\n offset: 0, # Integer | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at.\n kind: 0, # Integer | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only \n time_offset: '2025-01-01T00:00:00.000Z' # String | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned.\n}\n\nbegin\n # View notifications\n result = api_instance.get_notifications(app_id, opts)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_notifications: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | The app ID that you want to view notifications from\n Integer limit = 10; // Integer | How many notifications to return. Max is 50. Default is 50.\n Integer offset = 0; // Integer | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at.\n Integer kind = 0; // Integer | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only \n String timeOffset = \"2025-01-01T00:00:00.000Z\"; // String | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned.\n try {\n NotificationSlice result = apiInstance.getNotifications(appId, limit, offset, kind, timeOffset);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getNotifications\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetNotificationsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | The app ID that you want to view notifications from\n var limit = 10; // int? | How many notifications to return. Max is 50. Default is 50. (optional) \n var offset = 0; // int? | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) \n var kind = 0; // int? | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) \n var timeOffset = \"2025-01-01T00:00:00.000Z\"; // string | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) \n\n try\n {\n // View notifications\n NotificationSlice result = apiInstance.GetNotifications(appId, limit, offset, kind, timeOffset);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetNotifications: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let limit: Option = None;\n let offset: Option = None;\n let kind: Option = None;\n let time_offset: Option<&str> = None;\n\n match default_api::get_notifications(&configuration, app_id, limit, offset, kind, time_offset).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_notifications failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_notifications failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "limit", "in": "query", "description": "Specifies the maximum number of messages to return in a single query. The maximum and default is **50** messages per request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "offset", "in": "query", "description": "Controls the starting point for the notifications being returned. Default is **0**. Results are returned and sorted in descending order by `queued_at`.", "schema": { "type": "integer", "format": "int32" } }, { "name": "kind", "in": "query", "description": "Specifies which push notifications to return based on how it was created. Use this to segment push by their creation method, allowing for targeted analysis or management of notification types. All push types are returned by default. `0` - Notifications created through the dashboard. `1` - Notifications sent via API calls. `3` - Notifications triggered through automated systems.", "schema": { "type": "integer", "format": "int32" } }, { "name": "template_id", "in": "query", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates).", "schema": { "type": "string" } }, { "name": "time_offset", "in": "query", "description": "An ISO 8601 formatted timestamp or Base64 integer token (provided in the API response). See [`time_offset` Accepted Values](#time_offset-accepted-values).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "description": "Returns all message properties for up to 50 messages per request. See the [Push notifications](/reference/push-notification), [Email](/reference/email), and/or [SMS](/reference/sms) Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.", "properties": { "total_count": { "type": "integer", "description": "The total number of messages available in the dashboard irrespective of page" }, "time_offset": { "type": "string", "description": "The `time_offset` if specified in the request." }, "next_time_offset": { "type": "string", "description": "A Base64-encoded cursor token representing the next group of messages to fetch if `time_offset` provided." }, "offset": { "type": "integer", "description": "The offset specified. Defaults to `0` if not provided in the request." }, "limit": { "type": "integer", "description": "The `limit` specified. Defaults to `50` if not provided in the request." }, "notifications": { "type": "array", "description": "An array of message objects. `notifications: []` indicates no more messages to fetch. The data provided is generally the most desired from this request", "items": { "type": "object", "properties": { "app_id": { "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "type": "string" }, "big_picture": { "description": "The URL of the image set in the push notification.", "type": "string" }, "canceled": { "description": "Whether the message was canceled.", "type": "boolean" }, "chrome_web_icon": { "description": "The URL of the icon set in the push notification.", "type": "string" }, "chrome_web_image": { "description": "The URL of the image set in the push notification.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.", "type": "string" }, "contents": { "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages).", "type": "object", "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "converted": { "type": "integer", "description": "The number of times the push was clicked." }, "data": { "type": "object", "description": "The JSON data set in the push notification if applicable." }, "delayed_option": { "type": "string", "description": "The per-user delay option set for the message." }, "delivery_time_of_day": { "type": "string", "description": "The delivery time of day set for the message if `delayed_option` is `timezone`." }, "remaining": { "type": "integer", "description": "The number of messages that have not been sent yet. If `null`, then the system is still processing the audience, try again later." }, "errored": { "type": "integer", "description": "The number of times the message errored." }, "excluded_segments": { "type": "array", "description": "The segments excluded from the message if applicable." }, "failed": { "type": "integer", "description": "The number of subscriptions reported unsubscribed for the message." }, "global_image": { "type": "string", "description": "The URL of the image set in the push notification." }, "headings": { "type": "object", "description": "The title of the push notification." }, "id": { "type": "string", "description": "The identifier of the message in UUID v4 format." }, "included_segments": { "type": "array", "description": "The segments included in the message if applicable." }, "ios_badgeCount": { "type": "integer", "description": "The badge count set for the message if applicable." }, "ios_badgeType": { "type": "string", "description": "The badge type set for the message if applicable." }, "queued_at": { "type": "integer", "description": "Unix timestamp of when the message was created." }, "send_after": { "type": "integer", "description": "Unix timestamp of when the message delivery was scheduled to begin." }, "completed_at": { "type": "integer", "description": "Unix timestamp of when the message delivery was completed. The delivery duration from start to finish can be calculated with `completed_at - send_after`. " }, "successful": { "type": "integer", "description": "The number of messages successfully delivered to the push, email, or SMS servers." }, "received": { "type": "integer", "description": "The number of messages that confirmed being received aka [Confirmed Deliveries](/docs/confirmed-delivery)." }, "filters": { "type": "object", "description": "The filters set for the message if applicable." }, "template_id": { "type": "string", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates)." }, "url": { "type": "string", "description": "The URL of the push notification." }, "web_url": { "type": "string", "description": "The URL of the push notification for web push subscriptions." }, "app_url": { "type": "string", "description": "The URL of the push notification for mobile subscriptions." }, "platform_delivery_stats": { "type": "object", "description": "The successful, errored, failed, converted, received and frequency cap counts for each platform applicable." }, "throttle_rate_per_minute": { "type": "number", "description": "The throttle rate of the push notification if applicable." }, "fcap_status": { "type": "string", "description": "The frequency cap status of the push notification if applicable." }, "outcomes": { "type": "object", "description": "The id, value, and aggregation type of the outcome set in the request." } } } } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/notifications/{message_id}?app_id={app_id}": { "get": { "summary": "View message", "description": "View the details of a single message and the Outcomes associated with it.", "operationId": "view-message", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst notificationId: string = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n\ntry {\n const response = await apiInstance.getNotification(appId, notificationId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"getNotification failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n notification_id = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" \n\n try:\n # View notification\n api_response = api_instance.get_notification(app_id, notification_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->get_notification: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string\n\ntry {\n $result = $apiInstance->getNotification($app_id, $notification_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->getNotification: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->getNotification: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n notificationId := \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.GetNotification(restAuth, notificationId).AppId(appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.GetNotification``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `GetNotification`: NotificationWithMeta\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.GetNotification`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nnotification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | \n\nbegin\n # View notification\n result = api_instance.get_notification(app_id, notification_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->get_notification: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // String | \n try {\n NotificationWithMeta result = apiInstance.getNotification(appId, notificationId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#getNotification\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class GetNotificationExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // string | \n\n try\n {\n // View notification\n NotificationWithMeta result = apiInstance.GetNotification(appId, notificationId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.GetNotification: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let notification_id: &str = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n\n match default_api::get_notification(&configuration, app_id, notification_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"get_notification failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"get_notification failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "message_id", "in": "path", "description": "The identifier of the message in UUID v4 format. Get this `id` in the response of your Create Message API request, the [View Messages API](/reference/view-messages), and in your OneSignal dashboard Message Reports.", "schema": { "type": "string" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "outcome_names", "in": "query", "description": "The name and aggregation type of the outcome(s) you want to fetch. Example: `my_outcome.count` or `my_outcome.sum`. For clicks, use `os__click.count`. For confirmed deliveries, use `os__confirmed_delivery.count`. For session duration, use `os__session_duration.count`.", "schema": { "type": "array", "items": { "type": "string", "default": [ "os__click.count", "os__confirmed_delivery.count", "os__session_duration.count" ] } } }, { "name": "outcome_time_range", "in": "query", "description": "Time range for the returned data. Available values: `1h` (1 hour), `1d` (1 day), `1mo` (1 month)", "schema": { "type": "string", "enum": [ "1h", "1d", "1mo" ], "default": "1h" } }, { "name": "outcome_platforms", "in": "query", "description": "The platforms in which you want to pull the data represented as the `device_type` integer.", "schema": { "type": "string", "default": "0,1,2,5,8,11,14,17" } }, { "name": "outcome_attribution", "in": "query", "description": "Attribution type for the outcomes.", "schema": { "type": "string", "enum": [ "direct", "influenced", "unattributed", "total" ], "default": "total" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "description": "Returns all message properties set. See the [Push notifications](/reference/push-notification), [Email](/reference/email), and/or [SMS](/reference/sms) Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.", "properties": { "app_id": { "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "type": "string" }, "big_picture": { "description": "The URL of the image set in the push notification.", "type": "string" }, "canceled": { "description": "Whether the message was canceled.", "type": "boolean" }, "chrome_web_icon": { "description": "The URL of the icon set in the push notification.", "type": "string" }, "chrome_web_image": { "description": "The URL of the image set in the push notification.", "type": "string" }, "name": { "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.", "type": "string" }, "contents": { "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages).", "type": "object", "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "converted": { "type": "integer", "description": "The number of times the push was clicked." }, "data": { "type": "object", "description": "The JSON data set in the push notification if applicable." }, "delayed_option": { "type": "string", "description": "The per-user delay option set for the message." }, "delivery_time_of_day": { "type": "string", "description": "The delivery time of day set for the message if `delayed_option` is `timezone`." }, "remaining": { "type": "integer", "description": "The number of messages that have not been sent yet. If `null`, then the system is still processing the audience, try again later." }, "errored": { "type": "integer", "description": "The number of times the message errored." }, "excluded_segments": { "type": "array", "description": "The segments excluded from the message if applicable." }, "failed": { "type": "integer", "description": "The number of subscriptions reported unsubscribed for the message." }, "global_image": { "type": "string", "description": "The URL of the image set in the push notification." }, "headings": { "type": "object", "description": "The title of the push notification." }, "id": { "type": "string", "description": "The identifier of the message in UUID v4 format." }, "included_segments": { "type": "array", "description": "The segments included in the message if applicable." }, "ios_badgeCount": { "type": "integer", "description": "The badge count set for the message if applicable." }, "ios_badgeType": { "type": "string", "description": "The badge type set for the message if applicable." }, "queued_at": { "type": "integer", "description": "Unix timestamp of when the message was created." }, "send_after": { "type": "integer", "description": "Unix timestamp of when the message delivery was scheduled to begin." }, "completed_at": { "type": "integer", "description": "Unix timestamp of when the message delivery was completed. The delivery duration from start to finish can be calculated with `completed_at - send_after`. " }, "successful": { "type": "integer", "description": "The number of messages successfully delivered to the push, email, or SMS servers." }, "received": { "type": "integer", "description": "The number of messages that confirmed being received aka [Confirmed Deliveries](/docs/confirmed-delivery)." }, "filters": { "type": "object", "description": "The filters set for the message if applicable." }, "template_id": { "type": "string", "description": "The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates)." }, "url": { "type": "string", "description": "The URL of the push notification." }, "web_url": { "type": "string", "description": "The URL of the push notification for web push subscriptions." }, "app_url": { "type": "string", "description": "The URL of the push notification for mobile subscriptions." }, "platform_delivery_stats": { "type": "object", "description": "The successful, errored, failed, converted, received and frequency cap counts for each platform applicable." }, "throttle_rate_per_minute": { "type": "number", "description": "The throttle rate of the push notification if applicable." }, "fcap_status": { "type": "string", "description": "The frequency cap status of the push notification if applicable." }, "outcomes": { "type": "object", "description": "The id, value, and aggregation type of the outcome set in the request." } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "delete": { "summary": "Cancel message", "description": "Stop a scheduled or currently outgoing message.", "operationId": "cancel-message", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst notificationId: string = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n\ntry {\n const response = await apiInstance.cancelNotification(appId, notificationId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"cancelNotification failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n notification_id = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" \n\n try:\n # Stop a scheduled or currently outgoing notification\n api_response = api_instance.cancel_notification(app_id, notification_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->cancel_notification: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string\n\ntry {\n $result = $apiInstance->cancelNotification($app_id, $notification_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->cancelNotification: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->cancelNotification: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n notificationId := \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CancelNotification(restAuth, notificationId).AppId(appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CancelNotification``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CancelNotification`: GenericSuccessBoolResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CancelNotification`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \nnotification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | \n\nbegin\n # Stop a scheduled or currently outgoing notification\n result = api_instance.cancel_notification(app_id, notification_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->cancel_notification: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // String | \n try {\n GenericSuccessBoolResponse result = apiInstance.cancelNotification(appId, notificationId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#cancelNotification\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CancelNotificationExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var notificationId = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\"; // string | \n\n try\n {\n // Stop a scheduled or currently outgoing notification\n GenericSuccessBoolResponse result = apiInstance.CancelNotification(appId, notificationId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CancelNotification: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let notification_id: &str = \"b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88\";\n\n match default_api::cancel_notification(&configuration, app_id, notification_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"cancel_notification failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"cancel_notification failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "message_id", "in": "path", "description": "The identifier of the message in UUID v4 format. Get this `id` in the response of your Create Message API request, the [View Messages API](/reference/view-messages), and in your OneSignal dashboard Message Reports.", "schema": { "type": "string" }, "required": true }, { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the message was successfully canceled." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Reason for the message not being canceled. Usually due to the message already being sent to all recipients." ] } } } }, "404": { "description": "The notification was not found, or it is older than the retention window and its audience activity has been purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Notification not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/activities/activity/{activity_type}": { "post": { "summary": "Start Live Activity", "description": "Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.", "operationId": "start-live-activity", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | Your OneSignal App ID in UUID v4 format.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string | The name of the Live Activity defined in your app. This should match the attributes struct used in your app\\'s Live Activity implementation.\nconst activityType: string = \"order_status\";\n// StartLiveActivityRequest\nconst startLiveActivityRequest: Onesignal.StartLiveActivityRequest = {\n name: \"name_example\",\n event: \"start\",\n activity_id: \"activity_id_example\",\n event_attributes: {},\n event_updates: {},\n contents: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n headings: {\n en: \"en_example\",\n ar: \"ar_example\",\n bs: \"bs_example\",\n bg: \"bg_example\",\n ca: \"ca_example\",\n zh_hans: \"zh_hans_example\",\n zh_hant: \"zh_hant_example\",\n zh: \"zh_example\",\n hr: \"hr_example\",\n cs: \"cs_example\",\n da: \"da_example\",\n nl: \"nl_example\",\n et: \"et_example\",\n fi: \"fi_example\",\n fr: \"fr_example\",\n ka: \"ka_example\",\n de: \"de_example\",\n el: \"el_example\",\n hi: \"hi_example\",\n he: \"he_example\",\n hu: \"hu_example\",\n id: \"id_example\",\n it: \"it_example\",\n ja: \"ja_example\",\n ko: \"ko_example\",\n lv: \"lv_example\",\n lt: \"lt_example\",\n ms: \"ms_example\",\n nb: \"nb_example\",\n pl: \"pl_example\",\n fa: \"fa_example\",\n pt: \"pt_example\",\n pa: \"pa_example\",\n ro: \"ro_example\",\n ru: \"ru_example\",\n sr: \"sr_example\",\n sk: \"sk_example\",\n es: \"es_example\",\n sv: \"sv_example\",\n th: \"th_example\",\n tr: \"tr_example\",\n uk: \"uk_example\",\n vi: \"vi_example\",\n },\n stale_date: 1,\n priority: 1,\n ios_relevance_score: 3.14,\n idempotency_key: \"idempotency_key_example\",\n include_aliases: {\n \"key\": [\n \"key_example\",\n ],\n },\n include_subscription_ids: [\n \"include_subscription_ids_example\",\n ],\n included_segments: [\n \"included_segments_example\",\n ],\n excluded_segments: [\n \"excluded_segments_example\",\n ],\n filters: [\n {\n field: \"field_example\",\n key: \"key_example\",\n value: \"value_example\",\n hours_ago: \"hours_ago_example\",\n radius: 3.14,\n lat: 3.14,\n long: 3.14,\n relation: \">\",\n },\n ],\n };\n\ntry {\n const response = await apiInstance.startLiveActivity(appId, activityType, startLiveActivityRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"startLiveActivity failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # Your OneSignal App ID in UUID v4 format. \n activity_type = \"order_status\" # The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation. \n start_live_activity_request = StartLiveActivityRequest(\n name=\"name_example\",\n event=\"start\",\n activity_id=\"activity_id_example\",\n event_attributes={},\n event_updates={},\n contents=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n headings=LanguageStringMap(\n en=\"en_example\",\n ar=\"ar_example\",\n bs=\"bs_example\",\n bg=\"bg_example\",\n ca=\"ca_example\",\n zh_hans=\"zh_hans_example\",\n zh_hant=\"zh_hant_example\",\n zh=\"zh_example\",\n hr=\"hr_example\",\n cs=\"cs_example\",\n da=\"da_example\",\n nl=\"nl_example\",\n et=\"et_example\",\n fi=\"fi_example\",\n fr=\"fr_example\",\n ka=\"ka_example\",\n de=\"de_example\",\n el=\"el_example\",\n hi=\"hi_example\",\n he=\"he_example\",\n hu=\"hu_example\",\n id=\"id_example\",\n it=\"it_example\",\n ja=\"ja_example\",\n ko=\"ko_example\",\n lv=\"lv_example\",\n lt=\"lt_example\",\n ms=\"ms_example\",\n nb=\"nb_example\",\n pl=\"pl_example\",\n fa=\"fa_example\",\n pt=\"pt_example\",\n pa=\"pa_example\",\n ro=\"ro_example\",\n ru=\"ru_example\",\n sr=\"sr_example\",\n sk=\"sk_example\",\n es=\"es_example\",\n sv=\"sv_example\",\n th=\"th_example\",\n tr=\"tr_example\",\n uk=\"uk_example\",\n vi=\"vi_example\",\n ),\n stale_date=1,\n priority=1,\n ios_relevance_score=3.14,\n idempotency_key=\"idempotency_key_example\",\n include_aliases=IncludeAliases(\n key=[\n \"key_example\",\n ],\n ),\n include_subscription_ids=[\n \"include_subscription_ids_example\",\n ],\n included_segments=[\n \"included_segments_example\",\n ],\n excluded_segments=[\n \"excluded_segments_example\",\n ],\n filters=[\n Filter(\n field=\"field_example\",\n key=\"key_example\",\n value=\"value_example\",\n hours_ago=\"hours_ago_example\",\n radius=3.14,\n lat=3.14,\n long=3.14,\n relation=\">\",\n ),\n ],\n ) \n\n try:\n # Start Live Activity\n api_response = api_instance.start_live_activity(app_id, activity_type, start_live_activity_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->start_live_activity: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | Your OneSignal App ID in UUID v4 format.\n$activity_type = 'order_status'; // string | The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.\n$start_live_activity_request = new \\onesignal\\client\\model\\StartLiveActivityRequest(); // \\onesignal\\client\\model\\StartLiveActivityRequest\n\ntry {\n $result = $apiInstance->startLiveActivity($app_id, $activity_type, $start_live_activity_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->startLiveActivity: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->startLiveActivity: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | Your OneSignal App ID in UUID v4 format.\n activityType := \"order_status\" // string | The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.\n startLiveActivityRequest := *onesignal.NewStartLiveActivityRequest(\"Name_example\", \"Event_example\", \"ActivityId_example\", map[string]interface{}{\"key\": \"value\"}, map[string]interface{}{\"key\": \"value\"}, *onesignal.NewLanguageStringMap(), *onesignal.NewLanguageStringMap()) // StartLiveActivityRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.StartLiveActivity(restAuth, appId, activityType).StartLiveActivityRequest(startLiveActivityRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.StartLiveActivity``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `StartLiveActivity`: StartLiveActivitySuccessResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.StartLiveActivity`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | Your OneSignal App ID in UUID v4 format.\nactivity_type = 'order_status' # String | The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.\nstart_live_activity_request = OneSignal::StartLiveActivityRequest.new({name: 'name_example', event: 'start', activity_id: 'activity_id_example', event_attributes: 3.56, event_updates: 3.56, contents: OneSignal::LanguageStringMap.new, headings: OneSignal::LanguageStringMap.new}) # StartLiveActivityRequest | \n\nbegin\n # Start Live Activity\n result = api_instance.start_live_activity(app_id, activity_type, start_live_activity_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->start_live_activity: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | Your OneSignal App ID in UUID v4 format.\n String activityType = \"order_status\"; // String | The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.\n StartLiveActivityRequest startLiveActivityRequest = new StartLiveActivityRequest(); // StartLiveActivityRequest | \n try {\n StartLiveActivitySuccessResponse result = apiInstance.startLiveActivity(appId, activityType, startLiveActivityRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#startLiveActivity\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class StartLiveActivityExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | Your OneSignal App ID in UUID v4 format.\n var activityType = \"order_status\"; // string | The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.\n var startLiveActivityRequest = new StartLiveActivityRequest(); // StartLiveActivityRequest | \n\n try\n {\n // Start Live Activity\n StartLiveActivitySuccessResponse result = apiInstance.StartLiveActivity(appId, activityType, startLiveActivityRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.StartLiveActivity: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let activity_type: &str = \"order_status\";\n let start_live_activity_request: models::StartLiveActivityRequest = todo!();\n\n match default_api::start_live_activity(&configuration, app_id, activity_type, start_live_activity_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"start_live_activity failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"start_live_activity failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "activity_type", "in": "path", "description": "The name of the Live Activity defined in your app. This should match the `your-nameAttributes` struct used in your app code. See [Live Activities developer setup](/docs/live-activities-developer-setup). Example: If your app defines a Live Activity as `OneSignalWidgetAttributes`, then `activity_type` should be `OneSignalWidgetAttributes`.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "activity_id", "name", "event_attributes", "event_updates", "contents", "headings" ], "properties": { "include_aliases": { "type": "object", "description": "Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).", "format": "json", "properties": { "external_id": { "description": "An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).", "type": "array", "items": { "type": "string" } } } }, "include_subscription_ids": { "type": "array", "description": "Target users' specific [subscriptions](/docs/subscriptions) by ID. Include up to 20,000 `subscription_id` per API call. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "included_segments": { "type": "array", "description": "Target predefined [Segments](/docs/segmentation). Users that are in multiple segments will only be sent the message once. Can be combined with `excluded_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "excluded_segments": { "type": "array", "description": "Exclude users in predefined [Segments](/docs/segmentation). Overrides membership in any segment specified in the `included_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).", "items": { "type": "string" } }, "filters": { "type": "array", "description": "Dynamically target users based on properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. Not compatible with other targeting parameters like `include_aliases`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#filters).", "items": { "properties": { "field": { "type": "string", "description": "The name of the filter to use.", "default": "first_session" }, "key": { "type": "string", "description": "Used with the `tag` filter. This is the tag `key`." }, "relation": { "type": "string", "description": "Used with most filters. Usually this value is `\">\"`, `\"<\"`, `\"=\"`. See the specific filter.", "default": ">" }, "value": { "type": "string", "description": "The value of the `field` or tag `key` in which you want to filter with.", "default": "1" } }, "required": [ "field", "relation", "value" ], "type": "object" } }, "event": { "type": "string", "description": "The action to perform on the Live Activity. This request only supports `start`.", "enum": [ "start" ], "default": "start" }, "activity_id": { "type": "string", "description": "An identifier you set when starting the Live Activity to uniquely identify it and associated devices with the event. Save this value because it is required for the [Update Live Activity](/reference/update-live-activity) API. Consider using a UUID, CUID, or NanoID for this parameter." }, "event_attributes": { "type": "object", "description": "The static data to initialize the Live Activity. See [Live Activities developer setup](/docs/live-activities-developer-setup).", "format": "json" }, "event_updates": { "type": "object", "description": "The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/live-activities-developer-setup).", "format": "json" }, "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters." }, "contents": { "type": "object", "description": "The push message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "headings": { "type": "object", "description": "The push title with [language-specific values](/docs/en/multi-language-messaging#supported-languages).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The title in English. Must include the same languages as `contents`." } } }, "stale_date": { "type": "integer", "description": "A Unix timestamp (in seconds) that indicates the date the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to [`ActivityState.stale`](https://developer.apple.com/documentation/activitykit/activitystate/stale) at which point you can update the Live Activity to indicate that its content is out of date.", "format": "int32" }, "priority": { "type": "integer", "description": "Set the priority based on the urgency of the message. `10` - High priority. `5` - Normal priority. Apple allows a certain budget of High priority updates per hour. Exceeding the budget may throttle your messages. Apple recommends choosing a mix of priority `5` and `10` to prevent throttling. If your app needs more frequent updates, use `NSSupportsLiveActivitiesFrequentUpdates` entry as directed in [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).", "format": "int32", "enum": [ 5, 10 ] }, "ios_sound": { "type": "string", "description": "The name of a sound file in your app bundle to play when the Live Activity receives an update. If excluded, the system plays the default notification sound. Using the value `\"nil\"` will silence the sound." }, "ios_relevance_score": { "type": "number", "description": "A value between `0` and `1`. If you start more than one Live Activity for your app, the Live Activity with the highest relevance score appears in the Dynamic Island. If Live Activities have the same relevance score, the system displays the Live Activity that started first. Additionally, the Relevance Score determines the order of your Live Activities on the Lock Screen.", "format": "double" }, "idempotency_key": { "type": "string", "description": "A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`." } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "notification_id": { "type": "string", "description": "The ID of the Live Activity that was created in UUID v4 format." } } } } }, "headers": { "Idempotent-Replayed": { "description": "Present and set to `true` when this response is a replay of a previous successful request that used the same `idempotency_key`. Absent on fresh executions. Use this to distinguish \"new send\" from \"deduplicated retry\" without inspecting the body.", "schema": { "type": "boolean", "enum": [ true ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Reason for the message not being started. Usually due to the activity type not being found in the app." ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/templates/{template_id}/copy_to_app?app_id={app_id}": { "post": { "summary": "Copy template to another app", "description": "Create a duplicate of a OneSignal message template in another app within the same organization. The new template will retain the same content but have a unique template ID.", "operationId": "copy-template-to-another-app", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst templateId: string = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// CopyTemplateRequest\nconst copyTemplateRequest: Onesignal.CopyTemplateRequest = {\n target_app_id: \"target_app_id_example\",\n };\n\ntry {\n const response = await apiInstance.copyTemplateToApp(templateId, appId, copyTemplateRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"copyTemplateToApp failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n template_id = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" \n app_id = \"00000000-0000-0000-0000-000000000000\" \n copy_template_request = CopyTemplateRequest(\n target_app_id=\"target_app_id_example\",\n ) \n\n try:\n # Copy template to another app\n api_response = api_instance.copy_template_to_app(template_id, app_id, copy_template_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->copy_template_to_app: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$template_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c'; // string\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$copy_template_request = new \\onesignal\\client\\model\\CopyTemplateRequest(); // \\onesignal\\client\\model\\CopyTemplateRequest\n\ntry {\n $result = $apiInstance->copyTemplateToApp($template_id, $app_id, $copy_template_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->copyTemplateToApp: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->copyTemplateToApp: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n templateId := \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\" // string | \n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n copyTemplateRequest := *onesignal.NewCopyTemplateRequest(\"TargetAppId_example\") // CopyTemplateRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.CopyTemplateToApp(orgAuth, templateId).AppId(appId).CopyTemplateRequest(copyTemplateRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CopyTemplateToApp``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CopyTemplateToApp`: TemplateResource\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CopyTemplateToApp`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\ntemplate_id = 'e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c' # String | \napp_id = '00000000-0000-0000-0000-000000000000' # String | \ncopy_template_request = OneSignal::CopyTemplateRequest.new({target_app_id: 'target_app_id_example'}) # CopyTemplateRequest | \n\nbegin\n # Copy template to another app\n result = api_instance.copy_template_to_app(template_id, app_id, copy_template_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->copy_template_to_app: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // String | \n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n CopyTemplateRequest copyTemplateRequest = new CopyTemplateRequest(); // CopyTemplateRequest | \n try {\n TemplateResource result = apiInstance.copyTemplateToApp(templateId, appId, copyTemplateRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#copyTemplateToApp\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CopyTemplateToAppExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var templateId = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\"; // string | \n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var copyTemplateRequest = new CopyTemplateRequest(); // CopyTemplateRequest | \n\n try\n {\n // Copy template to another app\n TemplateResource result = apiInstance.CopyTemplateToApp(templateId, appId, copyTemplateRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CopyTemplateToApp: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let template_id: &str = \"e4d3c2b1-a09f-4f1e-8d7c-6b5a4f3e2d1c\";\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let copy_template_request: models::CopyTemplateRequest = todo!();\n\n match default_api::copy_template_to_app(&configuration, template_id, app_id, copy_template_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"copy_template_to_app failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"copy_template_to_app failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "template_id", "in": "path", "description": "The template ID in UUID v4 format. See [Templates](/docs/en/templates).", "schema": { "type": "string", "default": "YOUR_TEMPLATE_ID" }, "required": true }, { "name": "app_id", "in": "query", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "target_app_id" ], "properties": { "target_app_id": { "type": "string", "description": "Specifies the OneSignal app ID that the template will be copied to. Cannot be the same as the `app_id`.", "default": "YOUR_OTHER_APP_ID" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the template was copied successfully." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad Request (Missing Body Parameter)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "description": "Missing body parameter.Request is malformed: Failed to parse app_id from request" } } } }, { "title": "Bad Request (Missing Query Parameter)", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "description": "Missing query parameter. app_id not found. You may be missing a Content-Type: application/json header." } } } } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the template was copied successfully." } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/inbox": { "post": { "summary": "Create inbox broadcast message", "description": "Broadcast a message to users' inboxes.", "operationId": "create-inbox-broadcast-message", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "subjects" ], "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters. Required, and must be non-empty." }, "img_url": { "type": "string", "description": "The URL to an image that is associated with this message." }, "contents": { "type": "object", "description": "The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization).", "required": [ "en" ], "properties": { "en": { "type": "string", "description": "The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages)." } } }, "subjects": { "type": "object", "description": "The message's localized subjects, as a map of language codes to subjects. Each entry must have a language code as its key, mapped to the localized subject you would like users to receive for that language. Any language codes used must also be used within the contents property. This field supports tag substitutions and liquid syntax. Required, and must be non-empty. Example: `{\"en\": \"English Title\", \"es\": \"Spanish Title\"}`", "properties": { "en": { "type": "string", "default": "English Message" } } }, "send_after": { "type": "string", "description": "Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`" }, "data": { "type": "string", "description": "An arbitrary string (which can contain encoded JSON if desired) that is passed through to messages. This is meant for use in client applications and is not processed in any special way by OneSignal. If you need structured data, encode it as a JSON string. Example: `\"{\\\"abc\\\":\\\"123\\\"}\"`", "default": "{\"abc\":\"123\"}" }, "custom_data": { "type": "object", "description": "Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email).", "properties": { "key": { "type": "string", "description": "JSON object that can be used as a source of message personalization data for fields that support tag variable substitution. Initially can accept up to 2,048 bytes of valid JSON. Example: {\"order_id\": 123, \"currency\": \"USD\", \"amount\": 25}. See [Message Personalization](/docs/message-personalization)", "default": "value to be substituted" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The message ID in UUID v4 format." } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/inbox?last_broadcast_id={broadcast_id}&limit={number}": { "get": { "summary": "View broadcasts", "description": "Lists all inbox broadcasts sent to an audience.", "operationId": "view-broadcasts", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "last_broadcast_id", "in": "query", "description": "The exclusive lower bound of broadcasts to retrieve", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of broadcasts to retrieve.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "broadcasts_and_stats": [ { "broadcast": { "id": "uuid", "notification_id": "uuid", "name": "", "img_url": "", "included_segment_ids": [], "excluded_segment_ids": [], "included_aliases": {}, "filters": [], "include_unsubscribed": false, "send_after": "", "delayed_option": "", "delivery_time_of_day": "", "contents": {}, "subjects": {}, "data": {}, "custom_data": {}, "ttl_sec": 80000 }, "stats": { "sent": 0, "opened": 0, "read": 0 } } ], "last_broadcast_id": "uuid" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Access denied. Please include an 'Authorization: ...' header with a valid API key (/docs/accounts-and-keys)." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox?last_message_id={message_id}": { "get": { "summary": "View user broadcasts", "description": "Lists all inbox broadcasts specifically sent to a unique user.", "operationId": "view-user-inbox-messages", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "last_message_id", "in": "query", "description": "The exclusive lower bound of broadcasts to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The identifier or value set for the desired alias label.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "messages": [ { "id": "uuid", "created_at": "", "is_read": false, "is_deleted": false, "is_opened": false, "subject": "Subject", "body": "Personalized message", "img_url": "body", "data": {}, "expires_on": "" } ], "last_message_id": "uuid" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "title": "Given alias `(external_id: )` doesn't match an existing user" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "patch": { "summary": "Bulk update or delete message state", "description": "Updates the read, opened, or deleted state of multiple inbox messages for a user in a single request.", "operationId": "bulk-update-or-delete-message-state", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The identifier or value set for the desired alias label.", "schema": { "type": "string" }, "required": true }, { "name": "last_message_id", "in": "query", "description": "Scopes the update to this message and every message older than it. If omitted, the update applies to every message in the user's inbox.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_read": { "type": "boolean", "description": "Indicates whether to mark the matched messages as read." }, "is_deleted": { "type": "boolean", "description": "Indicates whether to mark the matched messages as deleted. Deleted messages no longer appear in View user broadcasts results." }, "is_opened": { "type": "boolean", "description": "Indicates whether to mark the matched messages as opened." } } } } } }, "responses": { "204": { "description": "204 No Content. The message state was updated successfully." }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Access denied. Please include an 'Authorization: ...' header with a valid API key (/docs/accounts-and-keys)." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox/unread_count": { "get": { "summary": "View user unread message count", "description": "Returns the number of unread messages in a user's inbox.", "operationId": "view-user-unread-message-count", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The identifier or value set for the desired alias label.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "count": 0 } } }, "schema": { "type": "object", "properties": { "count": { "type": "integer", "example": 0, "default": 0 } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "title": "Given alias `(external_id: )` doesn't match an existing user" } ] } } }, "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/users/by/{alias_label}/{alias_id}/inbox/{message_id}": { "patch": { "summary": "Update message state", "description": "Updates the read, opened, or deleted state of a single inbox message.", "operationId": "update-message-state", "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } }, { "name": "alias_label", "in": "path", "description": "The alias name or key to locate the user. Most commonly set as `external_id` but can be the `onesignal_id` or a [custom alias](/docs/aliases).", "schema": { "type": "string" }, "required": true }, { "name": "alias_id", "in": "path", "description": "The identifier or value set for the desired alias label.", "schema": { "type": "string" }, "required": true }, { "name": "message_id", "in": "path", "description": "The identifier of the message in UUID v4 format.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_read": { "type": "boolean", "description": "Indicates whether to mark the message as read." }, "is_deleted": { "type": "boolean", "description": "Indicates whether to mark the message as deleted. A deleted message no longer appears in View user broadcasts results." }, "is_opened": { "type": "boolean", "description": "Indicates whether to mark the message as opened." } } } } } }, "responses": { "204": { "description": "204 No Content. The message state was updated successfully." }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ "Access denied. Please include an 'Authorization: ...' header with a valid API key (/docs/accounts-and-keys)." ] } } }, "schema": { "$ref": "#/components/schemas/BasicErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredErrorResponse" }, "example": { "errors": [ { "code": "Rate Limit Exceeded", "title": "API rate limit exceeded" } ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/auth/tokens": { "get": { "summary": "View API keys", "description": "View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.", "operationId": "view-api-keys", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n\ntry {\n const response = await apiInstance.viewApiKeys(appId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"viewApiKeys failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n\n try:\n # View API keys\n api_response = api_instance.view_api_keys(app_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->view_api_keys: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n\ntry {\n $result = $apiInstance->viewApiKeys($app_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->viewApiKeys: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->viewApiKeys: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.ViewApiKeys(orgAuth, appId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.ViewApiKeys``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `ViewApiKeys`: ApiKeyTokensListResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.ViewApiKeys`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \n\nbegin\n # View API keys\n result = api_instance.view_api_keys(app_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->view_api_keys: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n try {\n ApiKeyTokensListResponse result = apiInstance.viewApiKeys(appId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#viewApiKeys\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class ViewApiKeysExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n\n try\n {\n // View API keys\n ApiKeyTokensListResponse result = apiInstance.ViewApiKeys(appId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.ViewApiKeys: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n\n match default_api::view_api_keys(&configuration, app_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"view_api_keys failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"view_api_keys failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "responses": { "200": { "description": "List of API key tokens for this app. The `formatted_token` field is never populated in this response — the secret is only shown immediately after create or rotate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyToken" }, "description": "All API key tokens registered against this app (ordered by `created_at`)." } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "Forbidden. Your organization permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Current organization permissions do not allow this action." ] } } } }, "404": { "description": "App not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "App not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "post": { "summary": "Create API key", "description": "Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.", "operationId": "create-api-key", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// CreateApiKeyRequest\nconst createApiKeyRequest: Onesignal.CreateApiKeyRequest = {\n name: \"name_example\",\n ip_allowlist_mode: \"disabled\",\n ip_allowlist: [\n \"ip_allowlist_example\",\n ],\n };\n\ntry {\n const response = await apiInstance.createApiKey(appId, createApiKeyRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createApiKey failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n create_api_key_request = CreateApiKeyRequest(\n name=\"name_example\",\n ip_allowlist_mode=\"disabled\",\n ip_allowlist=[\n \"ip_allowlist_example\",\n ],\n ) \n\n try:\n # Create API key\n api_response = api_instance.create_api_key(app_id, create_api_key_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_api_key: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$create_api_key_request = new \\onesignal\\client\\model\\CreateApiKeyRequest(); // \\onesignal\\client\\model\\CreateApiKeyRequest\n\ntry {\n $result = $apiInstance->createApiKey($app_id, $create_api_key_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createApiKey: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createApiKey: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n createApiKeyRequest := *onesignal.NewCreateApiKeyRequest() // CreateApiKeyRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateApiKey(orgAuth, appId).CreateApiKeyRequest(createApiKeyRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateApiKey``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateApiKey`: CreateApiKeyResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateApiKey`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \ncreate_api_key_request = OneSignal::CreateApiKeyRequest.new # CreateApiKeyRequest | \n\nbegin\n # Create API key\n result = api_instance.create_api_key(app_id, create_api_key_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_api_key: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n CreateApiKeyRequest createApiKeyRequest = new CreateApiKeyRequest(); // CreateApiKeyRequest | \n try {\n CreateApiKeyResponse result = apiInstance.createApiKey(appId, createApiKeyRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createApiKey\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateApiKeyExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var createApiKeyRequest = new CreateApiKeyRequest(); // CreateApiKeyRequest | \n\n try\n {\n // Create API key\n CreateApiKeyResponse result = apiInstance.CreateApiKey(appId, createApiKeyRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateApiKey: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let create_api_key_request: models::CreateApiKeyRequest = todo!();\n\n match default_api::create_api_key(&configuration, app_id, create_api_key_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_api_key failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_api_key failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track API keys (Rich Authentication Tokens). Maximum 128 characters." }, "ip_allowlist_mode": { "type": "string", "description": "Defaults to `disabled`, can be set to `explicit`. If set to `explicit`, a list of network addresses in the form of CIDRs has to be specified in the `ip_allowlist` parameter.", "enum": [ "disabled", "explicit" ] }, "ip_allowlist": { "type": "array", "description": "An array of allowed networks in CIDRs notation. Only IPs in those ranges will be permitted to use the API key.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The newly-created API key token. `token_id` and `formatted_token` are populated; `formatted_token` is the secret and is returned ONCE — store it now or rotate later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyToken" } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "Forbidden. Your organization permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Current organization permissions do not allow this action." ] } } } }, "404": { "description": "App not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "App not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/auth/tokens/{token_id}": { "delete": { "summary": "Delete API key", "description": "Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.", "operationId": "delete-api-key", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst tokenId: string = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n\ntry {\n const response = await apiInstance.deleteApiKey(appId, tokenId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"deleteApiKey failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n token_id = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" \n\n try:\n # Delete API key\n api_response = api_instance.delete_api_key(app_id, token_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->delete_api_key: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$token_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff'; // string\n\ntry {\n $result = $apiInstance->deleteApiKey($app_id, $token_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->deleteApiKey: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->deleteApiKey: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n tokenId := \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.DeleteApiKey(orgAuth, appId, tokenId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.DeleteApiKey``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `DeleteApiKey`: map[string]interface{}\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.DeleteApiKey`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \ntoken_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff' # String | \n\nbegin\n # Delete API key\n result = api_instance.delete_api_key(app_id, token_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->delete_api_key: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // String | \n try {\n Object result = apiInstance.deleteApiKey(appId, tokenId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#deleteApiKey\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class DeleteApiKeyExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // string | \n\n try\n {\n // Delete API key\n Object result = apiInstance.DeleteApiKey(appId, tokenId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.DeleteApiKey: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let token_id: &str = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n\n match default_api::delete_api_key(&configuration, app_id, token_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"delete_api_key failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"delete_api_key failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } }, { "name": "token_id", "in": "path", "description": "The OneSignal-generated ID specific to the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Returns an empty object on success. The token has been revoked and can no longer be used.", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "additionalProperties": false, "example": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "Forbidden. Your organization permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Current organization permissions do not allow this action." ] } } } }, "404": { "description": "Token not found in this app, or the App ID was wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Token not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false }, "patch": { "summary": "Update API key", "description": "Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.", "operationId": "update-api-key", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst tokenId: string = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n// UpdateApiKeyRequest\nconst updateApiKeyRequest: Onesignal.UpdateApiKeyRequest = {\n name: \"name_example\",\n ip_allowlist_mode: \"disabled\",\n ip_allowlist: [\n \"ip_allowlist_example\",\n ],\n };\n\ntry {\n const response = await apiInstance.updateApiKey(appId, tokenId, updateApiKeyRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"updateApiKey failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n token_id = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" \n update_api_key_request = UpdateApiKeyRequest(\n name=\"name_example\",\n ip_allowlist_mode=\"disabled\",\n ip_allowlist=[\n \"ip_allowlist_example\",\n ],\n ) \n\n try:\n # Update API key\n api_response = api_instance.update_api_key(app_id, token_id, update_api_key_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->update_api_key: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$token_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff'; // string\n$update_api_key_request = new \\onesignal\\client\\model\\UpdateApiKeyRequest(); // \\onesignal\\client\\model\\UpdateApiKeyRequest\n\ntry {\n $result = $apiInstance->updateApiKey($app_id, $token_id, $update_api_key_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->updateApiKey: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->updateApiKey: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n tokenId := \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" // string | \n updateApiKeyRequest := *onesignal.NewUpdateApiKeyRequest() // UpdateApiKeyRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.UpdateApiKey(orgAuth, appId, tokenId).UpdateApiKeyRequest(updateApiKeyRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.UpdateApiKey``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `UpdateApiKey`: map[string]interface{}\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.UpdateApiKey`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \ntoken_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff' # String | \nupdate_api_key_request = OneSignal::UpdateApiKeyRequest.new # UpdateApiKeyRequest | \n\nbegin\n # Update API key\n result = api_instance.update_api_key(app_id, token_id, update_api_key_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->update_api_key: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // String | \n UpdateApiKeyRequest updateApiKeyRequest = new UpdateApiKeyRequest(); // UpdateApiKeyRequest | \n try {\n Object result = apiInstance.updateApiKey(appId, tokenId, updateApiKeyRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#updateApiKey\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class UpdateApiKeyExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // string | \n var updateApiKeyRequest = new UpdateApiKeyRequest(); // UpdateApiKeyRequest | \n\n try\n {\n // Update API key\n Object result = apiInstance.UpdateApiKey(appId, tokenId, updateApiKeyRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.UpdateApiKey: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let token_id: &str = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n let update_api_key_request: models::UpdateApiKeyRequest = todo!();\n\n match default_api::update_api_key(&configuration, app_id, token_id, update_api_key_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"update_api_key failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"update_api_key failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization's API key found in [Organizations > Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } }, { "name": "token_id", "in": "path", "description": "The OneSignal-generated ID specific to the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "An internal name you set to help organize and track API keys (Rich Authentication Tokens). Maximum 128 characters." }, "ip_allowlist_mode": { "type": "string", "description": "Defaults to `disabled`, can be set to `explicit`. If set to `explicit`, a list of network addresses in the form of CIDRs has to be specified in the `ip_allowlist` parameter.", "enum": [ "disabled", "explicit" ] }, "ip_allowlist": { "type": "array", "description": "An array of allowed networks in CIDRs notation. Only IPs in those ranges will be permitted to use the API key.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Returns an empty object on success. Issue a follow-up GET to read the updated values.", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "additionalProperties": false, "example": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "Forbidden. Your organization permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Current organization permissions do not allow this action." ] } } } }, "404": { "description": "Token not found in this app, or the App ID was wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Token not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/auth/tokens/{token_id}/rotate": { "post": { "summary": "Rotate API key", "description": "Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.", "operationId": "rotate-api-key", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// string\nconst tokenId: string = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n\ntry {\n const response = await apiInstance.rotateApiKey(appId, tokenId);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"rotateApiKey failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" \n token_id = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" \n\n try:\n # Rotate API key\n api_response = api_instance.rotate_api_key(app_id, token_id)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->rotate_api_key: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string\n$token_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff'; // string\n\ntry {\n $result = $apiInstance->rotateApiKey($app_id, $token_id);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->rotateApiKey: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->rotateApiKey: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | \n tokenId := \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\" // string | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, \"YOUR_ORGANIZATION_API_KEY\") // Organization API key is only required for creating new apps and other top-level endpoints\n\n resp, r, err := apiClient.DefaultApi.RotateApiKey(orgAuth, appId, tokenId).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.RotateApiKey``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `RotateApiKey`: CreateApiKeyResponse\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.RotateApiKey`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: organization_api_key\n config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | \ntoken_id = '0aa1b2c3-d4e5-46f7-8899-aabbccddeeff' # String | \n\nbegin\n # Rotate API key\n result = api_instance.rotate_api_key(app_id, token_id)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->rotate_api_key: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: organization_api_key\n HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"organization_api_key\");\n organization_api_key.setBearerToken(\"YOUR_ORGANIZATION_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | \n String tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // String | \n try {\n CreateApiKeyResponse result = apiInstance.rotateApiKey(appId, tokenId);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#rotateApiKey\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class RotateApiKeyExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: organization_api_key\n config.AccessToken = \"YOUR_ORGANIZATION_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | \n var tokenId = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\"; // string | \n\n try\n {\n // Rotate API key\n CreateApiKeyResponse result = apiInstance.RotateApiKey(appId, tokenId);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.RotateApiKey: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.organization_api_key_token = Some(\"YOUR_ORGANIZATION_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let token_id: &str = \"0aa1b2c3-d4e5-46f7-8899-aabbccddeeff\";\n\n match default_api::rotate_api_key(&configuration, app_id, token_id).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"rotate_api_key failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"rotate_api_key failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "YOUR_APP_ID" }, "required": true }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } }, { "name": "token_id", "in": "path", "description": "The OneSignal-generated ID specific to the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The rotated key's new secret. Only `formatted_token` is populated; everything else stays the same as before the rotate. Update your integration with the new secret immediately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyToken" } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "403": { "description": "Forbidden. Your organization permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Current organization permissions do not allow this action." ] } } } }, "404": { "description": "Token not found in this app, or the App ID was wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Token not found" ] } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/apps/{app_id}/custom_events": { "post": { "summary": "Create Custom Events", "description": "The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.", "operationId": "create-custom-events", "x-codeSamples": [ { "lang": "typescript", "label": "Node.js SDK", "source": "import Onesignal from '@onesignal/node-onesignal';\n\nconst configuration = Onesignal.createConfiguration({\n restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\n// string | Your OneSignal App ID in UUID v4 format.\nconst appId: string = \"00000000-0000-0000-0000-000000000000\";\n// CustomEventsRequest\nconst customEventsRequest: Onesignal.CustomEventsRequest = {\n events: [\n {\n name: \"name_example\",\n external_id: \"external_id_example\",\n onesignal_id: \"onesignal_id_example\",\n timestamp: '1970-01-01T00:00:00.00Z',\n payload: {},\n },\n ],\n };\n\ntry {\n const response = await apiInstance.createCustomEvents(appId, customEventsRequest);\n console.log(response);\n} catch (e) {\n if (e instanceof Onesignal.ApiException) {\n // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n // the raw parsed body remains on `e.body`.\n console.error(\"createCustomEvents failed: HTTP \" + e.code, e.errorMessages);\n } else {\n throw e;\n }\n}" }, { "lang": "python", "label": "Python SDK", "source": "import onesignal\nfrom onesignal.api import default_api\nfrom onesignal.models import *\nfrom dateutil.parser import parse as dateutil_parser\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\n# Enter a context with an instance of the API client\nwith onesignal.ApiClient(configuration) as api_client:\n # Create an instance of the API class\n api_instance = default_api.DefaultApi(api_client)\n app_id = \"00000000-0000-0000-0000-000000000000\" # Your OneSignal App ID in UUID v4 format. \n custom_events_request = CustomEventsRequest(\n events=[\n CustomEvent(\n name=\"name_example\",\n external_id=\"external_id_example\",\n onesignal_id=\"onesignal_id_example\",\n timestamp=dateutil_parser('1970-01-01T00:00:00.00Z'),\n payload={},\n ),\n ],\n ) \n\n try:\n # Create custom events\n api_response = api_instance.create_custom_events(app_id, custom_events_request)\n pprint(api_response)\n except onesignal.ApiException as e:\n print(\"Exception when calling DefaultApi->create_custom_events: %s\\n\" % e)\n print(\"Status Code: %s\" % e.status)\n print(\"Response Body: %s\" % e.body)" }, { "lang": "php", "label": "PHP SDK", "source": "setRestApiKeyToken('YOUR_REST_API_KEY')\n ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.\n // This is optional, `GuzzleHttp\\Client` will be used as default.\n new GuzzleHttp\\Client(),\n $config\n);\n$app_id = '00000000-0000-0000-0000-000000000000'; // string | Your OneSignal App ID in UUID v4 format.\n$custom_events_request = new \\onesignal\\client\\model\\CustomEventsRequest(); // \\onesignal\\client\\model\\CustomEventsRequest\n\ntry {\n $result = $apiInstance->createCustomEvents($app_id, $custom_events_request);\n print_r($result);\n} catch (\\onesignal\\client\\ApiException $e) {\n echo 'Exception when calling DefaultApi->createCustomEvents: ', $e->getMessage(), PHP_EOL;\n echo 'Status Code: ', $e->getCode(), PHP_EOL;\n // getErrorMessages() flattens any error-envelope shape to a string[];\n // the raw body remains on getResponseBody().\n echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;\n echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n echo 'Exception when calling DefaultApi->createCustomEvents: ', $e->getMessage(), PHP_EOL;\n}" }, { "lang": "go", "label": "Go SDK", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n appId := \"00000000-0000-0000-0000-000000000000\" // string | Your OneSignal App ID in UUID v4 format.\n customEventsRequest := *onesignal.NewCustomEventsRequest([]onesignal.CustomEvent{*onesignal.NewCustomEvent(\"Name_example\")}) // CustomEventsRequest | \n\n configuration := onesignal.NewConfiguration()\n apiClient := onesignal.NewAPIClient(configuration)\n\n restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\") // App REST API key required for most endpoints\n\n resp, r, err := apiClient.DefaultApi.CreateCustomEvents(restAuth, appId).CustomEventsRequest(customEventsRequest).Execute()\n\n if err != nil {\n fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateCustomEvents``: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n // ErrorMessages() flattens any error-envelope shape to a []string;\n // the raw body remains on Body().\n fmt.Fprintf(os.Stderr, \"Error Messages: %v\\n\", apiErr.ErrorMessages())\n fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n }\n }\n // response from `CreateCustomEvents`: map[string]interface{}\n fmt.Fprintf(os.Stdout, \"Response from `DefaultApi.CreateCustomEvents`: %v\\n\", resp)\n}" }, { "lang": "ruby", "label": "Ruby SDK", "source": "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n # Configure Bearer authorization: rest_api_key\n config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\napp_id = '00000000-0000-0000-0000-000000000000' # String | Your OneSignal App ID in UUID v4 format.\ncustom_events_request = OneSignal::CustomEventsRequest.new({events: [OneSignal::CustomEvent.new({name: 'name_example'})]}) # CustomEventsRequest | \n\nbegin\n # Create custom events\n result = api_instance.create_custom_events(app_id, custom_events_request)\n p result\nrescue OneSignal::ApiError => e\n puts \"Error when calling DefaultApi->create_custom_events: #{e}\"\n puts \"Status Code: #{e.code}\"\n # `e.error_messages` flattens any error-envelope shape to an Array;\n # the raw body remains on `e.response_body`.\n puts \"Error Messages: #{e.error_messages}\"\n puts \"Response Body: #{e.response_body}\"\nend" }, { "lang": "java", "label": "Java SDK", "source": "// Import classes:\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n public static void main(String[] args) {\n ApiClient defaultClient = Configuration.getDefaultApiClient();\n defaultClient.setBasePath(\"https://api.onesignal.com\");\n \n // Configure HTTP bearer authorization: rest_api_key\n HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n DefaultApi apiInstance = new DefaultApi(defaultClient);\n String appId = \"00000000-0000-0000-0000-000000000000\"; // String | Your OneSignal App ID in UUID v4 format.\n CustomEventsRequest customEventsRequest = new CustomEventsRequest(); // CustomEventsRequest | \n try {\n Object result = apiInstance.createCustomEvents(appId, customEventsRequest);\n System.out.println(result);\n } catch (ApiException e) {\n System.err.println(\"Exception when calling DefaultApi#createCustomEvents\");\n System.err.println(\"Status code: \" + e.getCode());\n // getErrorMessages() flattens any error-envelope shape to a List;\n // the raw body remains on getResponseBody().\n System.err.println(\"Error messages: \" + e.getErrorMessages());\n System.err.println(\"Reason: \" + e.getResponseBody());\n System.err.println(\"Response headers: \" + e.getResponseHeaders());\n e.printStackTrace();\n }\n }\n}" }, { "lang": "csharp", "label": "C# SDK", "source": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n public class CreateCustomEventsExample\n {\n public static void Main()\n {\n Configuration config = new Configuration();\n config.BasePath = \"https://api.onesignal.com\";\n // Configure Bearer token for authorization: rest_api_key\n config.AccessToken = \"YOUR_REST_API_KEY\";\n\n var apiInstance = new DefaultApi(config);\n var appId = \"00000000-0000-0000-0000-000000000000\"; // string | Your OneSignal App ID in UUID v4 format.\n var customEventsRequest = new CustomEventsRequest(); // CustomEventsRequest | \n\n try\n {\n // Create custom events\n Object result = apiInstance.CreateCustomEvents(appId, customEventsRequest);\n Debug.WriteLine(result);\n }\n catch (ApiException e)\n {\n Debug.Print(\"Exception when calling DefaultApi.CreateCustomEvents: \" + e.Message );\n Debug.Print(\"Status Code: \"+ e.ErrorCode);\n // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;\n // the raw body remains on e.ErrorContent.\n Debug.Print(\"Error Messages: \" + string.Join(\", \", e.ErrorMessages));\n Debug.Print(\"Response Body: \" + e.ErrorContent);\n Debug.Print(e.StackTrace);\n }\n }\n }\n}" }, { "lang": "rust", "label": "Rust SDK", "source": "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\n\nuse onesignal_rust_api::models;\n\n\n#[tokio::main]\nasync fn main() {\n let mut configuration = Configuration::new();\n configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n\n // Realistic values are pulled from the spec's `example:` fields where present.\n let app_id: &str = \"00000000-0000-0000-0000-000000000000\";\n let custom_events_request: models::CustomEventsRequest = todo!();\n\n match default_api::create_custom_events(&configuration, app_id, custom_events_request).await {\n Ok(resp) => println!(\"{:?}\", resp),\n Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {\n // `e.error_messages()` flattens any error-envelope shape to a Vec;\n // the raw response remains on the ResponseError variant.\n eprintln!(\"create_custom_events failed: {:?}\", e.error_messages());\n }\n Err(e) => eprintln!(\"create_custom_events failed: {:?}\", e),\n }\n}" } ], "parameters": [ { "name": "app_id", "in": "path", "description": "Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "description": "Your app API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "schema": { "type": "string", "default": "Key YOUR_APP_API_KEY" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "description": "Array of event objects to be recorded. Maximum size for each event is `2024` bytes. Maximum size of request is `1` MB.", "items": { "properties": { "name": { "type": "string", "description": "The identifier or name of the event. Maximum 128 characters." }, "external_id": { "type": "string", "description": "The external ID of the user targeted for the event. Either the user's External ID or OneSignal ID is required." }, "onesignal_id": { "type": "string", "description": "The OneSignal ID of the user targeted for the event. Either the user's External ID or OneSignal ID is required." }, "timestamp": { "type": "string", "description": "Time the event occurred as an [ISO8601 formatted string](https://www.timestamp-converter.com/). Defaults to the current time if not provided. If the timestamp provided is in the future, it will be reset to the current time." }, "idempotency_key": { "type": "string", "description": "A unique UUID for avoiding duplicate custom event processing. Repeated events with the same idempotency_key will not be processed." }, "properties": { "type": "object", "description": "Properties or data related to the event, like {\"geography\": \"USA\"}" } }, "required": [ "name" ], "type": "object" } } } } } } }, "responses": { "202": { "description": "Accepted with optional partial-success details. The response body lists any individual events that could not be processed (typically because the supplied `event_user_id` does not resolve to a OneSignal user); other events in the same payload were processed normally. An empty `errors` array (or absent body) means every event was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "Errors for specific events in the payload. If this is returned, only the specified events have failed -- other events in the same payload were successfully processed.", "items": { "type": "object", "properties": { "event_user_id": { "type": "string", "description": "The External ID in the event that failed.", "example": "abc123" }, "event_id": { "type": "string", "description": "The value of the `event_id` property in the event, if it has one.", "example": "567491ee-9105-4a87-9cbc-ed78a571645b" }, "error": { "type": "object", "description": "Information about the error that caused the event to not be processed.", "properties": { "code": { "type": "string", "description": "A short error code describing the error.", "example": "not found" }, "title": { "type": "string", "description": "Human-readable information about what caused the error.", "example": "failed to find a onesignal_id for user_id abc123" } } } } } } } } } } }, "400": { "description": "Bad request. The payload was rejected (e.g., malformed JSON or missing required fields). The response body shape is currently an empty object placeholder. Treat any 400 as a fatal request error.", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "401": { "description": "Unauthorized. The `Authorization` header is missing or invalid. This response uses `text/plain` with an empty body (not the standard `BasicErrorResponse` envelope). Treat any 401 from this endpoint as an auth failure regardless of body.", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } }, "deprecated": false } }, "/organizations/{organization_id}/audit_logs": { "get": { "summary": "List audit logs", "description": "Retrieve a paginated, time-scoped list of audit log events for an organization. Requires an Enterprise plan with the audit logs entitlement enabled.", "operationId": "list-audit-logs", "parameters": [ { "name": "organization_id", "in": "path", "description": "The UUID of the organization to retrieve audit logs for. Must match the authenticated Organization API Key.", "required": true, "schema": { "type": "string", "default": "YOUR_ORG_ID" } }, { "name": "Authorization", "in": "header", "description": "Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).", "required": true, "schema": { "type": "string", "default": "Key YOUR_ORGANIZATION_API_KEY" } }, { "name": "start_time", "in": "query", "description": "Start of the time range in ISO 8601 format (e.g. `2026-02-01T00:00:00Z`). Required unless `cursor` is provided. Must be within the last 90 days and no earlier than `2026-02-18T00:00:00Z`.", "schema": { "type": "string" } }, { "name": "end_time", "in": "query", "description": "End of the time range in ISO 8601 format. Defaults to the current time. Must be after `start_time`.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor returned in a previous response as `next_cursor`. When provided, `start_time` and `end_time` are ignored.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return per page. Minimum `1`, maximum `100`. Values outside this range are clamped automatically.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 } }, { "name": "app_ids", "in": "query", "description": "Filter events by app UUID. Accepts up to 10 values. Org-level events are always included. Repeat the parameter for multiple values: `app_ids=uuid1&app_ids=uuid2`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "actions", "in": "query", "description": "Filter by action type (e.g. `notification.sent`, `segment.created`). Accepts up to 20 values. Repeat the parameter for multiple values: `actions=notification.sent&actions=segment.created`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, { "name": "actor_ids", "in": "query", "description": "Filter by actor UUID (the user or service that performed the action). Accepts up to 10 values. Repeat the parameter for multiple values: `actor_ids=uuid1&actor_ids=uuid2`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "actor_emails", "in": "query", "description": "Filter by actor email address. Accepts up to 10 values. Repeat the parameter for multiple values: `actor_emails=a@example.com&actor_emails=b@example.com`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "target_types", "in": "query", "description": "Filter by the type of resource the action was performed on (e.g. `notification`, `segment`, `journey`). Accepts up to 10 values. Repeat the parameter for multiple values: `target_types=notification&target_types=segment`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "target_ids", "in": "query", "description": "Filter by the UUID of the resource the action was performed on. Accepts up to 10 values. Repeat the parameter for multiple values: `target_ids=uuid1&target_ids=uuid2`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "ip_addresses", "in": "query", "description": "Filter by the IP address the action originated from. Accepts up to 10 values. Repeat the parameter for multiple values: `ip_addresses=203.0.113.1&ip_addresses=203.0.113.2`.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "description": "Array of audit log events, ordered by `occurred_at` ascending.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the audit log event." }, "organization_id": { "type": "string", "description": "UUID of the organization the event belongs to." }, "app_id": { "type": "string", "description": "UUID of the app the event is associated with. Absent for org-level events." }, "action": { "type": "string", "description": "The action that was performed (e.g. `notification.sent`, `segment.created`, `member.invited`)." }, "occurred_at": { "type": "string", "description": "RFC 3339 timestamp of when the event occurred (e.g. `2026-02-18T12:34:56Z`)." }, "version": { "type": "integer", "description": "Schema version of the event payload." }, "actor": { "type": "object", "description": "The user or service that performed the action. Absent if the actor is unknown.", "properties": { "type": { "type": "string", "description": "Actor type (e.g. `user`, `service`)." }, "id": { "type": "string", "description": "UUID of the actor." }, "name": { "type": "string", "description": "Display name of the actor. Absent if unavailable." }, "email": { "type": "string", "description": "Email address of the actor. Absent if unavailable." }, "metadata": { "type": "object", "description": "Additional actor-specific data." } } }, "targets": { "type": "array", "description": "The resources the action was performed on. May be empty for org-level events.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type (e.g. `notification`, `segment`, `journey`, `app`)." }, "id": { "type": "string", "description": "UUID of the resource." }, "name": { "type": "string", "description": "Display name of the resource. Absent if unavailable." }, "metadata": { "type": "object", "description": "Additional resource-specific data." } } } }, "context": { "type": "object", "description": "Request context at the time of the event. Absent if context was not captured.", "properties": { "ip": { "type": "string", "description": "IP address the request originated from." }, "user_agent": { "type": "string", "description": "User agent of the client that made the request." }, "country": { "type": "string", "description": "Country code derived from the request IP." }, "metadata": { "type": "object", "description": "Additional context-specific data." } } }, "metadata": { "type": "object", "description": "Additional event-specific data that does not fit into the standard fields." } } } }, "has_more": { "type": "boolean", "description": "`true` if additional events exist beyond this page. Use `next_cursor` to fetch the next page." }, "next_cursor": { "type": "string", "description": "Opaque cursor to pass as `cursor` in the next request. Only present when `has_more` is `true`." } } }, "examples": { "Result": { "value": { "audit_logs": [ { "id": "a1b2c3d4-0000-0000-0000-000000000001", "organization_id": "YOUR_ORG_ID", "app_id": "YOUR_APP_ID", "action": "segment.created", "occurred_at": "2026-02-18T10:22:01Z", "version": 1, "actor": { "type": "user", "id": "u1b2c3d4-0000-0000-0000-000000000001", "name": "Jane Smith", "email": "jane@example.com", "metadata": {} }, "targets": [ { "type": "segment", "id": "s1b2c3d4-0000-0000-0000-000000000001", "name": "High-value users", "metadata": {} } ], "context": { "ip": "203.0.113.42", "user_agent": "Mozilla/5.0", "country": "US", "metadata": {} }, "metadata": {} } ], "has_more": true, "next_cursor": "eyJv..." } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "Result": { "value": {} } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "Result": { "value": {} } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Always emitted on 429 responses.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "API rate limit exceeded" ] } } } }, "503": { "description": "Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicErrorResponse" }, "example": { "errors": [ "Service temporarily unavailable" ] } } } } } } } } }