Friend add mode

Each user has a friend add mode that decides what happens when someone sends them a friend request from a client:

Value	Meaning	When someone sends a request
need_confirm	Approval required	A pending request is created; they become friends once the user accepts
allow_any	Anyone can add	They become friends without the user's approval
deny_any	Nobody can add	The request can't be sent; the sender gets 403 friend_add_denied

• App default: users who never set one use default_friend_add_mode from the runtime policy (need_confirm by default, see Runtime policy). For example, an internal company messenger can default to allow_any; changing the default applies to every user who hasn't set their own.
• Who can set it: users set their own from clients, and your server can set it for them with this page's APIs (their online devices aren't notified).
• Only affects client friend requests: server Add a friend ignores the friend add mode. And if the other user already has a pending request to this user, requesting them back makes them friends right away, even if the other user is deny_any.

Get the friend add mode

GET/{org_name}/{app_name}/users/{username}/friend-settings

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
username	String	The username

Request example

curl "$IM_API/$ORG/$APP/users/erin/friend-settings" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

On success you get 200 OK with a friend add mode object. For a user who never set one:

{
  "friend_add_mode": null,
  "effective_friend_add_mode": "need_confirm"
}

Errors

HTTP status	code	Description
404	not_found	The user doesn't exist or was deleted

Set the friend add mode

Set a user's friend add mode, or clear it so the app default applies. Setting the same value isn't an error.

PUT/{org_name}/{app_name}/users/{username}/friend-settings

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
username	String	The username

Request body

Field	Type	Required	Description
friend_add_mode	String	Yes	need_confirm, allow_any or deny_any; null clears the user's setting so the app default applies. The field must be present

Request example

curl -X PUT "$IM_API/$ORG/$APP/users/erin/friend-settings" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "friend_add_mode": "allow_any"
  }'

Response

On success you get 200 OK with the updated friend add mode object.

{
  "friend_add_mode": "allow_any",
  "effective_friend_add_mode": "allow_any"
}

Errors

HTTP status	code	Description
400	invalid_argument	The body has no friend_add_mode, or its value isn't need_confirm, allow_any, deny_any or null
404	not_found	The user doesn't exist or was deleted

Data structures

Friend add mode object

Field	Type	Description
friend_add_mode	String	The mode the user set; null if they never set one
effective_friend_add_mode	String	The mode in effect: the user's setting if any, otherwise the app's default_friend_add_mode

{
  "friend_add_mode": null,
  "effective_friend_add_mode": "need_confirm"
}