Push notifications

Stream sends push notifications through Firebase Cloud Messaging (FCM), Apple Push Notification service (APN), Huawei Push and Xiaomi Push. Push providers, device registration and push preferences work the same way across products and are managed with the same APIs. Each product decides which events send a push and what the notification contains; those rules and templates are documented with each product.

Setting Up Push

Push is available to Stream integrations running in a mobile environment. Setting it up takes three steps:

1. Configure a push provider on the Stream Dashboard
2. Add client-side integration for your chosen provider in your app
3. Register user devices with Stream's API

The client-side steps depend on which SDK you are using; follow the push notification guide in your SDK's documentation.

Push Providers

A push provider is a configuration of a push API with one of four types: APN, Firebase, Huawei and Xiaomi. Chat supports all four provider types. Activity Feeds supports Firebase and APN.

Multiple providers can be added to the same Stream application to support:

• Different builds of the same application, such as prod and staging or regular and admin
• Different target platforms, such as starting with React Native and adapting native Android and iOS SDKs along the way
• Multi-tenant applications, where different customers need different configurations

While Stream doesn't have first class integration for push providers besides Firebase, APN, Huawei and Xiaomi, it is entirely possible to integrate with additional providers using webhooks.

Dashboard Configuration

1. Navigate to your Stream Dashboard
2. Select your application
3. Go to the Push Notifications section
4. Click New Configuration and select your provider
5. Upload your credentials

Firebase requires a service account key from your FCM project:

Firebase console → project settings (top left) → service accounts (4th sub header) → generate a new private key

Export your key and upload it in the Firebase credentials field. A sample service account JSON:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com",
  "client_id": "client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

APN requires an Apple Developer account and an authentication key or certificate:

Upsert a Push Provider

In the same endpoint, a new config can be created or updated.

const pushProviderConfig = {
  name: "my-custom-name",
  type: "firebase",
  firebase_credentials: "my-service-account-information",
};

client.upsertPushProvider(pushProviderConfig);

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.upsert_push_provider(Models::UpsertPushProviderRequest.new(
  push_provider: Models::PushProvider.new(
    name: 'my-custom-name',
    type: 'firebase',
    firebase_credentials: 'my-service-account-information'
  )
))

client.UpsertPushProvider(ctx, &getstream.UpsertPushProviderRequest{
  PushProvider: &getstream.PushProviderRequest{
    Name:                "my-custom-name",
    Type:                getstream.PtrTo("firebase"),
    FirebaseCredentials: getstream.PtrTo("my-service-account-information"),
  },
})

List Push Providers

client.listPushProviders();

require 'getstream_ruby'

client.common.list_push_providers

client.ListPushProviders(ctx, &getstream.ListPushProvidersRequest{})

Delete a Push Provider

const pushProviderID = {
  type: "apn or firebase or huawei or xiaomi",
  name: "your given custom name while creating",
};

client.deletePushProvider(pushProviderID);

require 'getstream_ruby'

provider_type = 'apn or firebase or huawei or xiaomi'
provider_name = 'your given custom name while creating'

client.common.delete_push_provider(provider_type, provider_name)

pushProviderType := "apn or firebase or huawei or xiaomi"
pushProviderName := "your given custom name while creating"

client.DeletePushProvider(ctx, pushProviderType, pushProviderName, &getstream.DeletePushProviderRequest{})

Linking Devices to Providers

By default, adding a device doesn't require a push provider linking due to backward compatibility where old configurations don't have a name, so their names are empty.

• If the configuration name is not provided when adding a device, devices will be matched with configurations according to only their types.

• If the configuration name is provided, but invalid, the request will fail with a bad request error.

When devices are added, they can be linked to a provider to inherit their configuration.

const pushToken = "your client side generated device token to receive pushes";
const pushProviderType = "apn or firebase or huawei or xiaomi";
const userId = "your user id for server side calls";
const pushProviderName =
  "the name of the provider you created while configuring your app";

client.addDevice(pushToken, pushProviderType, userId, pushProviderName);

client.CreateDevice(ctx, &getstream.CreateDeviceRequest{
  ID:               "your client side generated device token to receive pushes",
  UserID:           getstream.PtrTo("your user id for server side calls"),
  PushProvider:     "apn or firebase or huawei or xiaomi",
  PushProviderName: getstream.PtrTo("the name of the provider you created while configuring your app"),
})

Single-Provider Configuration

If you're not interested in multi-bundle support, you can leverage the updateAppSettings endpoint to add push configuration for a single APN, Firebase, Huawei or Xiaomi provider.

// this configuration is same with upsert push provider
// except type is inherent and naming is missing so it's set to empty string
const firebase_config = {
  credentials_json: "my-service-account-information",
};

client.updateAppSettings({ firebase_config });

// this configuration is same with upsert push provider
// except type is inherent and naming is missing so it's set to empty string
client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  FirebaseConfig: &getstream.FirebaseConfig{
    CredentialsJson: getstream.PtrTo("my-service-account-information"),
  },
})

Registering Devices

Once your app has enabled push notifications, use the APIs to register user devices such as iPhones and Android phones.

Device Parameters

Register a Device

Registering a device associates it with a user and tells the push provider to deliver notifications to the device.

await client.createDevice({
  id: "<push token>",
  push_provider: "apn",
  push_provider_name: "production-ios",
  user_id: "user_id",
});

client.create_device(
    id="2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
    push_provider="apn",
    user_id="42",
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.create_device(Models::CreateDeviceRequest.new(
  id: '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207',
  push_provider: 'apn',
  user_id: '42'
))

$client->createDevice(new Models\CreateDeviceRequest(
    id: "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
    pushProvider: "apn",
    userID: "elon",
));

client.CreateDevice(ctx, &getstream.CreateDeviceRequest{
  ID:           "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
  PushProvider: "apn",
  UserID:       getstream.PtrTo("elon"),
})

await client.CreateDeviceAsync(new CreateDeviceRequest
{
    ID = "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
    PushProvider = "apn",
    UserID = "<user_id>",
});

List Devices

Provides a list of all devices associated with a user.

const devices = await client.listDevices({ user_id: "<user_id>" });

client.list_devices(user_id=user_id)

require 'getstream_ruby'

client.common.list_devices(user_id)

$response = $client->listDevices($userID);

client.ListDevices(ctx, &getstream.ListDevicesRequest{UserID: getstream.PtrTo(userID)})

await client.ListDevicesAsync(new { user_id = userId });

Remove a Device

Removing a device stops further push notifications to it.

await client.deleteDevice({
  id: "<device id>",
});

client.delete_device(
    id="2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
    user_id="42",
)

require 'getstream_ruby'

client.common.delete_device(
  '2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207',
  '42'
)

$client->deleteDevice("2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207", "elon");

client.DeleteDevice(ctx, &getstream.DeleteDeviceRequest{
  ID:     "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
  UserID: getstream.PtrTo("elon"),
})

await client.DeleteDeviceAsync(new
{
    id = "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207",
    user_id = "Taquito"
});

Push Preferences

Users control which notifications they receive with push preferences, set through the same endpoint across products. Preferences use a per-product level field: chat_level and call_level for Chat and Video, feeds_level for Activity Feeds. All of them support temporarily disabling push until a timestamp with disabled_until.

Each product documents its own preference levels and granular per-event controls:

• Chat push preferences
• Feeds push preferences

What Each Product Configures

Which events send a push, the delivery rules and the notification templates are configured per product:

• Chat: push delivery rules and payload and push templates
• Activity Feeds: push events and delivery rules, feed group push configuration and push templates

Troubleshooting

Push notifications are not always intuitive to implement because they involve systems outside of Stream with a number of moving parts. If push isn't arriving:

1. Check your push configuration in the Stream Dashboard
2. Verify your device token is valid and current
3. Ensure proper permissions are granted for notifications
4. Check the push logs in the Stream Dashboard for error messages
5. Test with different devices to isolate the issue

Chat documents common errors and how to resolve them.