Pular para o conteúdo principal

Identify

POST /agent/identify

Upserts who the app's current user is — a name and a handful of free-form identifiers — so that if the conversation is escalated to a human, your support queue can show a real person instead of an opaque session id.

Auth: API key + a verified end-user token (X-Appilots-User-Token). See Authentication → Verified end users.

The user is taken from the end-user token your backend issued, not from the request body. Without that token, the call succeeds but does nothing and returns identified: false: a userId the client declares on its own can't overwrite your user registry, because the SDK key ships inside the app.

This endpoint is write-only and scoped to the calling project: it can only upsert the user named in the token. It cannot read, list, or delete the identity registry — that's a dashboard-only capability. See Dashboard: Projects & API keys and the rest of the Dashboard section for operator-side user management.

Body​

FieldTypeRequiredDescription
userIdstring (1–128 chars)YesYour identifier for the user. Must match the userId in the end-user token, otherwise the request returns 403.
namestringNoDisplay name to show in escalation/operator tooling.
identifiersobject (Record<string, string>)NoFree-form lookup keys, e.g. email, phone. Keep this to a handful of fields.

A request that fails body validation (e.g. missing userId) returns 422 with error.code: "VALIDATION_ERROR".

Response — 200​

{
  "success": true,
  "data": { "identified": true }
}

identified is false when the request carries no end-user token. Nothing is stored in that case.

Privacy​

User identifiers are never sent to the model.

curl​

curl https://api.appilots.com/api/v1/agent/identify \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "X-Appilots-User-Token: END_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "name": "Jordan Lee",
    "identifiers": { "email": "jordan@example.com" }
  }'

TypeScript​

const res = await fetch('https://api.appilots.com/api/v1/agent/identify', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ak_xxxxxxxxxxxx...',
    'X-Appilots-User-Token': endUserToken, // issued by your backend
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user_123',
    name: 'Jordan Lee',
    identifiers: { email: 'jordan@example.com' },
  }),
});
const { data } = await res.json();
Última atualização em