Sending an HTTP API request to Yandex Cloud Notification Service

The service's HTTP API is compatible with the Amazon SNS API.

You can find all the supported actions in the API reference.

To get started with the HTTP API using curl:

1. Get your cloud ready.
2. Get the authentication data.
3. Create a notification channel.
4. Get a list of channels.
5. Create an endpoint.
6. Send a notification.

Get your cloud ready

Sign up in Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or register a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Get the authentication credentials

For authentication in the API, use a static access key or IAM token.

See these guides on how to get an IAM token:

• Getting an IAM token for a Yandex account
• Getting an IAM token for a federated account
• Getting an IAM token for a service account

To make API requests, a user or service account must have at least the editor role for the folder.

Create a notification channel

export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data-urlencode "Action=CreatePlatformApplication" \
  --data-urlencode "ResponseFormat=JSON" \
  --data-urlencode "FolderId=<folder_ID>" \
  --data-urlencode "Name=<channel_name>" \
  --data-urlencode "Platform=GCM" \
  --data-urlencode "Attributes.entry.1.key=PlatformCredential" \
  --data-urlencode "Attributes.entry.1.value=<FCM_API_key>"
  "https://notifications.yandexcloud.net/"

Where:

• IAM_TOKEN: IAM token.

• Action: Operation type.

• ResponseFormat: Response format, JSON or XML.

• FolderId: Folder ID.

• Name: Notification channel name, user-defined.

  The name must be unique throughout CNS. Once the channel is created, you will not be able to change the name. The name may contain lowercase and uppercase Latin letters, numbers, underscores, hyphens, and periods. It must be from 1 to 256 characters long. For APNs channels, we recommend specifying the bundle ID in the name; for FCM and HMS, the full package name; for RuStore, packageName.

• Platform: Mobile platform type:

  • APNS and APNS_SANDBOX: Apple Push Notification service (APNs). Use APNS_SANDBOX to test the application.
  • GCM: Firebase Cloud Messaging (FCM).
  • HMS: Huawei Mobile Services (HMS).
  • RUSTORE: RuStore Android.

• Attributes.entry.N.key: Authentication attribute keys on the mobile platform. The values depend on the platform:

  • APNs:

    • Token-based authentication:
      • PlatformPrincipal: Token in .p8 format.
      • PlatformCredential: Token ID.
      • ApplePlatformTeamID: Developer ID.
      • ApplePlatformBundleID: Bundle ID.
    • Certificate-based authentication:
      • PlatformPrincipal: SSL certificate in .p12 format.
      • PlatformCredential: Certificate private key.

    Token-based authentication is preferred as a more modern option.

  • FCM: PlatformCredential is the Google Cloud service account key in JSON format for authentication with the HTTP v1 API or API key (server key) for authentication with the Legacy API.

    The HTTP v1 API is preferred as FCM will no longer support the Legacy API starting June 2024.

  • HMS:

    • PlatformPrincipal: Key ID.
    • PlatformCredential: API key.

  • RuStore:

    • PlatformPrincipal: Project ID (ProjectID).
    • PlatformCredential: Service token (ServiceToken).

• Attributes.entry.N.key: Authentication attribute keys on the mobile platform.

As a result, you will get a notification channel ID (ARN).

For more information, see CreatePlatformApplication.

Get a list of channels

export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data-urlencode "Action=ListPlatformApplications" \
  --data-urlencode "ResponseFormat=JSON" \
  --data-urlencode "FolderId=<folder_ID>" \
  "https://notifications.yandexcloud.net/"

Where:

• IAM_TOKEN: IAM token.
• Action: Operation type.
• ResponseFormat: Response format, JSON or XML.
• FolderId: Folder ID.

For more information, see ListPlatformApplications.

Create an endpoint

export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data-urlencode "Action=CreatePlatformEndpoint" \
  --data-urlencode "ResponseFormat=JSON" \
  --data-urlencode "PlatformApplicationArn=<notification_channel_ARN>" \
  --data-urlencode "Token=<push_token>" \
  "https://notifications.yandexcloud.net/"

Where:

• IAM_TOKEN: IAM token.
• Action: Operation type.
• ResponseFormat: Response format, JSON or XML.
• PlatformApplicationArn: Notification channel ID (ARN).
• Token: Unique push token for the app on the user’s device.

As a result, you will get a mobile endpoint ID (ARN).

For more information, see CreatePlatformEndpoint.

Send a notification

Explicit notifications (Bright Push)

export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data-urlencode "Action=Publish" \
  --data-urlencode "ResponseFormat=JSON" \
  --data-urlencode "TargetArn=<endpoint_ID>" \
  --data-urlencode "Message={"default": "<notification_text>", "GCM": "{ \"notification\": { \"body\": \"<notification_text>\"} }" }" \
  --data-urlencode "MessageStructure=json" \
  "https://notifications.yandexcloud.net/"

Where:

• IAM_TOKEN: IAM token.
• Action: Operation type.
• ResponseFormat: Response format, JSON or XML.
• TargetArn: Mobile endpoint ID (ARN).
• Message: Message.
• MessageStructure: Message format.

Silent notifications (Silent Push)

export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data-urlencode "Action=Publish" \
  --data-urlencode "ResponseFormat=JSON" \
  --data-urlencode "TargetArn=<endpoint_ID>" \
  --data-urlencode "Message={\"data\": { \"key\": \"value\" } }" \
  --data-urlencode "MessageStructure=json" \
  "https://notifications.yandexcloud.net/"

Where:

• IAM_TOKEN: IAM token.
• Action: Operation type.
• ResponseFormat: Response format, JSON or XML.
• TargetArn: Mobile endpoint ID (ARN).
• Message: Message.
• MessageStructure: Message format.

For more information, see Publish.