Server Side Studo App Push Notifications

This API allows you as a partner to send push notifications to users of the Studo App.
Push notifications can be sent to users that are subscribed to a partner specific category. A partner can offer multiple categories and a user can subscribe to any of those.
It is also possible to send notifications to specific users - each user is then one unique category.

Request

URL: https://api.studo.co/api/v1/webhooks/pushNotification

field	type	description
partnerId	String	Unique identifier of the partner.
partnerSecret	String	Shared secret of the partner.
pushNotificationId	String	Unique identifier of the push notification. Each identifier must be used only once. Ensures that a notification is only sent once. [A-Za-z0-9_-]{1,40}
categoryIds	String[]	The ids of the categories this notification should be sent to. Users that subscribes to one of those ids will receive the push notification. There is a maximum of 200 categories per request.
title	String	The title that should be shown in the notification.
text	String	The message that should be shown in the notification.
action	String	An action that will be triggered when a user taps on the notification. See Available Actions.
actionParams	object?	Parameters of the action. See Available Actions for the available actions an their parameters.
url	String?	Deprecated: Replaced by "action": "web", "actionParams": { "url": "https://..." }. Url to open when user taps on the notification.

Example

POST https://api.studo.co/api/v1/webhooks/pushNotification
content-type: application/json

{
    "partnerId": "partnerXYZ",
    "partnerSecret": "s3cret",
    "pushNotificationId": "someId",
    "categoryIds": [
        "fjdkslajfkldjsaklfdso45jr43ljrafklwe",
        "jfdklsajfkldsakfj43kljrafomlaw4fdasf"
    ],
    "title": "Push notification title",
    "text": "Push notification message",
    "action": "web",
    "actionParams": {
        "url": "https://studo.com"
    }
}

Available Actions

The following values can be used for the action property. The nested values are the actionParams for the action. Optional parameters are suffixed with ? (the question mark does not belong to the property name). The type of the value of the action parameters is always String. If an action does not have any required parameter the actionParams property can be skipped.
When a user taps the push notification the Studo App will be opened and the defined action will be triggered.

info

Keep in mind that not all actions are available on all Universities.

• web: Opens a web page in the Studo Browser
  • url: The url to open
• news:
  • newsId: The id of the post that should be shown. You can get the id from the preview link of the post.
• grades: Opens the grades list
• calendar: Opens the calendar
• courses: Opens the course list
• study: Opens the study list
• lunch: Opens the lunch overview
• studentCard: Opens the university/student/transport card

info

Further actions can be added on request.

Response

field	type	description
status	Int	HTTP-Status of the response.
message	String	Description of the response.
unusedCategoryIds	String[]	Ids of categories that are not subscribed by any user.

The HTTP-Status will always be the same as the status property.

• 201 Notification was created and will be sent (sending might take some time, response will be sent "instantly").
• 302 The notification was already created previously and is currently sent (or already finished sending).
• 4xx No new notification was created. See message for details.
• 5xx Undefined behaviour. Retry the request after some delay. In case of multiple consecutive failures contact our support.

It is ensured that the notification is either sent to all users or to none. The API also ensures, that notifications with the same pushNotificationId from one partner are only sent once. In case of failure you can safely retry the request.

Success Examples

HTTP/1.1 201 Created
content-type: application/json

{
    "status": 201,
    "message": "OK",
    "unusedCategoryIds": [],
}

HTTP/1.1 201 Created
content-type: application/json

{
    "status": 201,
    "message": "OK",
    "unusedCategoryIds": [
        "fjkdlsajfklasjdf",
        "fjdkslajfkdsajklfjoi"
    ],
}

HTTP/1.1 302 Found
content-type: application/json

{
    "status": 302,
    "message": "Notification with id 'someId' was already created.",
    "unusedCategoryIds": [],
}

Error Examples

HTTP/1.1 400 Bad Request
content-type: application/json

{
    "status": 400,
    "message": "Invalid request body.",
    "unusedCategoryIds": []
}

HTTP/1.1 400 Bad Request
content-type: application/json

{
    "status": 400,
    "message": "'title' must not be empty.",
    "unusedCategoryIds": []
}

HTTP/1.1 400 Bad Request
content-type: application/json

{
    "status": 400,
    "message": "Invalid action 'wbe'.",
    "unusedCategoryIds": []
}

HTTP/1.1 400 Bad Request
content-type: application/json

{
    "status": 400,
    "message": "'actionParams.url' is a required parameter for action 'web'.",
    "unusedCategoryIds": []
}

HTTP/1.1 400 Bad Request
content-type: application/json

{
    "status": 400,
    "message": "actionParams.url' must be a valid https URL.",
    "unusedCategoryIds": []
}

HTTP/1.1 401 Unauthorized
content-type: application/json

{
    "status": 401,
    "message": "Unauthorized",
    "unusedCategoryIds": []
}

HTTP/1.1 500 Internal Server Error
content-type: application/json

{
    "status": 500,
    "message": "Internal Server Error",
    "unusedCategoryIds": [],
}