Sending push messages

Sends one or several push messages to the specified devices.

This operation allows you to send messages with different properties (e.g. text, media attachment, etc.) in a single HTTP request. Each request can contain up to 250,000 devices to which messages will be sent.

POST /push/v1/send-batch
Note. We recommend using this operation instead of the obsolete POST /push/v1/send.
  1. Request format
  2. Request body
  3. Response format

Request format

https://push.api.appmetrica.yandex.net/push/v1/send-batch

Request body

{
  "push_batch_request": {
    "group_id": 1,
    "client_transfer_id": long,
    "tag": "string",
    "batch": [
      {
        "messages": {
          "android": {
            "silent": false,
            "content": {
              "title": "string",
              "text": "string",
              "icon": "string",
              "icon_background": "#AARRGGBB",
              "image": "https://example.com/picture.jpg",
              "banner": "https://example.com/picture.jpg",
              "data": "string",
              "channel_id": "string",
              "priority": -2,
              "collapse_key": 2001,
              "vibration": [0, 500],
              "led_color": "#RRGGBB",
              "led_interval": 50,
              "led_pause_interval": 50,
              "time_to_live": 180
            },
            "open_action": {
              "deeplink": "yandexmaps://?"
            }
          },
          "iOS": {
            "silent": false,
            "content": {
              "title": "string",
              "text": "string",
              "badge": 1,
              "sound": "disable",
              "thread_id": "string",
              "category": "string",
              "mutable_content": 1,
              "expiration": 3600,
              "data": "string"
            },
            "open_action": {
              "url": "https://ya.ru"
            }
          }
        },
        "devices": [
          {
            "id_type": "appmetrica_device_id",
            "id_values": ["123456789", "42"]
          },
          {
            "id_type": "ios_ifa",
            "id_values": ["8A690667-6204-4A6A-9B38-85DE016....."]
          },
          {
            "id_type": "google_aid",
            "id_values": ["eb5f3ec8-2e3e-492f-b15b-d21860b....."]
          },
          {
            "id_type": "android_push_token",
            "id_values": ["eFfxdO7uCMw:APA91bF1tN3X3BAbiJXsQhk-..."]
          },
          {
            "id_type": "ios_push_token",
            "id_values": ["F6A79E9F844A24C5FBED5C58A4C71561C180F........."]
          }
        ]
      },
      {
        "messages": {
        ...
        }
      }
    ]
  }
}
push_batch_request
The request to send a group of push notifications.
group_id *
Group ID. Required parameter.
client_transfer_id
ID of the dispatch, specified by the user. It is used for checking the status of the dispatch.
Attention. The client_transfer_id value must be unique in the specified group (group_id).
tag *
The dispatch tag. Required parameter.
batch
Array of messages objects. It contains push messages with properties.
messages
Push message.
android
The device platform.
ios
The device platform.
silent
A flag that indicates silent push sending. Possible values: true | false.
content
The content of the push message.
title
The title of the push message. The value is mandatory for the non-silent push messages.
text
The text of the message. The value is mandatory for the non-silent push messages.
icon
The icon is shown in the notification bar. By default, the standard app icon is displayed. To change the icon, set the icon resource ID in the standard /res/drawable/ directory.
icon_background
The color of the message icon. It is specified as a string in the format of the hex code #AARRGGBB.

This field is available only for the Android platform.

image
The URL of the image which is displayed in the push message next to the notification text.
banner
The URL of the image that is shown in the push message.

This field is available only for the Android platform.

data
An arbitrary data string. You can pass any data you need as a string value. You can process the data string by using the appropriate AppMetrica Push SDK methods.
channel_id
ID of the notification channel. If the ID is not specified, the default channel is used.

Available for Android 8 or higher. For more information about channels, see Android documentation.

priority
Notification priority. Acceptable values are in the range of [-2; 2]. The platform determines the priority of messages and takes appropriate actions: interrupts the user (displays a message on the screen), or does not notify the user about the message. On different devices, priority is interpreted differently.

This field is available only for the Android platform.

collapse_key
Notification ID. The default value is 0. Ignored if there are no push notifications currently displayed for this application. If one or more notifications are displayed and the new message has the same notification ID, the content of this notification will be updated. If the ID is different, the new message is displayed.

This field is available only for the Android platform.

vibration
Vibration pattern on message arrival. Format: [pause in ms, duration of vibration in ms, pause in ms, duration of vibration in ms, ...].

This field is available only for the Android platform.

led_color
LED color. It is specified as a string in the format of the hex code #RRGGBB.

This field is available only for the Android platform.

led_interval
The duration of the glow of the LED indicator in ms.

This field is available only for the Android platform.

led_pause_interval
Pause time for the glow of the LED indicator in ms.

This field is available only for the Android platform.

time_to_live
The duration of the interval in seconds that FireBase will store the push message if the device is offline or out of range.

This field is available only for the Android platform.

open_action
The action to be taken when a user clicks on a push notification. If the field is empty, the user click opens the application.
deeplink
The deeplink with an application screen to take a user to after clicking on a push message.
badge
Badge number to be displayed on the application icon on message arrival.
sound
The message sound. Possible values: default | disable
thread_id

ID for grouping push notifications. The value is specified in the threadIdentifier property of the UNNotificationContent object.

category

Push notifications category. The value is specified in the identifier property of the UNNotificationCategory object. More information about push actions and categories in the Apple documentation.

mutable_content

Indicates Notification Service Extension. If the value is 1, the push notification is processed by the extension. AppMetrica uses it to track the delivery of push notifications.

To track the delivery, set up push notification statistics collection and pass 1 as a field value. If the value is omitted, the number of delivered push notifications in reports is equal to the number of opened messages.

expiration
The duration of time to continue trying to deliver the notification to the user's device. The value should be specified in seconds.

If this time expires and the device is still unavailable (for example, it doesn't have internet access), the notification isn't delivered. By default, the time is unrestricted.

url
The URL to go to when the push message is clicked.
devices
Devices to send push notifications to. Each dispatch of messages can contain up to 250,000 devices.

Devices are grouped by id_type. One sending can have from 1 to 5 groups. All groups can contain up to 250,000 devices in total in a single HTTP request. For example, if the appmetrica_device_id group contains 100,000 devices, only 150,000 can be specified in the others.

id_type
The type of the ID. Possible values: appmetrica_device_id, ios_ifa, google_aid, android_push_token, ios_push_token.
Note. When you use a push token as an identifier, AppMetrica checks the presence of a token and device information in the database before sending. If there is no device information, the push message is not sent. This is necessary to control sending messages to the desired addressees and display information in the reports.
id_values
List of devices to send push messages to.
Attention. The list can't be empty.

* Required

Response format

{
  "push_response": {
    "transfer_id": 1,
    "client_transfer_id": long
  }
}
push_response
The response after sending push messages.
transfer_id
ID of the dispatch. It is used for checking the status of the dispatch.
client_transfer_id
Sending ID, specified by the user in the body of the request. It is used for checking the status of the dispatch.
Note. The field is returned only if it was specified in the body of the request.