Users

Users belong to accounts and represent individuals who can make/receive calls and access voicemails.

Create a User

const user = await dialstack.users.create(
  { name: 'John Doe', email: 'john@example.com' },
  { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' }
);

console.log(user.id); // 'user_01h2xcejqtf2nbrexx3vqjhp42'

Parameters

Parameter	Type	Required	Description
name	string	No	User's display name
email	string	No	User's email address
dialstackAccount	string	Yes	Parent account ID

Response

interface User {
  id: string;
  name: string | null;
  email: string | null;
  created_at: string;
  updated_at: string;
}

Retrieve a User

const user = await dialstack.users.retrieve('user_01h2xcejqtf2nbrexx3vqjhp42', {
  dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41',
});

console.log(user.name);

Parameters

Parameter	Type	Required	Description
userId	string	Yes	User ID
dialstackAccount	string	Yes	Account ID

Update a User

const user = await dialstack.users.update(
  'user_01h2xcejqtf2nbrexx3vqjhp42',
  { name: 'Jane Doe', email: 'jane@example.com' },
  { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' }
);

Parameters

Parameter	Type	Required	Description
userId	string	Yes	User ID
name	string	No	New display name
email	string	No	New email address
dialstackAccount	string	Yes	Account ID

Delete a User

await dialstack.users.del('user_01h2xcejqtf2nbrexx3vqjhp42', {
  dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41',
});

Parameters

Parameter	Type	Required	Description
userId	string	Yes	User ID
dialstackAccount	string	Yes	Account ID

List Users

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

const response = await dialstack.users.list({ limit: 20 }, acct);

for (const user of response.data) {
  console.log(user.id, user.name);
}

Parameters

Parameter	Type	Default	Description
limit	number	10	Results per page (max 100)
starting_after	string	-	Cursor for next page
ending_before	string	-	Cursor for previous page
dialstackAccount	string	Required	Account ID

Response

interface ListResponse<User> {
  data: User[];
  has_more: boolean;
}

Auto-Pagination

Iterate All Users

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

for await (const user of dialstack.users.list(undefined, acct).autoPagingEach()) {
  console.log(user.id, user.name);
}

Collect to Array

const acct = { dialstackAccount: 'acct_01h2xcejqtf2nbrexx3vqjhp41' };

const allUsers = await dialstack.users.list(undefined, acct).autoPagingToArray({ limit: 500 });

console.log(`Total users: ${allUsers.length}`);

Examples

Create User for New Customer

async function onboardCustomer(customerData: CustomerData) {
  // Create account
  const account = await dialstack.accounts.create({
    email: customerData.companyEmail,
  });

  const acct = { dialstackAccount: account.id };

  // Create primary user
  const user = await dialstack.users.create(
    { name: customerData.primaryContactName, email: customerData.primaryContactEmail },
    acct
  );

  return { account, user };
}

Sync Users from External System

async function syncUsers(accountId: string, externalUsers: ExternalUser[]) {
  const acct = { dialstackAccount: accountId };

  // Get existing users
  const existingUsers = await dialstack.users.list(undefined, acct).autoPagingToArray();

  const existingByEmail = new Map(existingUsers.map((u) => [u.email, u]));

  for (const ext of externalUsers) {
    const existing = existingByEmail.get(ext.email);

    if (existing) {
      // Update if changed
      if (existing.name !== ext.name) {
        await dialstack.users.update(existing.id, { name: ext.name }, acct);
      }
    } else {
      // Create new
      await dialstack.users.create({ name: ext.name, email: ext.email }, acct);
    }
  }
}

Get User's Voicemails Session

async function getUserVoicemailsSession(accountId: string, userId: string) {
  const acct = { dialstackAccount: accountId };

  // Verify user exists
  const user = await dialstack.users.retrieve(userId, acct);

  // Create session scoped to voicemails only
  const session = await dialstack.accountSessions.create({
    account: accountId,
    components: {
      call_logs: { enabled: false },
      voicemails: { enabled: true },
    },
  });

  return {
    userId: user.id,
    clientSecret: session.client_secret,
    expiresAt: session.expires_at,
  };
}

Delete All Users in Account

async function deleteAllUsers(accountId: string) {
  const acct = { dialstackAccount: accountId };

  const users = await dialstack.users.list(undefined, acct).autoPagingToArray();

  for (const user of users) {
    await dialstack.users.del(user.id, acct);
  }

  console.log(`Deleted ${users.length} users`);
}

Next Steps

• Sessions - Create session tokens
• Accounts - Manage accounts