Registering devices

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

Each user has a limit of 25 unique devices. Once this limit is reached, the oldest device will be removed and replaced by the new device.

Device Parameters

Name	Type	Description	Default	Optional
`id`	string	The device ID (push token provided by the push provider)	-
`user_id`	string	The user ID for this device	-
`push_provider`	string	The push provider for this device: APN, Firebase, Huawei or Xiaomi	-
`disabled`	boolean	Set if the device is disabled	false	✓
`disabled_reason`	string	Explanation if the device is disabled	-	✓
`push_provider_name`	string	The push provider name for multi-bundle configurations	-	✓

Register a Device

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

Multi-bundle configurations require that you specify a push_provider_name when registering a device that corresponds to the name of the push configuration that you've set up in the dashboard or via the API.

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

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

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

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

Registering from the chat client SDKs

Registering a device associates it with a user and tells the push provider to send new message notifications to the device.

Multi-bundle configurations require that you specify a push_provider_name when registering a device that corresponds to the name of the push configuration that you've set up in the dashboard or via the API.

const id = "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207";
const push_provider = "apn";
const user_id = "Taquito";

await client.addDevice(id, push_provider, user_id);

// if multi providers
await client.addDevice(id, push_provider, user_id, push_provider_name);

client.addDevice(
  Device(
    token = "push-provider-token",
    pushProvider = PushProvider.FIREBASE,
    providerName = "provider_name", // Optional, if adding to multi-bundle named provider
  )
).enqueue { result ->
  if (result.isSuccess) {
    // Device was successfully registered
  } else {
    // Handle error
  }
}

func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  // Note: If you leverage mutli-bundle configuration, please provide providerName - name of your configuration
  chatClient.currentUserController().addDevice(.apn(token: deviceToken)) { error in
   if let error = error {
     print("Error adding device token.", error)
   }
  }
}

// register the device with APN (Apple only)
await client.addDevice('device-token', PushProvider.apn);

// register the device with Firebase (Android only)
await client.addDevice('device-token', PushProvider.firebase);

await Client.DeviceApi.AddDeviceAsync(new CreateDeviceRequest
{
  //Device ID provided by the notifications provider e.g. Token provided by Firebase Messaging SDK
  Id = "unique-device-id",
  PushProvider = PushProviderType.Firebase,
});

// register the device with APN (Apple only)
Client->AddDevice(TEXT("device-token"), EPushProvider::Apn);

// register the device with Firebase (Android only)
Client->AddDevice(TEXT("device-token"), EPushProvider::Firebase);

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

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

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

Registering from the feeds client SDKs

Multi-bundle configurations require that you specify a push_provider_name when registering a device that corresponds to the name of the push configuration you've set up in the dashboard.

Multi-Bundle Device Registration

When using multi-bundle configurations, specify the provider name:

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

// Configure the push provider info during SDK initialization
let notificationsConfig = PushNotificationsConfig(
    pushProviderInfo: PushProviderInfo(
        name: "production-ios",
        pushProvider: .apn
    )
)

let config = FeedsConfig(pushNotificationsConfig: notificationsConfig)
let feedsClient = FeedsClient(
    apiKey: apiKey,
    user: user,
    token: token,
    feedsConfig: config,
    tokenProvider: tokenProvider
)

// Then register the device
try await feedsClient.createDevice(id: pushToken)

$response = $client->createDevice(
    new GeneratedModels\CreateDeviceRequest(
        id: "<push token>",
        pushProviderName: "production-ios",
        pushProvider: "apn",
        userID: "eric"
    )
);

List Devices

Provides a list of all devices associated with a user.

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

Listing from the chat client SDKs

Provides a list of all devices associated with a user.

const user_id = "Taquito";

await chatClient.getDevices(user_id);

let currentUserController = chatClient.currentUserController()

currentUserController.synchronizeDevices { error in
  guard error == nil else {
    print("Error getting the list of devices")
    return
  }

  let devices = currentUserController.currentUser?.devices
}

var response = await Client.DeviceApi.ListDevicesAsync(Client.UserId);
foreach (var userDevice in response.Devices)
{
  Debug.Log(userDevice.Id); // Unique Device ID provided by push notifications provider
  Debug.Log(userDevice.CreatedAt);
  Debug.Log(userDevice.PushProvider); //E.g. Firebase
  Debug.Log(userDevice.Disabled);
  Debug.Log(userDevice.DisabledReason);
}

Listing from the feeds client SDKs

Get a list of all devices associated with a user.

const devices = await client.listDevices();

The device object contains the following properties:

{
  created_at: Date,
  id: string,
  push_provider: string,
  user_id: string,
  disabled?: boolean,
  disabled_reason?: string,
  push_provider_name?: string,
  voip?: boolean
}

public struct Device {
    public var createdAt: Date
    public var disabled: Bool?
    public var disabledReason: String?
    public var id: String
    public var pushProvider: String
    public var pushProviderName: String?
    public var userId: String
    public var voip: Bool?
}

Remove a Device

Removing a device stops further push notifications to it.

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

Removing from the chat client SDKs

Unregistering a device removes the device from the user and stops further new message notifications.

const id = "2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207";
const user_id = "Taquito";

await chatClient.removeDevice(id, user_id);

client.deleteDevice(
  Device(
    token = "push-provider-token",
    pushProvider = PushProvider.FIREBASE,
    providerName = "custom_name", // Optional, if added to multi-bundle named provider
  )
).enqueue { result ->
  if (result.isSuccess) {
    // Device was successfully unregistered
  } else {
    // Handle error
  }
}

let currentUserController = chatClient.currentUserController()

guard let device = currentUserController.currentUser?.currentDevice else {
  // No device to remove
}

currentUserController.removeDevice(id: device.id) { error in
  if let error = error {
    print("Error removing the device", error)
  }
}

Removing from the feeds client SDKs

Remove a device to stop push notifications for that device.

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

Troubleshooting Device Registration

If device registration isn't working:

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

For more detailed troubleshooting, check the Activity Feeds logs and error responses from the API.

Push providers

Push preferences