Developer Interface¶

This page of the documentation will cover all methods and classes available to the developer.

Core Interface¶

class onesignal.OneSignal(api_key, app_id=None, api_version='v1')¶

__init__(api_key, app_id=None, api_version='v1')¶

A OneSignal API wrapper instance.

Parameters:	api_key – Your application api key or user api key. app_id – (optional) Your application id. api_version – (optional) The API version, defaults to “v1”.

apps()¶

View the details of all of your current OneSignal apps.

Docs: https://documentation.onesignal.com/reference#view-apps-apps

Return type:	dict

Usage:

>>> onesignal.apps()
>>> [
      {
          id: "92911750-242d-4260-9e00-9d9034f139ce",
          name: "Your app 1",
          players: 150,
          messagable_players: 143,
          updated_at: "2014-04-01T04:20:02.003Z",
          created_at: "2014-04-01T04:20:02.003Z",
          gcm_key: "a gcm push key",
          chrome_key: "A Chrome Web Push GCM key",
          chrome_web_origin: "Chrome Web Push Site URL",
          chrome_web_gcm_sender_id: "Chrome Web Push GCM Sender ID",
          chrome_web_default_notification_icon: "http://yoursite.com/chrome_notification_icon",
          chrome_web_sub_domain:"your_site_name",
          apns_env: "sandbox",
          apns_certificates: "Your apns certificate",
          safari_apns_cetificate: "Your Safari APNS certificate",
          safari_site_origin: "The homename for your website for Safari Push, including http or https",
          safari_push_id: "The certificate bundle ID for Safari Web Push",
          safari_icon_16_16: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16.png",
          safari_icon_32_32: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16@2.png",
          safari_icon_64_64: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/32x32@2x.png",
          safari_icon_128_128: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128.png",
          safari_icon_256_256: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128@2x.png",
          site_name: "The URL to your website for Web Push",
          basic_auth_key: "NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"
      }
  ]

apps_create(name, **data)¶

Creates a new OneSignal app.

Parameters:	name – The name of your new app, as displayed on your apps list on the dashboard. This can be renamed later.

Docs: https://documentation.onesignal.com/reference#create-an-app

Return type:	dict

Usage:

>>> onesignal.apps_create(
      'OneSignal API Test',
      apns_env='production',
      apns_p12='asdsadcvawe223cwef...',
      apns_p12_password='FooBar',
      gcm_key='a gcm push key',
  )
>>> {
      id: "92911750-242d-4260-9e00-9d9034f139ce",
      name: "OneSignal API Test",
      players: 150,
      messagable_players: 143,
      updated_at: "2014-04-01T04:20:02.003Z",
      created_at: "2014-04-01T04:20:02.003Z",
      gcm_key: "a gcm push key",
      chrome_key: "A Chrome Web Push GCM key",
      chrome_web_origin: "Chrome Web Push Site URL",
      chrome_web_gcm_sender_id: "Chrome Web Push GCM Sender ID",
      chrome_web_default_notification_icon: "http://yoursite.com/chrome_notification_icon",
      chrome_web_sub_domain:"your_site_name",
      apns_env: "sandbox",
      apns_certificates: "Your apns certificate",
      safari_apns_cetificate: "Your Safari APNS certificate",
      safari_site_origin: "The homename for your website for Safari Push, including http or https",
      safari_push_id: "The certificate bundle ID for Safari Web Push",
      safari_icon_16_16: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16.png",
      safari_icon_32_32: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16@2.png",
      safari_icon_64_64: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/32x32@2x.png",
      safari_icon_128_128: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128.png",
      safari_icon_256_256: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128@2x.png",
      site_name: "The URL to your website for Web Push",
      basic_auth_key: "NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"
  }

apps_details(app_id=None)¶

View the details of a single OneSignal app.

Parameters:	app_id – (optional) If you’re using your user API Key, you can pass one of your app ids.

Docs: https://documentation.onesignal.com/reference#view-an-app

Return type:	dict

Usage:

>>> onesignal.apps_details('92911750-242d-4260-9e00-9d9034f139ce')
>>> {
      id: "92911750-242d-4260-9e00-9d9034f139ce",
      name: "Your app 1",
      players: 150,
      messagable_players: 143,
      updated_at: "2014-04-01T04:20:02.003Z",
      created_at: "2014-04-01T04:20:02.003Z",
      gcm_key: "a gcm push key",
      chrome_key: "A Chrome Web Push GCM key",
      chrome_web_origin: "Chrome Web Push Site URL",
      chrome_web_gcm_sender_id: "Chrome Web Push GCM Sender ID",
      chrome_web_default_notification_icon: "http://yoursite.com/chrome_notification_icon",
      chrome_web_sub_domain:"your_site_name",
      apns_env: "sandbox",
      apns_certificates: "Your apns certificate",
      safari_apns_cetificate: "Your Safari APNS certificate",
      safari_site_origin: "The homename for your website for Safari Push, including http or https",
      safari_push_id: "The certificate bundle ID for Safari Web Push",
      safari_icon_16_16: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16.png",
      safari_icon_32_32: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16@2.png",
      safari_icon_64_64: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/32x32@2x.png",
      safari_icon_128_128: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128.png",
      safari_icon_256_256: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128@2x.png",
      site_name: "The URL to your website for Web Push",
      basic_auth_key: "NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"
  }

apps_update(app_id, **data)¶

Updates the name or configuration settings of an existing OneSignal app.

Parameters:	app_id – The id of the app you want to update.

Docs: https://documentation.onesignal.com/reference#update-an-app

Return type:	dict

Usage:

>>> onesignal.apps_update(
      name='OneSignal API Test EDITED',
  )
>>> {
      id: "92911750-242d-4260-9e00-9d9034f139ce",
      name: "OneSignal API Test EDITED",
      players: 150,
      messagable_players: 143,
      updated_at: "2014-04-01T04:20:02.003Z",
      created_at: "2014-04-01T04:20:02.003Z",
      gcm_key: "a gcm push key",
      chrome_key: "A Chrome Web Push GCM key",
      chrome_web_origin: "Chrome Web Push Site URL",
      chrome_web_gcm_sender_id: "Chrome Web Push GCM Sender ID",
      chrome_web_default_notification_icon: "http://yoursite.com/chrome_notification_icon",
      chrome_web_sub_domain:"your_site_name",
      apns_env: "sandbox",
      apns_certificates: "Your apns certificate",
      safari_apns_cetificate: "Your Safari APNS certificate",
      safari_site_origin: "The homename for your website for Safari Push, including http or https",
      safari_push_id: "The certificate bundle ID for Safari Web Push",
      safari_icon_16_16: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16.png",
      safari_icon_32_32: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/16x16@2.png",
      safari_icon_64_64: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/32x32@2x.png",
      safari_icon_128_128: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128.png",
      safari_icon_256_256: "http://onesignal.com/safari_packages/92911750-242d-4260-9e00-9d9034f139ce/128x128@2x.png",
      site_name: "The URL to your website for Web Push",
      basic_auth_key: "NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"
  }

csv_export(**data)¶

Generate a compressed CSV export of all of your current user data.

Docs: https://documentation.onesignal.com/reference#csv-export

Return type:	dict

Usage:

>>> onesignal.csv_export('a8c50012-7a78-492a-8a34-6bd3aa2e5f87', active_type=3600)
>>> {
      "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966-d8cc-11e4-bed1-df8f05be55ba/users_184948440ec0e334728e87228011ff41_2015-11-10.csv.gz"
  }

delete(url, **data)¶

Shortcut to make a DELETE request to OneSignal’s REST API.

Parameters:	url – Either a full OneSignal REST API url or a portion (i.e. “players/id”). **data – Parameters that are accepted by OneSignal for the endpoint you’re requesting.
Return type:	dict

devices(**data)¶

View the details of multiple devices in one of your OneSignal apps.

Docs: https://documentation.onesignal.com/reference#view-devices

Return type:	dict

Usage:

>>> onesignal.devices()
>>> {
      "total_count": 3,
      "offset": 2,
      "limit": 2,
      "players": [
          {
              "identifier": "ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566",
              "session_count": 1,
              "language": "en",
              "timezone": -28800,
              "game_version": "1.0",
              "device_os": "7.0.4",
              "device_type": 0,
              "device_model": "iPhone",
              "ad_id": null,
              "tags": {
                  "a": "1",
                  "foo": "bar"
              },
              "last_active": 1395096859,
              "amount_spent": 0.0,
              "created_at": 1395096859,
              "invalid_identifier": false,
              "badge_count": 0
          }
      ]
  }

devices_create(device_type, **data)¶

Register a new device to one of your OneSignal apps.

Parameters:	device_type – An integer representing a device platform from the docs.

Docs: https://documentation.onesignal.com/reference#add-a-device

Return type:	dict

Usage:

>>> onesignal.devices_create(0, identifier='ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566')
>>> {
      "identifier": "ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566",
      "session_count": 1,
      "language": "en",
      "timezone": -18880,
      "game_version": "1.0",
      "device_os": "",
      "device_type": 0,
      "device_model": "",
      "ad_id": null,
      "tags": {
      },
      "last_active": 1395096859,
      "amount_spent": 0.0,
      "created_at": 1395096859,
      "invalid_identifier": false,
      "badge_count": 0
  }

devices_details(player_id)¶

View the details of an existing device in one of your OneSignal apps.

Docs: https://documentation.onesignal.com/reference#view-device

Return type:	dict

Usage:

>>> onesignal.devices()
>>> {
      "identifier": "ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566",
      "session_count": 1,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "7.0.4",
      "device_type": 0,
      "device_model": "iPhone",
      "ad_id": null,
      "tags": {
          "a": "1",
          "foo": "bar"
      },
      "last_active": 1395096859,
      "amount_spent": 0.0,
      "created_at": 1395096859,
      "invalid_identifier": false,
      "badge_count": 0
  }

devices_update(player_id, **data)¶

Update an existing device in one of your OneSignal apps.

Parameters:	player_id – player_id of the device you want to update.

Docs: https://documentation.onesignal.com/reference#edit-device

Return type:	dict

Usage:

>>> onesignal.devices_update('a8c50012-7a78-492a-8a34-6bd3aa2e5f87', lang='es')
>>> {'success': true}

get(url, **data)¶

Shortcut to make a GET request to OneSignal’s REST API.

Parameters:	url – Either a full OneSignal REST API url or a portion (i.e. “players/id”). **data – Parameters that are accepted by OneSignal for the endpoint you’re requesting.
Return type:	dict

notifications()¶

View the details of multiple notifications.

Docs: https://documentation.onesignal.com/reference#view-notifications

Return type:	dict

notifications_cancel(notification_id)¶

Sends notifications to your users.

Docs: https://documentation.onesignal.com/reference#create-notification

Return type:	dict

Usage:

>>> onesignal.notifications_cancel('732d69c7-2599-489c-89a6-55cf6b41defe')
>>> {u'success': true}

notifications_create(**data)¶

Sends notifications to your users.

Docs: https://documentation.onesignal.com/reference#create-notification

Return type:	dict

Usage:

>>> onesignal.notifications_create(
      include_player_ids=['a8c50012-7a78-492a-8a34-6bd3aa2e5f87',],
      contents={
        'en': 'English Message'
      }
  )
>>> {u'id': u'732d69c7-2599-489c-89a6-55cf6b41defe', u'recipients': 1}

notifications_details(notification_id)¶

View the details of a single notification.

Parameters:	notification_id – Notification to get details for.

Docs: https://documentation.onesignal.com/reference#view-notification

Return type:	dict

Usage:

>>> onesignal.notifications_details('732d69c7-2599-489c-89a6-55cf6b41defe')
>>> {
      "id": "732d69c7-2599-489c-89a6-55cf6b41defe",
      "successful": 1,
      "failed": 0,
      "converted": 3,
      "remaining": 0,
      "queued_at": 1415914655,
      "send_after": 1415914655,
      "url": "https://yourWebsiteToOpen.com",
      "data": {
          "foo": "bar",
          "your": "custom metadata"
      },
      "canceled": false,
      "headings": {
          "en": "English and default langauge heading",
          "es": "Spanish language heading"
      },
      "contents": {
          "en": "English language content",
          "es": "Hola"
      }
  }

notifications_open(notification_id)¶

Track when users open a notification.

Parameters:	notification_id – Notification to track an open for.

Docs: https://documentation.onesignal.com/reference#track-open

Return type:	dict

post(url, **data)¶

Shortcut to make a POST request to OneSignal’s REST API.

Parameters:	url – Either a full OneSignal REST API url or a portion (i.e. “players/id”). **data – Parameters that are accepted by OneSignal for the endpoint you’re requesting.
Return type:	dict

purchases_create(player_id, purchases=None, **data)¶

Track a new purchase in your app.

Parameters:	player_id – player_id of the device you want to create a purchase for. purchases – An array of purchases with the following keys: sku, amount, iso

Docs: https://documentation.onesignal.com/reference#new-purchase

Return type:	dict

Usage:

>>> onesignal.sessions_create('a8c50012-7a78-492a-8a34-6bd3aa2e5f87')
>>> {'success': true}

put(url, **data)¶

Shortcut to make a PUT request to OneSignal’s REST API.

Parameters:	url – Either a full OneSignal REST API url or a portion (i.e. “players/id”). **data – Parameters that are accepted by OneSignal for the endpoint you’re requesting.
Return type:	dict

request(method, url, **data)¶

Make a request to OneSignal’s REST API.

Parameters:	method – GET, POST, DELETE or PUT. url – Either a full OneSignal REST API url or a portion (i.e. “players/id”). **data – Parameters that are accepted by OneSignal for the endpoint you’re requesting.
Return type:	dict

sessions_create(player_id, **data)¶

Update a device’s session information.

Parameters:	player_id – player_id of the device you want to create a session for.

Docs: https://documentation.onesignal.com/reference#new-session

Return type:	dict

Usage:

>>> onesignal.sessions_create('a8c50012-7a78-492a-8a34-6bd3aa2e5f87')
>>> {'success': true}

sessions_length_update(player_id, active_time)¶

Track a new purchase in your app.

Parameters:	player_id – player_id of the device you want to update the session length for.

Docs: https://documentation.onesignal.com/reference#increment-session-length

Return type:	dict

Usage:

>>> onesignal.sessions_create('a8c50012-7a78-492a-8a34-6bd3aa2e5f87', active_type=3600)
>>> {'success': true}

Exceptions¶

exception onesignal.OneSignalApiError(msg, status_code=None)¶

Generic error class, catch-all for most OneSignal API issues.

from onesignal import OneSignalApiError

Developer Interface¶

Core Interface¶

Exceptions¶

Table Of Contents

Related Topics

This Page