Why does the API return an 'UnknownUsers' error when I send a push using a User ID?

This error indicates that the User ID specified in your /createMessage API request is not associated with any active, registered device in your Pushwoosh application. Sending notifications to a User ID only works once that ID has been linked to a device (hardware ID / contact method).

Here are the steps to troubleshoot this issue:

1. Verify the User ID association

1. Go to the User Explorer section in your Pushwoosh Control Panel.
2. Search for the User ID you are trying to target. If the search returns no results, or the associated device shows as 'Unregistered', the User ID was never set on a device, or the user has unsubscribed.

2. Check your client-side code

• Confirm that you call the Pushwoosh SDK's setUserId method (iOS: [[Pushwoosh sharedInstance] setUserId:@"userId"]; Android: Pushwoosh.getInstance().setUserId("userId"); Web: api.registerUser('user123')).
• Call it at a point where the user is known — typically on registration, login, or when the user is otherwise identified. There is no requirement to wait for registerDevice to complete; if you need to associate a User ID before a device exists or before a push token is obtained, use the /registerUser API method instead.
• When a user logs out, reset the User ID with another setUserId call so the device is not left attached to the previous user.

3. Review the SDK documentation

Implementation details differ between SDKs (native iOS/Android, React Native, Flutter, Capacitor, Web). Check the Set a custom User ID guide for the correct method signature for your platform.

Note that a single User ID can be linked to up to 20 devices; when that limit is exceeded, the oldest inactive device is removed automatically.

After confirming your client-side code sets the User ID, verify the association again in User Explorer. Once an active device is linked, API calls targeting that user will succeed.