Identify users

Tell Whisperr who a user is: traits for context, channels for how Whisperr can reach them — and whether it’s allowed to.

POST /v1/identify

Identify is idempotent and safe to call on every login. Traits are merged server-side.

The identify object

{
  "external_user_id": "user_8842",
  "traits": { "plan": "pro" },
  "preferred_channel": "email",
  "channels": [
    { "channel": "email", "address": "ada@example.com", "opted_in": true, "verified": false }
  ]
}

external_user_id string, required

Your own stable user id — the same one you send on events.

traits object, optional

Free-form user attributes (plan, name, …), merged server-side. Omit when empty.

preferred_channel string, optional

One of email | sms | push. Optional — by default Whisperr decides which channel to use based on engagement, so only set this to record an explicit user choice.

channels array, optional

Each item:

Field	Type	Notes
channel	string, required	email | sms | push. The field is named channel, not type — the API rejects unknown fields, so type fails the whole request with a 400.
address	string, required	Email address, E.164 phone number, or push token.
opted_in	bool	Defaults to true. Set false to record an opt-out — Whisperr will not use that channel.
verified	bool, optional	Omit unless you’ve verified the address yourself.

SDK shortcuts

The SDKs expose email / phone / pushToken conveniences that expand to opted-in email / sms / push channels respectively:

whisperr.identify("user_8842", { email: "ada@example.com", traits: { plan: "pro" } });

is the same wire request as the JSON above (minus preferred_channel).