Push notification API

This page describes the Hive Axyl Server API that the app server calls directly for 'Push notifications'. The app client does not send push notifications directly, so the app server uses this API to send remote push notifications to users.

Send remote push notifications

POST /push/v1/messages

Immediately sends push notifications to the specified users. Specify up to 100 users per request. Call this API when you send a notification to one or more users for whom a specific event occurred in the app or a condition was met.

Notifications are delivered to the devices that users registered with Register device tokens. Users who have not registered a token do not receive notifications.

Before calling the API

Item	Value
Caller	`app server`
Base URL	`https://app-api.hiveaxyl.com`
Authentication	`Authorization: Bearer {access-token}`

Warning

Put the token for the app server that you received from Issue a token in the authentication header. If you call with a user's login token, the request is rejected. Keep the access token and the Client Secret used for token issuance only on the app server.

Call parameters

Name	Location	Type	Required	Description
body	body	`CreatePushSendRequest`	`true`	The users to receive the notification, the notification content, and the delivery options.

Request body CreatePushSendRequest

Field	Type	Required	Description
`appIds`	`array[string]`	`true`	List of App IDs to send the notification to. App IDs are created separately for each platform or store, so to send to both Android and iOS users, specify each App ID together. Notifications are sent only to tokens registered with the specified App IDs. Check them in Project Settings > App ID, and specify 1 to 50.
`identifiers`	`array[object]`	`true`	List of users to receive the notification. Specify 1 to 100 users.
`category`	`string`	`true`	Notification type. `INFO` is an informational notification and `ADVERTISE` is an advertising notification; the devices that receive the notification depend on the user's notification consent. For details, see Notes for each API.
`defaultLanguage`	`string`	`true`	Default language code. If `messages` has no message that matches the language of the user's device, the message in this language is sent. `messages` must contain a message for this language code.
`messages`	`object`	`true`	Map with language codes as keys and the message in each language as values. Include at least one message. The available language codes are `ko`, `en`, `ja`, `zh-Hans`, `zh-Hant`, `de`, `fr`, `ru`, `it`, `es`, `pt`, `pl`, `nl`, `tr`, `th`, `id`, `ar`, `hi`, `vi`, `sv`, `cs`, `fa`, `no`, `uk`, `ro`, `he`, `ms`, `da`, `el`, `hu`, and `tl`.
`options`	`object`	`false`	Platform-specific notification delivery and display options. If omitted, the notification is sent with each platform's default settings. If the entire `options`, including `customData`, `android`, and `apns`, is larger than 1,536 bytes when converted to JSON, the request is rejected.

Nested request object identifiers[]

Field	Type	Required	Description
`targetPlayerId`	`integer(int64)`	`true`	Player ID of the user to receive the notification.

Nested request object messages.{language code}

Field	Type	Required	Description
`notification`	`object`	`true`	Notification content to display to the user. The same content applies to all platforms.
`notification.title`	`string`	`true`	Notification title. Up to 240 characters.
`notification.body`	`string`	`true`	Notification body. Up to 420 characters.
`notification.image`	`string`	`false`	Notification image URL. Up to 512 characters. On Android, it is displayed as the image of the expanded notification. On iOS, the image is displayed only if the app includes a Notification Service Extension.

Nested request object options

Field	Type	Required	Description
`customData`	`object`	`false`	Data to pass to the app. Include up to 12 pairs in which both the key and the value are strings; keys are up to 20 characters, and values are 1 to 512 characters. The total size of `options`, including `customData`, must be 1,536 bytes or less. It is delivered only to Android devices, not to iOS devices. You cannot use keys reserved by the system, such as `from`, `notification`, `message_type`, and keys that start with `google.`.
`android.priority`	`string`	`false`	Priority for delivering the message to Android devices. `HIGH` attempts immediate delivery even in Doze mode, when the device is in a power-saving state, and `NORMAL` is subject to the operating system's battery optimization. This value is different from the display importance of the notification channel.
`android.notification.channelId`	`string`	`false`	Notification channel ID to use on Android 8.0 or later. The app must create the channel in advance; if you do not specify it or the channel ID does not exist, the FCM default channel is used. Up to 64 characters.
`android.notification.clickAction`	`string`	`false`	Intent action to run when the notification is tapped. The Activity that has the matching intent-filter runs; if not specified, the app's default Activity runs. Up to 128 characters.
`android.notification.icon`	`string`	`false`	Resource name of the notification icon. It must be included in the app's res/drawable; if not specified, the app icon is used. Up to 64 characters.
`android.notification.sound`	`string`	`false`	Resource name of the notification sound. It must be included in the app's res/raw. Up to 64 characters.
`android.notification.tag`	`string`	`false`	Notification tag. If a notification with the same tag already exists, it is replaced with the new notification. Up to 64 characters.
`apns.sound`	`string`	`false`	File name of the notification sound to play on iOS and macOS devices. To use the system default notification sound, specify `default`. Up to 64 characters.
`apns.badge`	`integer`	`false`	Badge number to display on the app icon. 0 or greater; the default value is `1`.
`apns.category`	`string`	`false`	Notification type identifier. It must match one of the `UNNotificationCategory` identifiers the app registered at startup. Up to 128 characters.

Call example

curl

curl -X POST 'https://app-api.hiveaxyl.com/push/v1/messages' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "appIds": ["{android-app-id}", "{ios-app-id}"],
    "identifiers": [
      { "targetPlayerId": 1001 },
      { "targetPlayerId": 1002 }
    ],
    "category": "INFO",
    "defaultLanguage": "en",
    "messages": {
      "en": {
        "notification": {
          "title": "Maintenance Notice",
          "body": "Server maintenance is scheduled from 12:00 to 14:00 UTC. Some services may be unavailable.",
          "image": "https://cdn.example.com/push/maintenance_en.png"
        }
      },
      "ko": {
        "notification": {
          "title": "서버 점검 안내",
          "body": "오늘 오후 12시부터 2시까지 서버 점검이 진행됩니다. 이용에 불편을 드려 죄송합니다."
        }
      }
    },
    "options": {
      "android": {
        "notification": {
          "icon": "ic_notification",
          "tag": "maintenance"
        },
        "priority": "HIGH"
      },
      "apns": {
        "sound": "default",
        "badge": 1
      }
    }
  }'

Response

For the common data and meta, the error body, and the product common error codes, see Push notification responses and errors. This section describes the objects this API actually returns and the handling specific to this API.

Asynchronous request acceptance response

A 202 response means that the notification sending request has been accepted, not that the notification has arrived on the user's device. Both data and meta in the response are null.

Response example

202 Accepted400 Bad Request

{
  "data": null,
  "meta": null
}

{
  "type": "/errors/common/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Invalid request parameters.",
  "instance": "/push/v1/messages",
  "code": "invalid_parameter",
  "errors": [
    {
      "field": "identifiers",
      "message": "must not be empty"
    },
    {
      "field": "defaultLanguage",
      "message": "must not be blank"
    }
  ]
}

Notes for each API

Notifications are delivered only to devices that have the consent matching the category. INFO is delivered to devices with informational notification consent turned on, and ADVERTISE is delivered to devices with both advertising notification consent and nighttime advertising notification consent turned on. The app client updates the user's notification consent with Change notification consent.

If you send only notification, the operating system displays the notification, so there is nothing to implement separately in the app. If you send options.customData with the notification, the app processes that data when the Android app is in the foreground or when the user taps the notification.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`202`	`application/json`	Notification sending request accepted	-	`data` and `meta` are `null`.
`400`	`application/problem+json`	Request validation failed or authorization denied	-	-
`500`	`application/problem+json`	Server error	-	-