Step 4. Send remote push notifications

POST /v1/messages

Immediately sends a notification message to specific users. You can target up to 100 users.

Warning

To perform this operation, you must be authenticated with the API using one of the following: bearerAuth

Call parameters

Name	Location	Type	Required	Description
body	body	`CreatePushSendRequest`	true	Target identification information, message content, and sending options of the push notification to send immediately
» category	body	string	true	Notification consent filter criterion. If `INFO`, the notification is sent only to tokens whose `agreement.info` is true; if `ADVERTISE`, it is sent only to tokens whose `agreement.advertise` and `agreement.night` are both true.
» defaultLanguage	body	`LanguageCode`	true	Language code to use as the fallback. A language code key that matches this value must exist in the `messages` map.
» identifiers	body	`Identifier[]`	true	List of identifiers of the target users to send the push notification to. You can specify up to 100 users.
»» targetPlayerId	body	integer(int64)	true	ID that identifies the user in Hive. Check it in the Hive authentication response.
» messages	body	object	true	Message map keyed by language code. It must include an entry for the language code specified in `defaultLanguage`, and that entry is used as the fallback when no entry matches the language code of the user's token. Only `LanguageCode` enum values are allowed as language code keys (for example: ko, en, ja).
»» additionalProperties	body	`Message`	false	Push message object for a single language.
»»» notification	body	`NotificationContent`	true	Notification content displayed to the user. Used as the default for all OSs.
»»»» body	body	string	true	Notification body.
»»»» image	body	string	false	Notification image URL. Android: Automatically displayed as an expanded notification (BigPictureStyle) image. iOS: Displayed only when a NotificationServiceExtension is included in the app. If it is not included, the image is not displayed. (See the Reference Kit)
»»»» title	body	string	true	Notification title.
» options	body	`PushOptions`	false	Options for notification delivery and display behavior for each OS. If omitted, the notification is sent with each OS's default settings.
»» android	body	object	false	Options that control how Android notifications are delivered through FCM and displayed
»»» notification	body	object	false	Options that control how Android system notifications are displayed. Valid only when the notification field is present.
»»»» channelId	body	string	false	Android notification channel ID (Android 8.0+). The app must create the channel in advance. If not specified or if the channel ID does not exist, it falls back to the FCM default channel.
»»»» clickAction	body	string	false	Intent action to run when the notification is tapped. The Activity with the matching intent-filter is launched. If not specified, the app's default Activity is launched.
»»»» icon	body	string	false	Notification icon resource name. It must be included in the app's res/drawable. If not specified, the app icon is used.
»»»» sound	body	string	false	Notification sound resource name. It must be included in the app's res/raw.
»»»» tag	body	string	false	Notification tag. Replaces (overwrites) an existing notification with the same tag.
»»» priority	body	string	false	FCM message delivery priority. This is a different concept from the notification display priority (the importance of channelId). HIGH: Attempts immediate delivery even in Doze mode. NORMAL: Subject to OS battery optimization.
»» customData	body	`CustomData`	false	Common custom data delivered regardless of the language code. Delivered only through FCM.
»»» additionalProperties	body	string	false	none
»» ios	body	object	false	Options that control how iOS notifications are delivered through APNs and displayed
»»» badge	body	integer(int32)	false	App icon badge number. Mapped to APNs aps.badge.
»»» category	body	string	false	Notification type identifier. Mapped to APNs aps.category, and must match the identifier of one of the UNNotificationCategory objects registered at app startup.
»»» sound	body	string	false	Notification sound file name or "default" (the system default notification sound). Mapped to APNs aps.sound.
» project	body	object	true	Identification information of the target Hive project and apps
»» appIds	body	[string]	true	List of identifiers of the target apps in the project. An app exists separately for each OS (Android, iOS, and so on) or market that the game is serviced on, and the notification is sent to tokens registered to the specified apps. Check them in Hive App Center.
»» projectId	body	string	true	Identifier of the target project, which you can check in the Hive Console

messages details

Name	Description
»» additionalProperties	Push message object for a single language. - Only `notification` provided: The OS displays the notification automatically. No app implementation needed. - `notification` + `Options.customData`: The OS displays the notification, and when the app is in the foreground or when the notification is tapped, the Android app processes customData. (Recommended)

Enumerated values

Parameter	Value
» category	INFO
» category	ADVERTISE
» defaultLanguage	ko
» defaultLanguage	en
» defaultLanguage	ja
» defaultLanguage	zh-Hans
» defaultLanguage	zh-Hant
» defaultLanguage	de
» defaultLanguage	fr
» defaultLanguage	ru
» defaultLanguage	it
» defaultLanguage	es
» defaultLanguage	pt
» defaultLanguage	pl
» defaultLanguage	nl
» defaultLanguage	tr
» defaultLanguage	th
» defaultLanguage	id
» defaultLanguage	ar
» defaultLanguage	hi
» defaultLanguage	vi
» defaultLanguage	sv
» defaultLanguage	cs
» defaultLanguage	fa
» defaultLanguage	false
» defaultLanguage	uk
» defaultLanguage	ro
» defaultLanguage	he
» defaultLanguage	ms
» defaultLanguage	da
» defaultLanguage	el
» defaultLanguage	hu
» defaultLanguage	tl
»»» priority	NORMAL
»»» priority	HIGH

Call example

curl

# You can also use wget
curl -X POST https://test-api.hiveaxyl.com/push/v1/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{
  "category": "INFO",
  "defaultLanguage": "en",
  "identifiers": [
    {
      "targetPlayerId": 1001
    },
    {
      "targetPlayerId": 1002
    }
  ],
  "messages": {
    "en": {
      "notification": {
        "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",
        "title": "Maintenance Notice"
      }
    },
    "ko": {
      "notification": {
        "body": "오늘 오후 12시부터 2시까지 서버 점검이 진행됩니다. 이용에 불편을 드려 죄송합니다.",
        "title": "서버 점검 안내"
      }
    }
  },
  "options": {
    "android": {
      "notification": {
        "icon": "ic_notification",
        "sound": "",
        "tag": "maintenance"
      },
      "priority": "HIGH"
    },
    "ios": {
      "badge": 1,
      "sound": "default"
    }
  },
  "project": {
    "appIds": [
      "com.com2us.hivesdk.android",
      "com.com2us.hivesdk.ios"
    ],
    "projectId": "com.com2us.hivesdk"
  }
  }'

Response

Status	Meaning	Description	Schema
202	Accepted	Accepted	`AcceptedEmptyResponse`
400	Bad Request	Bad Request — Request validation failed	`AxylBusinessErrorResponse`
401	Unauthorized	Unauthorized — Authentication failed (token missing or expired)	`AxylBusinessErrorResponse`
403	Forbidden	Forbidden — No permission to access the resource	`AxylBusinessErrorResponse`
500	Internal Server Error	Internal Server Error	`AxylErrorResponse`

Response example

202 AcceptedOccurs when the type of a request body field differs from the schema (for example, a string in a boolean field or a string in an int64 field). Because the body fails at the deserialization stage, field-level validation is not reached, and in this case the response does not include the errors array. instance varies depending on the actual request path.Bad Request — Request validation failedUnauthorized — Authentication failed (token missing or expired)Forbidden — No permission to access the resourceInternal Server Error

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

{
  "code": "invalid_parameter",
  "detail": "Request validation failed.",
  "instance": "/v1/tokens",
  "outcome": null,
  "status": 400,
  "title": "Invalid Request",
  "type": "/errors/axyl-push/invalid-parameter"
}

{
  "code": "invalid_parameter",
  "detail": "Request validation failed.",
  "errors": [
    {
      "field": "identifiers",
      "message": "must not be empty"
    },
    {
      "field": "defaultLanguage",
      "message": "must not be blank"
    }
  ],
  "instance": "/v1/messages",
  "outcome": null,
  "status": 400,
  "title": "Invalid Request",
  "type": "/errors/axyl-push/invalid-parameter"
}

{
  "code": "unauthorized",
  "detail": "Authentication token is missing or expired.",
  "instance": "/v1/...",
  "outcome": null,
  "status": 401,
  "title": "Unauthorized",
  "type": "/errors/axyl-push/unauthorized"
}

{
  "code": "forbidden",
  "detail": "You do not have permission to access this resource.",
  "instance": "/v1/...",
  "outcome": null,
  "status": 403,
  "title": "Forbidden",
  "type": "/errors/axyl-push/forbidden"
}

{
  "detail": "An unexpected error occurred.",
  "instance": "/v1/...",
  "status": 500,
  "title": "Internal Server Error",
  "type": "/errors/axyl-push/internal-error"
}