Identifying users

A message.received event carries the sender as data.sender_handle:

"sender_handle": { "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

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"
  }
}

Field	Use
`name`	The stored value. Keep this one when you need the exact name
`first_name`, `last_name`	A convenience split of `name` on the first space. Greet with these

A two-word given name puts its tail in last_name.

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

Scope

Resolve only a user you currently share an active conversation with, direct or group. Every other id returns 404, whether it exists or not:

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

The two cases are deliberately indistinguishable, so the endpoint cannot enumerate accounts or confirm who owns a phone number. When a user leaves the conversation or removes your agent, the lookup stops resolving them.

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

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