--- title: "Create or update a user" method: PUT path: "/v1/{appId}/users/{userId}" tags: ["Users"] --- # Create or update a user `PUT /v1/{appId}/users/{userId}` ## Request - Base URL: `https://api.talkjs.com` - URL: `https://api.talkjs.com/v1/{appId}/users/{userId}` - Auth: one of: - HTTP bearer - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a user, or updates user details. If a user with this specific user ID exists, then this operation updates their user details. If a user with this specific user ID doesn't yet exist, then it creates a new user with the set details. **Note:** To update user details, you only need to send the subset of fields you want to update. In that respect, even though you update a user with an HTTP `PUT` request method, the user update acts similar to an HTTP `PATCH` request method. ### Remove user data Currently you can't delete a user. Instead, you can update the user's data to remove any personally identifiable information associated with the user. To automate the process of removing user data, use the [Anonymize user data](https://github.com/talkjs/talkjs-examples/tree/master/rest-api/anonymizing-user) script from the TalkJS examples GitHub repository. ## Path parameters - `appId` string, required - `userId` string, required ## Request body - UserCreateOrUpdateData: One single user. A user is a person or a group of people who uses your app. For more on the concept of a user in TalkJS, see: [Users](https://talkjs.com/docs/Reference/Concepts/Users/). - `name` string, required: 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 for other users who are n 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` has been 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/). ## Response `200` Empty response - object: Empty response ## Other responses - `400`: Bad request - `401`: Authorization information is missing or invalid. - `404`: Resource not found - `415`: Unsupported media type - `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)