Users

Create or update a user

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 script from the TalkJS examples GitHub repository.

put/v1/{appId}/users/{userId}

Request

Base URL
https://api.talkjs.com
Auth
- HTTP bearer
- or HTTP bearer
TypeScript
https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/users/:userId/put.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

appIdstring required

Example:abcd1234

A unique identifier of your TalkJS app. You can find your app ID on the Settings page of your dashboard.

userIdstring required

Example:alice

A unique identifier of a user.

Request body

namestring required

Name of a user

rolestring nullable

A user's role. You can set up roles from the Roles page of your TalkJS dashboard.

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.

customobject

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.

emailstring[]

An array of email addresses of a user.

If enabled, email addresses are used to send a user email notifications of messages they may have missed while they were offline.

photoUrlstring 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.

localestring nullable

An IETF language tag 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.

phonestring[]

An array of phone numbers of a user in the E.164 international phone number format, without spaces.

If enabled, phone numbers are used to send a user SMS notifications for messages they may have missed while they were offline.

welcomeMessagestring nullable

An optional welcome text shown to another user at the start of a conversation.

availabilityTextstring nullable

An optional neutral text sent by this user at the start of a new conversation, rendered as a System Message.

availabilityText has been deprecated in favor of conversation.welcomeMessages.

pushTokensobject

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.

Example request

{
  "name": "Alice",
  "role": "admin",
  "custom": {
    "country": "Bahrain"
  },
  "photoUrl": "https://talkjs.com/images/avatar-1.jpg",
  "locale": "ar",
  "welcomeMessage": "Hi there, how are you? :-)",
  "availabilityText": "We're usually online during office hours",
  "pushTokens": {
    "fcm:TOKEN_ID": true
  }
}

Response

Empty response

object required