Push notification management

Push notifications allow you to broadcast app-wide announcements to all or selected users. This page explains how to use Chat RESTful APIs to send and configure push notifications.

Authorization

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following Authorization field must be filled in the request header:

Authorization: Bearer ${YourAppToken}

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see Authentication using App Token.

Send push notifications

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

Parameter	Type	Description	Required
`host`	String	The domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.	Yes
`org_name`	String	The unique identifier assigned to each company (organization) by the Chat service. For how to get the organization name, see Get the information of the Chat project.	Yes
`app_name`	String	The unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of the Chat project.	Yes
`username`	String	The unique login account of the user.	Yes

Response parameters

Parameter	Type	Description
`timestamp`	Number	The Unix timestamp (ms) of the HTTP response.
`duration`	Number	The duration (ms) from when the HTTP request is sent to the time the response is received.

Send push notifications by users

Sends push notifications to one or more users by specifying user IDs.

HTTP request

POST https://{host}/{org_name}/{app_name}/push/single

Path parameters

For the descriptions of path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

Parameter	Type	Description	Required
`targets`	List	The targeting user IDs. You can pass one user at most for synchronous push and a maximum of 100 users for asynchronous push.	Yes
`async`	Boolean	Whether to implement a synchronous or asynchronous push: `true`: (Default) Push asynchronously to a maximum of 100 users. `false`: Push synchronously to one user at most. You can send push notifications to multiple users (set `targets` to more than one user ID) only if you set `async` to `true`.	No
`strategy`	Number	The push strategies. `0`: Use third-party push service first. When the pushing attempt fails, use Agora push service instead. `1`: Use Agora push service only. If the target user is offline, Agora retains the push message for a certain period, depending on the Chat package to which you subscribe. After the retention period, the push message is dropped and the push attempt fails. `2`: (Default) Use third-party push service only. If the target user is offline, whether to retain the push message and the retention period of the push message depend on the setting of the third-party service. If the push attempt fails, the message is discarded. `3`: Use Agora push service first. When the pushing attempt fails, use third-party push service instead.	No
`pushMessage`	JSON	The push messages. See Set push notifications for details.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The push result.
`id`	String	The targeting user ID.
`pushStatus`	String	The push status: `SUCCESS`: The push succeeds. `FAIL`: The push fails due to non-server errors. For example, an invalid token is passed. `ERROR`: The push fails due to server errors. For example, the request times out. `ASYNC_SUCCESS`: The asynchronous push succeeds.
`desc`	String	The result description.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -X POST "http://localhost:8099/agora-demo/testy/push/single" -H "Authorization: Bearer YWMtOzQVjJ3mEeuJQv1qXhB5QAAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF41YIKUABPGgDuIZeu5IMVC_M9G5JlTjUsZeYVSg5o8BwshLgWveZxjA" -H "Content-Type: application/json" --data-raw "{
    \"targets\": [
        \"test2\"
    ],
    \"pushMessage\": {
        \"title\": \"Hello\",
        \"subTitle\": \"Hello\",
        \"content\": \"Hello\",
        \"vivo\": {
        }
    }
}"

Response example

{
    "timestamp": 1619506344007,
    "data": [
        {
            "id": "test2",
            "pushStatus": "ASYNC_SUCCESS",
            "desc": "async success."
        }
    ],
    "duration": 14
}

Send push notifications by labels

Sends push notifications to all users under one label, or the intersection of users under multiple labels.

A push task is automatically created per request, and the ID of the push task is returned for data statistics.

See Set push labels for configuring labels.

HTTP request

POST https://{host}/{org_name}/{app_name}/push/list/label

Path parameter

For the descriptions of path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

Parameter	Type	Description	Required
`targets`	List	The targeting label names. You can either pass one label to send push notifications to all users under the label, or pass a maximum of three labels to send push notifications to the intersection of users under these labels.	Yes
`strategy`	Number	The push strategies. `0`: Use third-party push service first. When the pushing attempt fails, use Agora push service instead. `1`: Use Agora push service only. If the target user is offline, Agora retains the push message for a certain period, depending on the Chat package to which you subscribe. After the retention period, the push message is dropped and the push attempt fails. `2`: (Default) Use third-party push service only. If the target user is offline, whether to retain the push message and the retention period of the push message depend on the setting of the third-party service. If the push attempt fails, the message is discarded. `3`: Use Agora push service first. When the pushing attempt fails, use third-party push service instead.	No
`pushMessage`	JSON	The push messages. See Set push notifications for details.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The detailed information of the push task.
`taskId`	Number	The ID of the push task.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X POST 'http://a1-hsb.agora.com/agora-demo/easeim/push/list/label' \
-H 'Authorization: Bearer YWMtIPBHKsOyEeAAAAAAAAAAAExCXvf5bRGAJBgXNYFJVQ9AQMAAAGAWu67KQBPGgBOV9ghkGKbtt9H9b1' \
-H 'Content-Type: application/json' \
--data-raw '{
    "targets": [
        "post-90s"
    ],
    "strategy": 2,
    "pushMessage": {
        "title": "Agora PUSH",
        "content": "Welcome to Agora Push Service",
        "sub_title": "Agora"
    }
}'

Response example

{
    "timestamp": 1650859482843,
    "data": {
        "taskId": 968120369184112182
    },
    "duration": 0
}

Send push notifications to all users under the app

Sends push notifications to all users under the app.

A push task is automatically created per request, and the ID of the push task is returned for data statistics.

HTTP request

POST https://{host}/{org_name}/{app_name}/push/task

Path parameter

For the descriptions of path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

Parameter	Type	Description	Required
`strategy`	Number	The push strategies. `0`: Use third-party push service first. When the pushing attempt fails, use Agora push service instead. `1`: Use Agora push service only. If the target user is offline, Agora retains the push message for a certain period, depending on the Chat package to which you subscribe. After the retention period, the push message is dropped and the push attempt fails. `2`: (Default) Use third-party push service only. If the target user is offline, whether to retain the push message and the retention period of the push message depend on the setting of the third-party service. If the push attempt fails, the message is discarded. `3`: Use Agora push service first. When the pushing attempt fails, use third-party push service instead.	No
`pushMessage`	JSON	The push messages. See Set push notifications for details.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	Number	The ID of the push task.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -X POST "http://a1-hsb.agora.com/agora-demo/testy/push/task" -H "Content-Type: application/json" --data-raw "{
    \"pushMessage\": {
        \"title\": \"Hello1234\",
        \"subTitle\": \"Hello\",
        \"content\": \"Hello\",
        \"vivo\": {}
    }
}"

Response example

{
    "timestamp": 1618817591755,
    "data": 968120369184112182,
    "duration": 1
}

Status codes

For details, see HTTP Status Codes.

Configure push notifications

Chat not only provides basic configurations that are adaptive to all, but also supports advanced configurations varied by service providers. You can choose the service provider and configure the notification fields based on your business requirements.

A push notification example is as follows:

{
  // Basic configurations available to all
  "title": "You have a message",
  "subTitle": "",
  "content": "Check the message",
  "ext": {},
  "config": {
    "clickAction": {
      "url":"",
      "action":"",
      "activity":""
    },
    "badge": {
      "addNum": 0,
      "setNum": 0
      }
  },
  // Advanced configurations varied by service providers
  "agora":{},
  "apns": {},
  "fcm": {}
}

Basic configurations

The following table lists basic configuration fields available to all:

Field	Type	Description	Supported platforms	Required
`title`	String	The title of the notification. The value of this field is "You have a message" by default. The length of this field cannot exceed 32 characters.	Android & iOS	Yes
`subTitle`	String	The subtitle of the notification that provides additional information. The length of this field cannot exceed 10 characters.	iOS	No
`content`	String	The body text of the notification. The value of this field is "Check the message" by default. The length of this field cannot exceed 100 characters.	Android & iOS	Yes
`ext`	JSON	The custom extension of the notification stored in key-value pairs. The number of key-value pairs can be a maximum of 10, and the total length of key-value pairs can be 1024 characters at most.	Android & iOS	No
`config`	JSON	The configuration of click action and badge value in the notifications center.	Android & iOS	No
`config.clickAction`	JSON	The action triggered by a user click on the notification, which contains the following fields: `url`: Direct to a URL. Specify a custom URL; otherwise, the user click on notifications cannot work as expected. `action`: Open a specific page in the app. Specify the address of an in-app page. Open a package or an Activity component. Specify a package name or component path.	Android	No
`config.badge`	JSON	The value of the badge displayed on the app’s icon, which contains the following fields (Int): `addNum`: The new notification adds on the badge number. `setNum`: The new notification resets the badge number.	iOS & Android

Advanced configurations

If the basic configuration fields stated above cannot meet your business requirements, Chat allows you to implement advanced configurations provided by the following push services. All messages can be pushed via the three channels, regardless of whether users are online or offline. For how to choose to use the three push services, see the strategy parameter in Send push notifications.

Field	Type	Description	Required
`agora`	JSON	The Agora push service.	No
`apns`	JSON	Apple Push Notification service (APNs).	No
`fcm`	JSON	Firebase Cloud Messaging (FCM).	No

Advanced configurations overwrite the basic ones by default.

Agora push service

An Agora push notification example is as follows:

{
    "title": "The title of the notification",
    "content": "The body text of the notification",
    "subTitle": "The subtitle of the notification",
    "iconUrl": "https://web-cdn.agora.io/docs-files/1676966850073",
    "needNotification": true,
    "badge": {
        "setNum": 0,
        "addNum": 1,
        "activity": "com.hyphenate.chat.section.me.activity.AboutHxActivity"
    },
    "operation": {
        "type": "2",
        "openUrl": "https://www.baidu.com/",
        "openAction": "com.hyphenate.chat.section.me.activity.OfflinePushSettingsActivity"
    },
    "channelId": "chat",
    "channelName": "message",
    "channelLevel": 3,
    "autoCancel": 1,
    "expiresTime": 3600000,
    "sound": 0,
    "vibrate": 0,
    "style": 2,
    "bigTxt": "Big text content",
    "bigPicture": "https://web-cdn.agora.io/docs-files/1676966850073",
    "id": 056734579
}

The following table lists advanced configuration fields provided by Agora:

Field	Type	Description	Supported platforms
`title`	String	The title of the notification.	iOS & Android
`content`	String	The body text of the notification.	iOS & Android
`subTitle`	String	The subtitle of the notification that provides additional information.	iOS
`iconUrl`	String	The URL of the app icon.	iOS & Android
`needNotification`	Boolean	Wether a notification pops out: `true`: (Default) Yes. `false`: No.	iOS & Android
`badge`	JSON	The value of the badge displayed on the app’s icon, which contains the following fields: `addNum`: The new notification adds on the badge number. `setNum`: The new notification resets the badge number.	iOS & Android
`operation`	JSON	The action triggered by a user click on the notification.	iOS & Android
`operation.type`	Number	The type of the action. `0`: (Default) Launch the app. `1`: Direct to a URL. Set `operation.openUrl` to a custom URL; otherwise, the user click on notifications cannot work as expected. `2`: Open a specific page in the app. Set `operation.openAction` to the address of the in-app page, and set `operation.openActivity` to the package name or component path; otherwise, the user click on notifications cannot work as expected.	iOS & Android
`channelId`	String	The channel ID of the notification. The default value is `chat`. If this parameter is not specified or does not exist, a channel ID is automatically created using `channelName` and `channelLevel`.	Android
`channelName`	String	The name of the channel. The default value is `message`. This parameter is used to generate the channel ID.	Android
`channelLevel`	Number	The level of the channel. `0`: Low. `3`: (Default) Medium. `4`: High. This parameter is used to generate the channel ID.	Android
`autoCancel`	Number	Whether the notification center is automatically closed after the user click on notifications. `0`: No `1`: (Default) Yes	Android
`expiresTime`	Number	The Unix timestamp (ms) when the notification expires and disappears from the notification center.	iOS & Android
`sound`	Number	Whether a sound plays when the device receives notifications. `0`: (Default) No `1`: Yes	iOS & Android
`vibrate`	Number	Whether a vibration occurs when the device receive notifications. `0`: (Default) No `1`: Yes	iOS & Android
`style`	Number	The style of the notification. `0`: (Default) Normal style. `1`: Big test style. `2`: Big image style.	iOS & Android
`bigTxt`	String	The text content. This field is required when `style` is set to `1`.	iOS & Android
`bigPicture`	String	The image URL. This field is required when `style` is set to `2`.	Android
`id`	Number	The ID of the notification. A random number assigned by the Chat service. Chat automatically assigns a random number for each notification by default. If you manually specify this parameter to a value same as a previous ID, the previous notification is overwritten by the new one.	iOS & Android

APNs

The mapping of field names between Chat and APNs is as follows:

Chat	APNs
`invalidationTime`	`apns-expiration`
`priority`	`apns-priority`
`pushType`	`apns-push-type`
`collapseId`	`apns-collapse-id`
`apnsId`	`apns-id`
`badge`	`badge`
`sound`	`sound`
`mutableContent`	`mutable-content`
`contentAvailable`	`content-available`
`categoryName`	`category`
`threadId`	`thread-id`
`title`	`title`
`subTitle`	`subtitle`
`content`	`body`
`titleLocKey`	`title-loc-key`
`titleLocArgs`	`title-loc-args`
`subTitleLocKey`	`subtitle-loc-key`
`subTitleLocArgs`	`subtitle-loc-args`
`bodyLocKey`	`localizedAlertKey`
`bodyLocArgs`	`loc-key`
`ext`	`loc-args`
`launchImage`	`launch-image`

For descriptions of these fields, see APNs official documentation below:

FCM

The mapping of field names between Chat and FCM is as follows:

Chat	FCM
`condition`	`condition`
`collapseKey`	`collapse_key`
`priority`	`priority`
`timeToLive`	`time_to_live`
`dryRun`	`dry_run`
`restrictedPackageName`	`restricted_package_name`
`data`	`data`
`notification`	`notification`
`notification.title`	`notification.title`
`notification.body`	`notification.body`
`notification.androidChannelId`	`notification.android_channel_id`
`notification.sound`	`notification.sound`
`notification.tag`	`notification.tag`
`notification.color`	`notification.color`
`notification.clickAction`	`notification.click_action`
`notification.titleLocKey`	`notification.title_loc_key`
`notification.titleLocArgs`	`notification.title_loc_args`
`notification.bodyLocKey`	`notification.body_loc_key`
`notification.bodyLocArgs`	`notification.body_loc_args`

For descriptions of these fields, see FCM official documentation: Firebase Cloud Messaging HTTP protocol.

Set push labels

The push service allows you to group targeting users by configuring labels. Each label marks a user group that has similar habits, hobbies, or characteristics. When sending notifications, you can implement a bespoke push by specifying relevant labels, and the messages can then be sent to the users under the labels. For example, you can label a group of users as fashion trendsetters, and push related information about domestic and foreign trend brands to that user group on a regular basis.

You can manage the labels through RESTful API. The relationship between users and labels is many to many, that is, one user can have multiple labels and one label can also have multiple users. You can update the labels without any delay and change user labels by first removing users from their current label and then adding them to a new one.

Before calling the following methods, ensure that you understand the call frequency limit of the Chat RESTful APIs as described in Limitations.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

Parameter	Type	Description	Required
`host`	String	The domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.	Yes
`org_name`	String	The unique identifier assigned to each company (organization) by the Chat service. For how to get the organization name, see Get the information of the Chat project.	Yes
`app_name`	String	The unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of the Chat project.	Yes
`username`	String	The unique login account of the user.	Yes

Response parameters

Parameter	Type	Description
`timestamp`	Number	The Unix timestamp (ms) of the HTTP response.
`duration`	Number	The duration (ms) from when the HTTP request is sent to the time the response is received.

Create a push label

Creates a push label.

You can create a maximum of 100 push labels. To lift the upper limit, contact support@agora.io.

HTTP request

POST https://{host}/{org_name}/{app_name}/push/label

Path parameter

For the descriptions of path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

Parameter	Type	Description	Required
`name`	String	The name of the push label. The length of each label name cannot exceed 64 characters, and the following character sets are supported: 26 lowercase English letters (a-z) 26 uppercase English letters (A-Z) 10 numbers (0-9) "_", "-", "." The label name is case insensitive, so "Aa" and "aa" are the same label. Ensure that each label name under the same app is unique.	Yes
`description`	String	The description of the push label. The length of the label description cannot exceed 255 characters.	No

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The detailed information of the push label.
`name`	String	The label name.
`description`	String	The label description.
`createdAt`	Number	The Unix timestamp (ms) when the push label was created.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X POST 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name":"post-90s",
    "description":"hah"
}'

Response example

{
    "timestamp": 1648720341157,
    "data": {
        "name": "post-90s",
        "description": "hah",
        "createdAt": 1648720341118
    },
    "duration": 13
}

Query the detailed information of a push label

Retrieves the detailed information of the specified push label.

HTTP request

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes

For the descriptions of other path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The detailed information of the push label.
`name`	String	The label name.
`description`	String	The label description.
`count`	Number	The number of the users added to the push label.
`createdAt`	Number	The Unix timestamp (ms) when the push label was created.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X GET 'localhost/hx/hxdemo/push/label/90' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

Response example

{
    "timestamp": 1648720562644,
    "data": {
        "name": "90",
        "description": "hah",
        "count": 0,
        "createdAt": 1648720341118
    },
    "duration": 0
}

Query the detailed information of push labels by page

Retrieves the detailed information of multiple push labels by page.

HTTP request

GET https://{host}/{org_name}/{app_name}/push/label

Path parameter

For the descriptions of the other path parameters, see Common parameters.

Query parameters

Parameter	Type	Description	Required
`limit`	Number	The number of push labels displayed per page. The range is [1,100]. The default value is `100`.	No
`cursor`	String	The start position for the next query.	No

Request header

Parameter	Type	Description	Required
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON Array	The detailed information of the push label.
`name`	String	The label name.
`description`	String	The label description.
`count`	Number	The number of the users added to the push label.
`createdAt`	Number	The Unix timestamp (ms) when the push label was created.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X GET 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

Response example

{
    "timestamp": 1648720425599,
    "data": [
        {
            "name": "post-90s",
            "description": "hah",
            "count": 0,
            "createdAt": 1648720341118
        },
        {
            "name": "post-80s",
            "description": "post-80s generation",
            "count": 0,
            "createdAt": 1647512525642
        }
    ],
    "duration": 1
}

Delete a push label

Deletes the specified push label. You can delete one push label at each call.

HTTP request

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes

For the descriptions of the other path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	String	The request result. `success` indicates that the delete operation proceeds properly.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

Response example

{
    "timestamp": 1648721097405,
    "data": "success",
    "duration": 0
}

Add users to a push label

Adds one or more users to the specified push label. A maximum of 200,000 users can be added to a push label. To lift the upper limit, contact support@agora.io.

You can add a maximum of 100 users at each call.

HTTP request

POST https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes

For the descriptions of the other path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

Parameter	Type	Description	Required
`usernames`	List	The IDs of the users to be added to the push label. You can pass a maximum of 100 users for each request.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The request result.
`success`	List	The user IDs properly added to the push label.
`fail`	JSON	If add operations fail, the user IDs failed to be added and the corresponding failure reasons are returned in key-value pairs.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X POST 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "usernames":["hx1","hx2"]
}'

Response example

{
    "timestamp": 1648721496345,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 18
}

Query the specified user under the specified push label

Retrieves the detailed information of the specified user under the specified push label.

HTTP request

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user/{member}

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes
`member`	String	The ID of the user.	Yes

For the descriptions of the other path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`data`	JSON	The detailed information of the user.
`username`	String	The user ID.
`created`	Number	The Unix timestamp (ms) when the user was added to the push label.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user/hx1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

Response example

{
    "timestamp": 1648721589676,
    "data": {
        "username": "hx1",
        "created": 1648721496324
    },
    "duration": 1
}

Query the detailed information of users under the specified push label by page

Retrieves the detailed information of one or more users under the specified push label by page.

HTTP request

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes

For the descriptions of the other path parameters, see Common parameters.

Query parameters

Parameter	Type	Description	Required
`limit`	String	The number of the users displayed per page. The range is [1,100]. The default value is `100`.	No
`cursor`	String	The start position for the next query.	No

Request header

Parameter	Type	Description	Required
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Parameter	Type	Description
`cursor`	String	The start position for the next query.
`data`	JSON Array	The detailed information of the users.
`username`	String	The user ID.
`created`	Number	The Unix timestamp (ms) when the user was added to the push label.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user?limit=1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

Response example

{
    "timestamp": 1648721736670,
    "cursor": "ZWFzZW1vYjpwdXNoOmxhYmVsOmN1cnNvcjo5NTkxNTMwMDM4ODQxMzgwMjc",
    "data": [
        {
            "username": "hx1",
            "created": 1648721496324
        }
    ],
    "duration": 1
}

Remove users from a push label

Removes one or more users from the specified push label. You can remove a maximum of 100 users at each call.

HTTP request

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

Path parameter

Parameter	Type	Description	Required
`labelname`	String	The name of the push label.	Yes

For the descriptions of the other path parameters, see Common parameters.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	The content type. Set it as `application/json`.	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Parameter	Type	Description
`data`	JSON	The request result.
`success`	List	The user IDs properly removed from the push label.
`fail`	JSON	If remove operations fail, the user IDs failed to be removed and the corresponding failure reasons are returned in key-value pairs.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "usernames":["hx1","hx2"]
}'

Response example

{
    "timestamp": 1648722018636,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 1
}

Status codes

For details, see HTTP Status Codes.

Common parameters​

Basic configurations​

Common parameters​

Common parameters

Basic configurations

Common parameters