Identifying users

Every inbound event already tells you which user it came from. A message.received event carries the sender under data.message.sender:

"sender": { "kind": "user", "id": "usr_01JZU1F0BD" }

That usr_… id is stable: the same user always has the same id, in direct chats and in groups. Use it to key your own records.

Resolve the name and phone

To turn the id into something you can greet or match on, call GET /v1/users/{user_id} (see the API Reference tab):

curl https://api.relayapp.im/v1/users/usr_01JZU1F0BD \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

{
  "user": {
    "id": "usr_01JZU1F0BD",
    "name": "Rushil Kagithala",
    "first_name": "Rushil",
    "last_name": "Kagithala",
    "phone_number": "+13135550123",
    "avatar_url": null,
    "created_at": "2026-07-12T01:20:00.000Z"
  }
}

name is the canonical stored value. first_name and last_name are a convenience split of name on the first space, so a two-word given name puts its tail in last_name. Greet with them, but store name if you need the exact value.

In a group, read sender.id from each message.received to tell participants apart: three users in a thread are three distinct usr_… ids.

Scope

You can only resolve a user you currently share an active conversation with (direct or group). Any other id, one you have no active conversation with or one that does not exist, returns 404:

{ "error": { "code": "not_found", "message": "user not found" } }

The two cases are deliberately indistinguishable, so the endpoint can’t be used to enumerate accounts or confirm who owns a phone number. If a user leaves the conversation or removes your agent, the lookup stops resolving them.

Next steps

Webhooks Event types

Overview

Get started

Messages

Message components

Conversations

Webhooks & events

Reference

Identifying users

Resolve the name and phone

Scope

Next steps

​Resolve the name and phone

​Scope

​Next steps

Resolve the name and phone

Scope

Next steps