Guides

The people in your apps

List, add, disable and change the role of the people who sign in to the account's own apps, from your server.

The people who sign in to the account's apps (see Sign in) are one list for the account: someone signs in to any of its apps with the same email and role. Your server can manage that list, for a staff screen or your own sign-up flow.

It needs the account's token, never an app key. Reading works on every plan with crm:read; adding and changing people needs crm:write and Pro or above, because signing people in to your own apps is part of Pro.

#Add someone

const person = await db.appUsers.invite('sam@example.com', { role: 'customer' });
console.log(person.id, person.contact_id); // linked to Sam's contact when one has that email

No email is sent: they sign in from your app with auth.signInWithLink(). Adding someone already on the list keeps their id and gives them the new role. The role defaults to member; a role is lower case letters, digits and _.

#List, change and disable

const people = await db.appUsers.list(); // newest first, at most 1,000
const quiet = people.filter((p) => !p.last_sign_in_at);

await db.appUsers.update(people[0].id, { role: 'staff' });
const { sessionsRevoked } = await db.appUsers.update(people[0].id, { disabled: true });

Disabling someone ends every session they have at once (sessionsRevoked says how many), and their next call to the hub is refused. { disabled: false } lets them sign in again. contactId links them to a contact, or null unlinks them.

#An app's assistant this month

When an app's conversations have an AI assistant, assistantUsage(appId) says what it did this month (UTC): conversations it looked at, replies it sent or drafted, replies that asked Knowledge (those count towards the account's Knowledge answers), and the AI tokens, with how many were on the account's own AI key.

const usage = await db.assistantUsage(appId);
console.log(usage.replies, usage.knowledge_replies, usage.tokens, usage.own_key);