A Python client library for OneSignal REST API. Supports async/await.
Please read v1.x documentation for older versions.
pip install onesignal-sdk
You can think this library as a wrapper around OneSignal REST API. It is fairly simple to use:
- Create an instance of Client with your credentials. user_auth_key is not required but necessary for some API calls.
- Build your request body and call related method on the client.
- Client will make the request with required authentication headers and parse the response for you.
from onesignal_sdk.client import Client
client = Client(app_id=APP_ID, rest_api_key=REST_API_KEY, user_auth_key=USER_AUTH_KEY)
notification_body = {
'contents': {'tr': 'Yeni bildirim', 'en': 'New notification'},
'included_segments': ['Active Users'],
'filters': [{'field': 'tag', 'key': 'level', 'relation': '>', 'value': 10}],
}
response = client.send_notification(notification_body)
print(response.body)AsyncClient and Client shares exactly the same interface, method signatures. All the examples for Client in this documentation is also valid for AsyncClient.
from onesignal_sdk.client import AsyncClient
async def main():
client = AsyncClient(app_id=APP_ID, rest_api_key=REST_API_KEY)
notification_body = {'contents': ...}
response = await client.send_notification(notification_body)
print(response.body)We are using httpx library for making http requests underneath. Responses from OneSignal REST API are parsed as JSON and returned to you as an instance of OneSignalResponse, which is just a simple class consisting of following attributes:
- .body: JSON parsed body of the response, as a Python dictionary.
- .status_code: HTTP status code of the response.
- .http_response: Original httpx.Response object, in case you want to access more attributes.
Sample code:
client = AsyncClient(...)
response = await client.view_apps()
print(response.body) # JSON parsed response
print(response.status_code) # Status code of response
print(response.http_response) # Original http response object.An instance of OneSignalHTTPError is raised whenever http responses have a status code other than 2xx. For instance, if status code of an http response is 404, OneSignalHTTPError is raised with additional details. See the sample snippet below, error handling is the same of AsyncClient
from onesignal_sdk.client import Client
from onesignal_sdk.error import OneSignalHTTPError
# Create a One Signal client using API KEYS.
client = Client(app_id=APP_ID, rest_api_key=REST_API_KEY, user_auth_key=USER_AUTH_KEY)
notification_body = {
'contents': {'tr': 'Yeni bildirim', 'en': 'New notification'},
'included_segments': ['Active Users'],
'filters': [{'field': 'tag', 'key': 'level', 'relation': '>', 'value': 10}],
}
response = client.send_notification(notification_body)
print(response.body)
try:
notification_body = {
'contents': {'en': 'New notification'},
'included_segments': ['Active Users'],
}
# Make a request to OneSignal and parse response
response = client.send_notification(notification_body)
print(response.body) # JSON parsed response
print(response.status_code) # Status code of response
print(response.http_response) # Original http response object.
except OneSignalHTTPError as e: # An exception is raised if response.status_code != 2xx
print(e)
print(e.status_code)
print(e.http_response.json()) # You can see the details of error by parsing original responseReference: https://documentation.onesignal.com/reference/create-notification
notification_body = {
'contents': {'en': 'New notification'},
'included_segments': ['Active Users'],
}
response = client.send_notification(notification_body)Reference: https://documentation.onesignal.com/reference/cancel-notification
response = client.cancel_notification('notification-id')Reference: https://documentation.onesignal.com/reference/view-notification
response = client.view_notification('notification-id')Reference: https://documentation.onesignal.com/reference/view-notifications
request_query = {'limit': 5, 'offset': 2}
response = client.view_notification(request_query)Reference: https://documentation.onesignal.com/reference/notification-history
body = {
'events': 'clicked',
'email': 'test@email.com'
}
response = client.notification_history('notification-id', body)Reference: https://documentation.onesignal.com/reference/view-device
response = client.view_device('device-id')Reference: https://documentation.onesignal.com/reference/view-devices
request_query = {'limit': 1}
response = client.view_devices(request_query)
// or no query
response = client.view_devices()Reference: https://documentation.onesignal.com/reference/add-a-device
body = {
'device_type': 1,
'identifier': '7a8bbbb00000'
}
response = client.add_device(body)Reference: https://documentation.onesignal.com/reference/edit-device
body = {
'device_type': 1,
'identifier': '7a8bbbb00000'
}
response = client.edit_device('2ada581e-1380-4967-bcd2-2bb4457d6171', body)Reference: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id
body = {
'tags': {
'foo': '',
'bar': 'new_value',
}
}
response = client.edit_tags('f0f0f0f0', body)Reference: https://documentation.onesignal.com/reference/new-session
body = {
'language': 'de',
'timezone': -28800
}
response = client.new_session('foo-device-id', body)Reference: https://documentation.onesignal.com/reference/new-purchase
body = {
'purchases': [
{'sku': 'SKU123', 'iso': 'EUR'}
]
}
response = client.new_purchase('foo-device-id', body)Reference: https://documentation.onesignal.com/reference/csv-export
body = {
'extra_fields': ['country', 'location'],
'last_active_since': '1469392779',
}
response = client.csv_export(body)Reference: https://documentation.onesignal.com/reference/create-segments
body = {
'name': 'new-segment',
'filters': [{'field': 'session_count', 'relation': '>', 'value': 1}],
}
response = client.create_segment(body)Reference: https://documentation.onesignal.com/reference/delete-segments
response = client.delete_segment('segment-id-1')Reference: https://documentation.onesignal.com/reference/view-outcomes
extra_http_params = {
'outcome_platforms': 0
}
outcome_names = ['os__click.count']
response = client.view_outcomes(outcome_names, extra_http_params)Reference: https://documentation.onesignal.com/reference/view-apps-apps
Requires user_auth_key!
response = client.view_apps()Reference: https://documentation.onesignal.com/reference/view-an-app
Requires user_auth_key!
response = client.view_app('034744e7-4eb-1c6a647e47b')Reference: https://documentation.onesignal.com/reference/create-an-app
Requires user_auth_key!
app_body = {
'name': 'new-android-app',
'apns_env': 'production',
}
response = client.create_app(app_body)Reference: https://documentation.onesignal.com/reference/update-an-app
Requires user_auth_key!
app_body = {
'name': 'new-app',
}
response = client.update_app('f33c318b-6c99', app_body)This project is under the MIT license.