Register or Update a Campaign

Register a scheduled push campaign or update an existing campaign.

The Register or Update Campaign API uses server-to-server communication, called directly from the app server to the Hive Notification server. The id field in the request distinguishes creation from update: provide an id of 1 or greater to update an existing campaign, or omit it to register a new campaign.

Note

An OAuth 2.0 access token is required to use this API. If you already have a token, request only the additional permissions. See Issue an OAuth Token.

URL คำขอ

Production URL	https://notification.withhive.com/v2/push/campaigns https://notification.qpyou.cn/v2/push/campaigns
Sandbox URL	https://sandbox-notification.withhive.com/v2/push/campaigns https://sandbox-notification.qpyou.cn/v2/push/campaigns
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

ส่วนหัวคำขอ

Field	Description	Type	Required
X-Access-Token	OAuth 2.0 access token for app server authentication (see Issue an OAuth Token)	String	Y

Note

The JWT project_id must match game.gameid in the request body. This applies when using a project-type token. Every app specified in game.apps must belong to that game; if even one app does not meet this condition, the entire request fails.

เนื้อหาคำขอ

Field	Description	Type	Required
id	Campaign ID. Updates an existing campaign if 1 or greater; omitted to register a new campaign	Integer	N
status	Campaign status. For new campaigns, this field is ignored and the server sets it to 1. For updates, the provided value is saved as-is, so it must be included 0: Completed 1: Active or pending 3: Canceled	Integer	Conditional
description	Campaign description	String	Y
type	Send type B: Bulk push (send to all recipients) T: Targeting push	String	Y
targeting_id	Targeting ID. Required with a value of 1 or greater when type is T Returned by the Register Targeting Data API	Integer	Conditional
notice	Whether this is an announcement notification (default: true). See Announcement Notification Behavior	Boolean	N
reservation	Scheduled send settings. See Reservation structure	Object	Y
distribution	Send distribution settings. See Distribution structure	Object	N
countries	Country codes to target (at least one). See Country codes	Array	Y
game	Target game information. See Game structure	Object	Y
default_language	Default language code. See Language codes	String	Y
notification	Messages by language code (at least one). Each value follows the Message structure	Object	Y
option	Send options. See Option structure	Object	N

Reservation Structure

Field	Description	Type	Required
localizing	Whether to apply the user's local time zone true: Send according to the user's local time false: Send according to gmt_offset	Boolean	Y
start_date	Send start date (YYYY-MM-DD). Cannot be later than end_date	String	Y
end_date	Send end date (YYYY-MM-DD)	String	Y
time	Send time (HH:mm:00). Specify seconds as 00	String	Y
repeat	Whether to repeat sends during the scheduled period	Boolean	Y
weekday	Days of the week on which to repeat sending. See Weekday codes	Array	N
skip	Dates to skip during the repeat period (YYYY-MM-DD)	Array	N
gmt_offset	Offset from UTC for the reference time zone, in seconds. Must be between -43200 and 50400; defaults to 32400 (Korea Standard Time, KST)	Long	N

Weekday Codes

Code	Description
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday
7	Sunday

Distribution Structure

Field	Description	Type	Required
enable	Whether to enable distributed sending (default: false)	Boolean	N
count	Number of sends per interval	Integer	Conditional
interval	Interval length, in seconds	Integer	Conditional

Note

If enable is true, both count and interval must be greater than 0, and the send rate per second (count / interval) must be at least 50000.

Game Structure

Field	Description	Type	Required
gameid	Game ID	String	Y
server_ids	Server IDs to target. If specified, the push is sent only to users whose stored server ID matches; if omitted, no server filtering is applied	Array	N
apps	Apps to target (at least one)	Array	Y
apps[].appid	App ID	String	Y
apps[].versions	App versions to target. If omitted, all versions are targeted	Array	N

Note

Game and app indexes are not accepted in the request. The server looks them up using gameid and appid and includes them in the response.

Message Structure

Provide Android and iOS messages for each language code specified in notification.

Field	Description	Type	Required
android.title	Android notification title (up to 240 UTF-8 bytes)	String	Conditional
android.message	Android notification body (up to 420 UTF-8 bytes)	String	Conditional
android.message_expanded	Body displayed when the notification is expanded (up to 1,800 UTF-8 bytes)	String	N
android.image_url	Image URL displayed in the notification	String	N
android.ticker	Ticker text displayed when the notification arrives (up to 90 UTF-8 bytes)	String	N
android.summary_text	Summary text that briefly describes the body (up to 90 UTF-8 bytes)	String	N
ios.title	iOS notification title (up to 240 UTF-8 bytes)	String	Conditional
ios.message	iOS notification body (up to 420 UTF-8 bytes)	String	Conditional
ios.media_url	Media URL displayed in a rich notification	String	N

Note

notification must include a language-code key matching default_language. For each language, provide both title and message for at least one of Android or iOS.

Option Structure

Field	Description	Type	Required
badge	Number displayed on the app icon when a push is received (default: 1)	Integer	N
overwrite	Whether to enable Android push overwrite (default: false)	Boolean	N
collapse_key	Key used for push overwrite. Specify a number as a string (for example, "123")	String	N
comment	Description stored with a push overwrite	String	N
engagement	User engagement Scheme URL that the SDK executes when the push is tapped (for example, push://hive/...). Passed in the push payload's action field See Hive Scheme URL format	String	N
group_key	Group key used to display notifications together. Notification settings configured in the device OS apply by default See the iOS and Android documentation	String	N
android.icon	Image file name for the push notification icon. The image must be in the app's /src/main/res/drawable directory. See Android documentation for supported formats To use an image on the web, enter its URL instead of a file name If empty, the app icon is used	String	N
android.sound	Sound file name to play for the push notification. The file must be in the app's /src/main/res/raw directory If empty, the system default sound is used	String	N
android.priority	Priority of the message sent to Android devices (default: NORMAL). This FCM setting controls message delivery timing. See the Firebase guide NORMAL: Delivered immediately if the device is not in Doze mode; delivery may be delayed to save battery while the device is in Doze mode HIGH: Attempts immediate delivery and may wake the device from Doze mode if needed	String	N
ios.sound	Sound file name to play for the push notification. The file must be in the app container's Library/Sounds directory or the app's main bundle If empty, it is set to default and the system default sound is used	String	N

Request example

Register a New Campaign

{
  "description": "August returning-user campaign",
  "type": "T",
  "targeting_id": 1024,
  "notice": true,
  "reservation": {
    "localizing": false,
    "start_date": "2026-08-01",
    "end_date": "2026-08-01",
    "time": "10:00:00",
    "repeat": false,
    "gmt_offset": 32400
  },
  "countries": ["KR", "JP"],
  "game": {
    "gameid": "com.com2us.mygame",
    "apps": [
      {
        "appid": "com.com2us.mygame.normal.freefull.google.global.android.common"
      }
    ]
  },
  "default_language": "en",
  "notification": {
    "en": {
      "android": {
        "title": "Welcome back reward",
        "message": "Check your mailbox."
      },
      "ios": {
        "title": "Welcome back reward",
        "message": "Check your mailbox."
      }
    }
  },
  "option": {
    "badge": 1
  }
}

Update an Existing Campaign

{
  "id": 8821,
  "status": 1,
  "description": "August returning-user campaign (updated)",
  "type": "B",
  "reservation": {
    "localizing": false,
    "start_date": "2026-08-02",
    "end_date": "2026-08-02",
    "time": "11:00:00",
    "repeat": false,
    "gmt_offset": 32400
  },
  "countries": ["KR"],
  "game": {
    "gameid": "com.com2us.mygame",
    "apps": [
      {
        "appid": "com.com2us.mygame.normal.freefull.google.global.android.common"
      }
    ]
  },
  "default_language": "en",
  "notification": {
    "en": {
      "android": {
        "title": "Welcome back reward",
        "message": "Check your mailbox."
      }
    }
  }
}

เนื้อหาการตอบกลับ

Field	Description	Type
result_code	Response code. Details	Integer
result_msg	Result message	String
token_validation	JWT validation result (JWT validation errors)	Object
token_validation.result_code	JWT validation result code	Integer
token_validation.result_msg	JWT validation result message	String
data.uuid	Request tracking ID	String
data.id	Campaign ID; generated by the server for a new campaign	Integer
data.status	Campaign status	Integer
data.modify	Whether the campaign can be modified. Cannot be set in the request; always true for campaigns saved through this API	Boolean
data.type	Send type	String
data.notice	Whether this is an announcement notification	Boolean
data.description	Campaign description	String
data.targeting_id	Targeting ID. 0 if type is not T	Integer
data.is_analytics	Whether this is an analytics campaign. Always false for campaigns saved through this API	Boolean
data.reservation	Scheduled send settings	Object
data.distribution	Send distribution settings	Object
data.countries	Country codes targeted for sending	Array
data.last_end_time	Time when the campaign's final send ends, in seconds. The largest end_time in data.tasks; the server marks the campaign as completed after this time	Long
data.last_end_timestamp	Time when the campaign's final send ends, as UTC epoch seconds. The largest end_timestamp in data.tasks	Long
data.tasks	Send tasks calculated by the server from the schedule. See Task structure	Object
data.game	Target game information, populated with the game_index and app_index looked up by the server	Object
data.default_language	Default language code	String
data.notification	Messages by language code	Object
data.option	Send options	Object
data.registrant	Registrant. Always SYSTEM for campaigns registered through this API	Object
data.timestamp	Save time. date is a string and time is epoch milliseconds	Object

Task Structure

tasks is an object whose keys are send-time strings (HH:mm:00) and whose values have the structure below. Countries scheduled for the same time are grouped into one task.

Field	Description	Type
time	Send time (HH:mm:00), matching the object key	String
gmt_offset	Offset from UTC for the time zone applied to this task, in seconds	Long
zones	Time zone names of the countries grouped into this task	Array
start_time	Send start time converted to Korea Standard Time (KST). Calculated by adding the KST offset (32400) to start_timestamp	Long
end_time	Send end time converted to Korea Standard Time (KST). Calculated by adding the KST offset (32400) to end_timestamp	Long
start_timestamp	Send start time as UTC epoch seconds	Long
end_timestamp	Send end time as UTC epoch seconds	Long

Note

If reservation.localizing is false, reservation.gmt_offset applies to all countries, so they are grouped into one task. If true, tasks are split by each country's local time zone, and countries with the same offset are grouped together in zones.

รหัสการตอบกลับ

Code	Description
0	Success
1400	Invalid request A required field is missing A date or time has an invalid format type is T and targeting_id is less than 1 The requested gameid or appid does not exist notification does not contain a language-code key matching default_language The message in notification is incomplete for both Android and iOS A message exceeds the maximum byte length for a field The campaign cannot be updated because sending has already started
1401	No permission for the requested app
1500	Internal server error
2499	JWT validation failed (see token_validation)

ตัวอย่างการตอบกลับ

สำเร็จ

{
  "result_code": 0,
  "result_msg": "success",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  },
  "data": {
    "uuid": "2f8c1b90-4a77-4d31-9c6e-1b0e5a7d3c42",
    "id": 9001,
    "status": 1,
    "modify": true,
    "type": "B",
    "description": "test",
    "targeting_id": 0,
    "is_analytics": false,
    "default_language": "en",
    "reservation": {
      "localizing": false,
      "start_date": "2026-08-01",
      "end_date": "2026-09-25",
      "time": "05:10:00",
      "repeat": true,
      "weekday": [3, 4, 5],
      "gmt_offset": 32400
    },
    "countries": ["KR", "SE"],
    "last_end_time": 1790313000,
    "last_end_timestamp": 1790280600,
    "tasks": {
      "05:10:00": {
        "time": "05:10:00",
        "gmt_offset": 32400,
        "zones": ["Asia/Seoul", "Europe/Stockholm"],
        "start_time": 1785561000,
        "end_time": 1790313000,
        "start_timestamp": 1785528600,
        "end_timestamp": 1790280600
      }
    },
    "game": {
      "gameid": "com.com2us.mygame",
      "game_index": 1234,
      "apps": [
        {
          "app_index": 5001,
          "appid": "com.com2us.mygame.normal.freefull.google.global.android.common"
        }
      ]
    },
    "notification": {
      "en": {
        "android": {
          "title": "test",
          "message": "test"
        },
        "ios": {
          "title": "test",
          "message": "test"
        }
      }
    },
    "option": {
      "badge": 1
    },
    "registrant": {
      "id": "SYSTEM",
      "name": "SYSTEM"
    },
    "timestamp": {
      "date": "2026-07-31 18:57:23.193",
      "time": 1785491843193
    }
  }
}

ล้มเหลว

{
  "result_code": 1400,
  "result_msg": "description field is required.",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  }
}

การตรวจสอบ JWT ล้มเหลว

{
  "result_code": 2499,
  "result_msg": "JWT validation failed.",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "The access token is expired. Please refresh your token."
  }
}

Country Codes

The following country codes can be used in countries.

Continent	Country	Code	Country	Code
Africa	Angola	AO	Madagascar	MG
	Burkina Faso	BF	Mali	ML
	Burundi	BI	Mauritania	MR
	Benin	BJ	Mauritius	MU
	Botswana	BW	Malawi	MW
	Democratic Republic of the Congo	CD	Mozambique	MZ
	Central African Republic	CF	Namibia	NA
	Republic of the Congo	CG	Niger	NE
	Ivory Coast	CI	Nigeria	NG
	Cameroon	CM	Reunion	RE
	Cape Verde	CV	Rwanda	RW
	Djibouti	DJ	Seychelles	SC
	Algeria	DZ	Sudan	SD
	Egypt	EG	Saint Helena	SH
	Western Sahara	EH	Sierra Leone	SL
	Eritrea	ER	Senegal	SN
	Ethiopia	ET	Somalia	SO
	Gabon	GA	South Sudan	SS
	Ghana	GH	Sao Tome and Principe	ST
	Gambia	GM	Swaziland	SZ
	Guinea	GN	Chad	TD
	Equatorial Guinea	GQ	French Southern Territories	TF
	Guinea-Bissau	GW	Togo	TG
	British Indian Ocean Territory	IO	Tunisia	TN
	Kenya	KE	Tanzania	TZ
	Comoros	KM	Uganda	UG
	Liberia	LR	Mayotte	YT
	Lesotho	LS	South Africa	ZA
	Libya	LY	Zambia	ZM
	Morocco	MA	Zimbabwe	ZW
Americas	Antigua and Barbuda	AG	Honduras	HN
	Anguilla	AI	Haiti	HT
	Argentina	AR	Jamaica	JM
	Aruba	AW	Saint Kitts and Nevis	KN
	Barbados	BB	Cayman Islands	KY
	Saint Barthélemy	BL	Saint Lucia	LC
	Bermuda	BM	Saint Martin	MF
	Bolivia	BO	Martinique	MQ
	Bonaire, Saint Eustatius and Saba	BQ	Montserrat	MS
	Brazil	BR	Mexico	MX
	Bahamas	BS	Nicaragua	NI
	Belize	BZ	Panama	PA
	Canada	CA	Peru	PE
	Chile	CL	Saint Pierre and Miquelon	PM
	Colombia	CO	Puerto Rico	PR
	Costa Rica	CR	Paraguay	PY
	Cuba	CU	Suriname	SR
	Curaçao	CW	El Salvador	SV
	Dominica	DM	Sint Maarten	SX
	Dominican Republic	DO	Turks and Caicos Islands	TC
	Ecuador	EC	Trinidad and Tobago	TT
	Falkland Islands	FK	United States Minor Outlying Islands	UM
	Grenada	GD	United States	US
	French Guiana	GF	Uruguay	UY
	Greenland	GL	Saint Vincent and the Grenadines	VC
	Guadeloupe	GP	Venezuela	VE
	South Georgia and the South Sandwich Islands	GS	British Virgin Islands	VG
	Guatemala	GT	U.S. Virgin Islands	VI
	Guyana	GY
Asia	United Arab Emirates	AE	Lebanon	LB
	Afghanistan	AF	Sri Lanka	LK
	Armenia	AM	Myanmar	MM
	Azerbaijan	AZ	Mongolia	MN
	Bangladesh	BD	Macao	MO
	Bahrain	BH	Maldives	MV
	Brunei	BN	Malaysia	MY
	Bhutan	BT	Nepal	NP
	China	CN	Oman	OM
	Georgia	GE	Philippines	PH
	Hong Kong	HK	Pakistan	PK
	Indonesia	ID	Palestinian Territory	PS
	Israel	IL	Qatar	QA
	India	IN	Saudi Arabia	SA
	Iraq	IQ	Singapore	SG
	Iran	IR	Syria	SY
	Jordan	JO	Thailand	TH
	Japan	JP	Tajikistan	TJ
	Kyrgyzstan	KG	East Timor	TL
	Cambodia	KH	Turkmenistan	TM
	North Korea	KP	Turkey	TR
	South Korea	KR	Taiwan	TW
	Kuwait	KW	Uzbekistan	UZ
	Kazakhstan	KZ	Vietnam	VN
	Laos	LA	Yemen	YE
Europe	Andorra	AD	Iceland	IS
	Albania	AL	Italy	IT
	Austria	AT	Jersey	JE
	Aland Islands	AX	Liechtenstein	LI
	Bosnia and Herzegovina	BA	Lithuania	LT
	Belgium	BE	Luxembourg	LU
	Bulgaria	BG	Latvia	LV
	Belarus	BY	Monaco	MC
	Switzerland	CH	Moldova	MD
	Cyprus	CY	Montenegro	ME
	Czech Republic	CZ	Macedonia	MK
	Germany	DE	Malta	MT
	Denmark	DK	Netherlands	NL
	Estonia	EE	Norway	NO
	Spain	ES	Poland	PL
	Finland	FI	Portugal	PT
	Faroe Islands	FO	Romania	RO
	France	FR	Serbia	RS
	United Kingdom	GB	Russia	RU
	Guernsey	GG	Sweden	SE
	Gibraltar	GI	Slovenia	SI
	Greece	GR	Svalbard and Jan Mayen	SJ
	Croatia	HR	Slovakia	SK
	Hungary	HU	San Marino	SM
	Ireland	IE	Ukraine	UA
	Isle of Man	IM	Vatican	VA
Oceania	American Samoa	AS	Niue	NU
	Australia	AU	New Zealand	NZ
	Cocos Islands	CC	French Polynesia	PF
	Cook Islands	CK	Papua New Guinea	PG
	Christmas Island	CX	Pitcairn	PN
	Fiji	FJ	Palau	PW
	Micronesia	FM	Solomon Islands	SB
	Guam	GU	Tokelau	TK
	Kiribati	KI	Tonga	TO
	Marshall Islands	MH	Tuvalu	TV
	Northern Mariana Islands	MP	Vanuatu	VU
	New Caledonia	NC	Wallis and Futuna	WF
	Norfolk Island	NF	Samoa	WS
	Nauru	NR
Polar	Antarctica	AQ

รหัสภาษา

The following language codes can be used for default_language and the keys in notification.

Language code	Language
ko	Korean
zh-hans	Simplified Chinese
zh-hant	Traditional Chinese
en	English
ja	Japanese
ar	Arabic
fr	French
de	German
es	Spanish
pt	Portuguese
th	Thai
it	Italian
ru	Russian
id	Indonesian
vi	Vietnamese
tr	Turkish
tl	Filipino

พฤติกรรมการแจ้งเตือนประกาศ

Announcement notifications are sent only to app users who have agreed to receive them.

• If a user has not agreed to receive announcement notifications, messages with notice set to true are not sent to that user.
• If the send time falls during nighttime hours (21:00–08:00 the following day), the user must also have agreed to receive nighttime notifications.

Warning

When sending announcement notifications to users in Korea, follow Article 50 of Korea's Network Act, which treats them as advertising messages. Advertising notifications must include a label identifying the message as an advertisement and instructions for opting out.

• Example advertising notification: (Ad) {message_body} (To opt out: change your settings)

Note

If JWT validation fails, check the token_validation field for details. See JWT validation error codes.