Look up users

Goal

Turn a name or an email typed by someone into the user ids you pass when you create conversations and add members. Your backend usually already has its users’ ids. Use lookup only when you do not.

Prerequisites

Chat permission: users.lookupMachine scope (any of): chat:users.lookupchat:sync

A backend client with one of those scopes.
The ChatClient from Create direct conversations.

Steps

Search. Send at least 2 characters. Chat matches the query against display names and emails, ignoring case, and returns at most 20 members sorted by display name.
Use the ids. Each result has user_id, display_name, email (may be null) and avatar_url. Pass user_id as a member or as actor_user_id.

TypeScript
curl

import { ChatApiError, type ChatUserProfile } from '@central-code-station/ccs-chat-client';
import { chat } from './guide-chat-client';

// Resolve a name or email typed by someone into user ids. Chat returns at most 20 matches.
export async function findMembers(query: string): Promise<ChatUserProfile[]> {
  if (query.trim().length < 2) return [];
  try {
    return await chat.users.lookup(query.trim());
  } catch (error) {
    if (error instanceof ChatApiError && error.code === 'query_too_long') return [];
    throw error;
  }
}

curl -s "$CHAT_API_URL/tenants/$CCS_TENANT_ID/applications/$CCS_APPLICATION_ID/users/lookup?q=jo" \
  -H "Authorization: Bearer $CHAT_MACHINE_TOKEN"

{ "items": [ { "user_id": "client-john", "display_name": "John Client", "email": "john@example.com", "avatar_url": null } ] }

Backend lookup and directory lookup

	Your backend client	A user with `users.lookup`	A user with `users.lookup.directory`
Searches	Tenant members Chat already knows	The same	Also the tenant directory at the Identity Server, when Chat knows no match
Granted by	`chat:users.lookup` or `chat:sync`	The role’s Chat permissions	The role’s Chat permissions

A backend client never searches the directory, whatever its scopes. users.lookup.directory is never granted to machines.

“Already knows” means people Chat has already seen in your tenant, for example because they signed in or an earlier call named them. A user Chat has not seen may not appear, but you can still pass their id to a create or add-member call. Chat then checks their eligibility with the Identity Server.

Limits

A query is 2 to 100 characters.
Calls from your backend count against the per-client budget, 600 requests per 60 s per client. The per-user lookup limit, 20 lookups per 10 s per user, applies to users.

Verify

Look up a member you know, such as jo for John, and check that client-john is in items. A query of one character returns 400 query_too_short.

Troubleshooting

Symptom	Cause and fix
Empty `items` for a user you know exists	Chat has not seen them yet, or the text does not match their display name or email. Use their id directly, or look them up in your own data.
400 `query_too_short`	Fewer than 2 characters.
400 `query_too_long`	More than 100 characters.
403 `insufficient_scope`	The client lacks `chat:users.lookup`.
429 `rate_limited`	Back off for the `Retry-After` seconds. See Handle errors and retries.