Identities endpoints

Following a User

For purposes of this discussion:

  • Your User: Refers to the user whose list of Followed Users you are editting
  • Followed Users: Refers to users “followed” by Your User as defined below.

Very circular. But with that, lets define following:

Define Following

A User is Followed if:

  • Your User has ever been in a Conversation with the other user
  • Or your User has explicitly followed the other user (or a request sent on their behalf of Your User to follow the other user is sent via Client API or Server API)
  • And your User has not explicitly unfollowed the other user (or a request sent on their behalf using Client API or Server API)

A Followed User has the following behaviors from the perspective of Your User:

  • The Followed User is returned in any request listing users followed by Your User
  • WebSocket Change Events will be delivered to Your User for any changes to Identity objects for any Followed Users

Rationale

There are a few goals served by Following a user:

  1. Improved Rendering: While many applications will just use the display_name and avatar_url that comes with each Message to display the sender of the Message, some applications may need additional information when rendering users. To accomplish this, and to minimize the amount of on-demand fetching of users, your application can load the full Identity objects for all of the user’s the current user is following.
  2. On having a cache of user data, that cache needs to be maintained in the event of any changes (i.e. a user changes their Avatar)
  3. For applications that don’t already maintain a list of users your user can talk to, there are advantages to using this existing cache of data to drive any user lists. Useful for example when selecting users to create a Conversation with or add a user to an existing Conversation.
  4. Using information outside of display_name for rendering the user in a User List or next to their Messages. For example, there may be information in the Identity metadata property that affects how they are rendered (blue for admin, red for novice users, etc…)

Endpoint Details

All operations for allowing Your User to follow Other Users is accessed via the Client API Identities operations.

All other operations listed here are for creating and manipulating the Identity objects that these users will receive when viewing their Followed Users.

Method HTTP request Description
Create identity POST /apps/:app_uuid/users/:user_id/identity Register an Identity with Layer
Update identity PATCH /apps/:app_uuid/users/:user_id/identity Update parameters for an Identity
Replace identity PUT /apps/:app_uuid/users/:user_id/identity Replace the entire Identity object
Get identity GET /apps/:app_uuid/users/:user_id/identity Get the Identity object
Delete identity DELETE /apps/:app_uuid/users/:user_id/identity Delete an Identity from Layer

Create identity

You can create an Identity object when authenticating via the Identity Token. Alternately, you can register an Identity with Layer at a later time using this endpoint. Creating an Identity will not count towards your monthly users.

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
display_name string Name to show on-screen for user
avatar_url string (optional) URL to the user’s profile photo
first_name string (optional) First name for user
last_name string (optional) Last name for user
identity_type string (optional) One of bot or user
phone_number string (optional) Phone number for user
email_address string (optional) Email for user
public_key string (optional) Public encryption key for end-to-end encryption
metadata object (optional) Arbitrary key-value metadata. Values must be strings, nested objects are not supported.

HTTP request:

POST/apps/:app_uuid/users/:user_id/identity

Example:

{
    "display_name": "Frodo the Dodo",
    "avatar_url": "http://sillylordoftheringspictures.com/frodo-riding-a-dodo.png",
    "first_name": "Frodo",
    "last_name": "Baggins",
    "phone_number": "13791379137",
    "email_address": "frodo@sillylordoftheringspictures.com",
    "metadata": {
        "level": "35",
        "race": "Dodo"
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity\
 -d '{"display_name":"Frodo the Dodo","avatar_url":"http://sillylordoftheringspictures.com/frodo-riding-a-dodo.png","first_name":"Frodo","last_name":"Baggins","phone_number":"13791379137","email_address":"frodo@sillylordoftheringspictures.com","metadata":{"level":"35","race":"Dodo"}}'

Possible responses:

Identity created successfully
Status: 201 (Created)
(Empty body)

Update identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
operation string The type of operation; “set” is the only allowed value for this endpoint
property string The property to change
value string New value to set

HTTP request:

PATCH/apps/:app_uuid/users/:user_id/identity

Example:

[
    {
        "operation": "set",
        "property": "last_name",
        "value": "Dodo"
    },
    {
        "operation": "set",
        "property": "phone_number",
        "value": ""
    },
    {
        "operation": "set",
        "property": "metadata.level",
        "value": "2"
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity\
 -d '[{"operation":"set","property":"last_name","value":"Dodo"},{"operation":"set","property":"phone_number","value":""},{"operation":"set","property":"metadata.level","value":"2"}]'

Possible responses:

Identity updated successfully
Status: 204 (No Content)
(Empty body)

Replace identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with
display_name string Name to show on-screen for user
avatar_url string (optional) URL to the user’s profile photo
first_name string (optional) First name for user
last_name string (optional) Last name for user
phone_number string (optional) Phone number for user
email_address string (optional) Email for user
public_key string (optional) Public encryption key for end-to-end encryption
metadata object (optional) Arbitrary key-value metadata. Values must be strings, nested objects are not supported.

HTTP request:

PUT/apps/:app_uuid/users/:user_id/identity

Example:

curl  -X PUT \
      -H 'Accept: application/vnd.layer+json; version=3.0' \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{"display_name": "Frodo the Dodo", "first_name": "Frodo"}' \
      https://api.layer.com/apps/<APP_UUID>/users/<USER_ID>/identity

Possible responses:

Identity updated successfully
Status: 204 (No Content)
(Empty body)

Get identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with

HTTP request:

GET/apps/:app_uuid/users/:user_id/identity

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity

Possible responses:

Got identity | Status: 200 (OK)

Identity

Delete identity

Parameters:

Name Type Description
app_uuid string Your Layer App ID
user_id string ID of the user to associate the identity with

HTTP request:

DELETE/apps/:app_uuid/users/:user_id/identity

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_id>/identity

Possible responses:

Identity deleted successfully
Status: 204 (No Content)
(Empty body)