---
title: "List users in an app"
method: GET
path: "/v1/{appId}/users"
tags: ["Users"]
---

# List users in an app

`GET /v1/{appId}/users`

## Request

- Base URL: `https://api.talkjs.com`
- URL: `https://api.talkjs.com/v1/{appId}/users`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
- TypeScript: <https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/users/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists all users that were ever created in your TalkJS application. 

You can filter results based on whether the user is online or not, and by a timestamp for when the user was created.

## Path parameters

- `appId` string, required

## Query parameters

- `isOnline` boolean
- `limit` integer
- `startingAfter` string

## Response `200`

Users listed successfully.

- UserList: An object that wraps an array of users
  - `data` User[]: An array of users
    - `id` string: A unique identifier of a user. When setting a user `id`, consider using the same user ID as the one you use inside your own database.
    - `createdAt` integer: Timestamp of when this message was sent, expressed as the number of milliseconds since the UNIX epoch (1970-01-01, 00:00:00 UTC).
    - `name` string: Name of a user
    - `role` string, nullable: A user's role. You can set up roles from the [Roles page of your TalkJS dashboard](https://talkjs.com/dashboard/roles/). You can vary many settings per user role, such as the content of their email or SMS notification, the look and feel of the UI, or forbidden words. Make sure the value of `role` corresponds exactly to a role name you set in the dashboard. For more information on roles, see: [Roles](https://talkjs.com/docs/Reference/Concepts/Roles/).
    - `custom` object: A custom property of a user. Custom properties are made available in the events sent to your code and in your email or SMS notification templates. For more on custom user properties, see: [Custom user properties](https://talkjs.com/docs/Reference/Concepts/Users/#custom).
    - `email` string[]: An array of email addresses of a user. If enabled, email addresses are used to send a user [email notifications](https://talkjs.com/docs/Features/Notifications/Email_Notifications/) of messages they may have missed while they were offline.
    - `photoUrl` string, nullable: A URL to a profile image (avatar) of a user. The photo shows up to other users who are in conversation with this user.
    - `locale` string, nullable: An [IETF language tag](https://www.w3.org/International/articles/language-tags/) that sets a language and date format for this user. You can set a default locale for your entire app on the **Settings** page of your [TalkJS dashboard](https://talkjs.com/dashboard).
    - `phone` string[]: An array of phone numbers of a user in the [E.164 international phone number format](https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers), without spaces. If enabled, phone numbers are used to send a user [SMS notifications](https://talkjs.com/docs/Features/Notifications/SMS_Notifications/) for messages they may have missed while they were offline.
    - `welcomeMessage` string, nullable: An optional welcome text shown to another user at the start of a conversation.
    - `availabilityText` string, nullable: An optional neutral text sent by this user at the start of a new conversation, rendered as a [System Message](https://talkjs.com/docs/Reference/Concepts/System_Messages/). `availabilityText` is deprecated in favor of [conversation.welcomeMessages](https://talkjs.com/docs/Reference/Concepts/Conversations/#welcomeMessages).
    - `pushTokens` object: pushTokens is an object that has the keys in the format: `provider:TOKEN_ID` Where _provider_ is either `fcm` for Android (Firebase Cloud Messaging), or `apns` for iOS (Apple Push Notification Service). And where `TOKEN_ID` is the token ID for your push notification service. To register a device for push notifications, set the value to the string `true`. To deregister a device for push notifications on all previously registered devices, set the value to `null`. For more on push tokens, see: [Mobile push notifications](https://talkjs.com/docs/Features/Notifications/Mobile_Push_Notifications/).

## Other responses

- `400`: Bad request
- `401`: Authorization information is missing or invalid.
- `404`: Resource not found
- `429`: Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/talkjs/apis/talkjs-api.md) - [All operations](https://skmtc.dev/talkjs/apis/talkjs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talkjs/apis/talkjs-api/revisions/9d4acc9cfa43?raw)