All resource URLs include an {appId}, which you can find in the Dashboard.

Path:/v1/{appId}/users/{userId}
Methods:GET, PUT

{userId} is your internal unique identifier for the user.

Creating or updating a user

Before you start sending messages, you need to synchronize participants of the conversation. Structure:

PUT https://api.talkjs.com/v1/{appId}/users/{userId}

{
  "name": string,
  "email": Array<string>,
  "welcomeMessage": string,
  "photoUrl": string,
  "configuration": string,
  "phone": Array<string>,
  "custom": Map<string, string>
}

Example payload:

{
  "name": "Alice",
  "email": ["[email protected]"],
  "welcomeMessage": "Hi there, how are you? :-)",
  "photoUrl": "https://demo.talkjs.com/img/alice.jpg",
  "configuration": "buyer",
  "phone": ["+1123456789"],
  "custom": {
    "country": "ca"
  }
}

Getting created users

After you successfully create or update a user, you can fetch it back with a GET REST call.

GET https://api.talkjs.com/v1/{appId}/users/{userId}

The interface for this resource is the following:

type UserId = string;
type UnixMilliseconds = number;

type User = {
  id: UserId;
  name: string;
  welcomeMessage?: string;
  photoUrl?: string;
  headerPhotoUrl?: string;
  configuration?: string;
  email?: string[] | null;
  phone?: string[] | null;
  custom?: {[name: string]: string };
  availabilityText?: string;
  locale?: string;
  createdAt: UnixMilliseconds;
};

Listing conversations a user is a part of

You can list all conversations the user is a part of. The structure of the response is explained here.

GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations
Filters

If you want to filter a user's conversations you have the following options:

  • list the conversations with unread messages: pass the unreadsOnly parameter with its value set to true.
  • last message in the conversation was sent before and/or after an arbitrary date. lastMessageBefore and lastMessageAfter are Unix timestamps expressed in milliseconds. Filters can be combined together with limits and cursors.
Limits and pagination

Similarly to other list requests, pagination and limits are applicable to listing user's conversations.

Examples:
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=true
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=true&lastMessageBefore=1521522849308&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726&lastMessageBefore=1521522849308

Listing all users in the application

You can list all users ever created in your TalkJS application. The structure of the response is explained here.

GET https://api.talkjs.com/v1/{appId}/users
Limits and pagination

Similarly to other list requests, pagination and limits are applicable to listing users.

Filters

TalkJS supports a limited set of filters for getting user information. In order to only list users that are online or offline, you have to pass the isOnline parameter to the query string:

GET https://api.talkjs.com/v1/{appId}/users?isOnline=true
GET https://api.talkjs.com/v1/{appId}/users?isOnline=false
Examples:
GET https://api.talkjs.com/v1/{appId}/users
GET https://api.talkjs.com/v1/{appId}/users?limit=50
GET https://api.talkjs.com/v1/{appId}/users?limit=50&startingAfter=u_31
GET https://api.talkjs.com/v1/{appId}/users?startingAfter=u_31
GET https://api.talkjs.com/v1/{appId}/users?isOnline=true&limit=3
GET https://api.talkjs.com/v1/{appId}/users?isOnline=false&limit=5&startingAfter=u_48