Set a user's profile information, including custom status.
POSThttps://slack-gov.com/api/users.profile.set
application/x-www-form-urlencoded
application/json
token
Authentication token bearing required scopes. Tokens should be passed as an HTTP Authorization header or alternatively, as a POST parameter.
xxxx-xxxxxxxxx-xxxx
Name of a single key to set. Usable only if profile
is not passed.
first_name
Collection of key:value pairs presented as a URL-encoded JSON hash. At most 50 fields may be set. Each field name is limited to 255 characters.
{ first_name: "John", ... }
ID of user to change. This argument may only be specified by admins on paid teams.
W1234567890
users.profile.set
API method in order to change the profile for other users.users.profile.set
API method requires you to use a user access token (starts with xoxp-
).Primary Owner
> Owner
> Admin
> Member
> Guest
. More information about roles can be found here. Therefore:
There are two ways to update non-custom profile fields with this method:
name
and value
.profile
.You can update any of the following non-custom fields from the profile
object within a Slack user
object:
Field | Description |
---|---|
display_name |
The display name the user has chosen to identify themselves by in their workspace profile. Maximum of 80 characters. |
email |
A valid email address. It cannot have spaces, or be in use by another member of the same team. It must have an @ and a domain. Changing a user's email address will send an email to both the old and new addresses, and also post a slackbot message to the user informing them of the change. You cannot update your own email using this method. This field can only be changed by admins for users on paid teams. |
first_name |
The user's first name. The name slackbot cannot be used. Updating first_name will update the first name within real_name . |
last_name |
The user's last name. The name slackbot cannot be used. Updating last_name will update the second name within real_name . |
phone |
The user's phone number, in any format. |
pronouns |
The user's pronouns. |
real_name |
The user's first and last name. Updating this field will update first_name and last_name . If only one name is provided, the value of last_name will be cleared. Maximum of 50 characters. |
start_date |
The date the person joined the organization (Business+ or Enterprise customers only). |
title |
The user's title. |
The skype
field will always be an empty string and cannot be set otherwise. For more details, please read this changelog entry.
While profile image fields are present in the profile
object, they cannot be set using the users.profile.set
method. Use users.setPhoto
and users.deletePhoto
to update a user's profile image.
The following example payload updates the values of first_name
, last_name
, pronoun
, and email
for a user:
{
"profile": {
"first_name": "John",
"last_name": "Smith",
"pronouns": "they/them",
"email": "john@smith.com"
}
}
Custom fields are created within the organization admin tools. Once a field is created, you can update it for users with this API method.
Each custom profile field has a unique per-team ID. You can update a custom profile field by providing a key:value pair where the key is the relevant ID. Use team.profile.get
to retrieve the profile fields and their IDs used by a team.
You can update a profile field by using the ID in the name
field. To update custom profile fields, use the fields
object instead. The fields
object is an array of custom profile fields' key:value pairs.
If you update fields within the fields
array, you can also choose to set the alt
field. While the value
of a field is what is usually displayed, the alt
key will be displayed instead if it is set. The alt
field can be up to 256 characters for all field types.
A field within the fields
array needs a type
. This determines the type
of information value
contains.
Type | Description |
---|---|
date |
the value must be a valid date. |
link |
the value can be any valid link that's not more than 256 characters. The link text will be the alt value if set, or the data element name if alt is not set. |
long_text |
the value can be up to 5,000 characters of basic formatted mrkdown . See the long_text section below. |
options_list |
the value must be one of the possible_values in the field definition. |
tags |
the value contains distinct elements known as multi-value tags. Individual tags can hold up to 50 characters. Any number of tags can be created by admins, but end-users can only add 75 tags to their profiles. See the tags section below. |
text |
the value can be up to 256 characters of plain text. |
user |
the value can be up to 25 user IDs, seperated by commas. |
The following example sets the value
of three fields; one with plain text, one with a date, and another with a link.
{
"profile": {
"fields": {
"Xf0111111": {
"value": "Barista",
"alt": ""
},
"Xf0222222": {
"value": "2022-04-11",
"alt": ""
},
"Xf0333333": {
"value": "https://example.com",
"alt": ""
}
}
}
}
The value
of a long_text
field can be up to 5,000 characters of basic formatted mrkdown
.
While you should use team.profile.get
to get the ID for any field, including long-text fields, you should not copy the received schema. Below is a properly formatted payload for updating the long_text
field with user.profile.set
.
{
"profile": {
"fields": {
"Xf0222222": {
"value": "I make absolutely the best coffee you will *_ever_* taste. Learn more about where I studied <http://www.example.com|how to pull an espresso shot>. :coffee:",
"alt": ""
}
}
}
}
The value
of a tags
field contains distinct elements known as multi-value tags. Individual tags can hold up to 50 characters. Any number of tags can be created by admins, but end-users can only add 75 tags to each smart tag element on their profiles.
While you should use team.profile.get
to get the ID for any field, including smart tag fields, you should not copy the received schema. Below is a properly formatted payload for updating the tags
field with user.profile.set
.
{
"fields": {
"Xf0333333": {
"value": [
"Mocha", "Latte", "Americano"
],
"alt": ""
}
}
}
The Name Pronunciation field lets a user provide a text description of how their name is pronounced. This text is displayed under their job title.
Use team.profile.get
to obtain the field ID. Below is an example payload for updating the field once you have that ID:
{
"profile": {
"fields": {
"Xf0444444": {
"value": "Zoë is pronounced zo-ee",
"alt": ""
}
}
}
}
Name Recordings
A user can also record an audio file of how their name is pronounced. This name recording will appear on their profile as a speaker icon. A Name Recording cannot be updated via API.
This method is also used to set a user's current status.
Place the following status fields within the profile
object when calling users.profile.set
:
Field | Type | Description |
---|---|---|
status_emoji |
string | The displayed emoji that is enabled for the Slack team, such as :train: . |
status_expiration |
integer | the Unix timestamp of when the status will expire. Providing 0 or omitting this field results in a custom status that will not expire. |
status_text |
string | The displayed text of up to 100 characters. We strongly encourage brevity. |
For example, the following payload sets a custom status of 🚆 riding a train
and has it expire on July 26th, 2018 at 17:51:46 UTC:
{
"profile": {
"status_text": "riding a train",
"status_emoji": ":train:",
"status_expiration": 1532627506
}
}
To manually unset a user's custom status, provide empty strings to both the status_text
and status_emoji
attributes: ""
.
A user's start date can be found in the start_date
non-custom profile field. You can update this field like any other non-custom profile field.
{
"profile": {
"start_date": "2022-10-22"
},
"user": "U123ABC456"
}
When you update a user's start date, both the start_date
field and a custom profile field with its own unique field ID is updated.
While it's perfectly fine to just update start_date
, you could also choose to update this custom field instead, after obtaining the custom field ID with team.profile.get
. Updating one of these fields will update the other field accordingly.
{
"profile": {
"fields": {
"Xf0123ABC456": {
"value": "2022-10-22",
}
},
"user": "U123ABC456",
}
We strongly recommend using application/json
POSTs when using this method. If you choose to use application/x-www-form-urlencoded
, you must URL-encode the JSON provided to the profile
field.
In general, you need to set your content type and authorization credentials to make an HTTP request. If you're using a workspace token, you need to provide an x-slack-user
header indicating the user you're acting on behalf of.
You can send a JSON payload to users.profile.set
with such an HTTP request:
POST /users/profile.set
Host: slack.com
Authorization: Bearer xoxp-secret-token
Content-type: application/json; charset=utf-8
{
"profile": {
"first_name": "John",
"last_name": "Smith",
"pronouns": "they/them",
"email": "john@smith.com",
"fields": {
"Xf0111111": {
"value": "Barista",
"alt": ""
},
"Xf0222222": {
"value": "2022-04-11",
"alt": ""
},
"Xf0333333": {
"value": "https://example.com",
"alt": ""
}
}
}
}
This method will generate a user_change
event on success, containing the complete user.
Update a user's profile, including custom status, sparingly. Special rate limit rules apply when updating profile data with users.profile.set
. A token may update a single user's profile no more than 10 times per minute. And a single token may only set 30 user profiles per minute. Some burst behavior is allowed.
The complete user's profile will be returned.
{
"ok": true,
"profile": {
"title": "Head of Coffee Production",
"phone": "",
"skype": "",
"real_name": "John Smith",
"real_name_normalized": "John Smith",
"display_name": "john",
"display_name_normalized": "john",
"fields": {
"Xf0111111": {
"value": "Barista",
"alt": ""
},
"Xf0222222": {
"value": "2022-04-11",
"alt": ""
},
"Xf0333333": {
"value": "https://example.com",
"alt": ""
}
},
"status_text": "Watching cold brew steep",
"status_emoji": ":coffee:",
"status_emoji_display_info": [],
"status_expiration": 0,
"avatar_hash": "123xyz",
"start_date": "2022-03-21",
"email": "johnsmith@example.com",
"pronouns": "they/them/theirs",
"huddle_state": "default_unset",
"huddle_state_expiration_ts": 0,
"first_name": "john",
"last_name": "smith",
"image_24": "https://.../...-24.png",
"image_32": "https://.../...-32.png",
"image_48": "https://.../...-48.png",
"image_72": "https://.../...-72.png",
"image_192": "https://.../....-192png",
"image_512": "https://.../...-512.png"
}
}
Typical error response
{
"ok": false,
"error": "invalid_profile"
}
This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok
params in the response.
Error | Description |
---|---|
cannot_update_admin_user | Only a primary owner can update the profile of an admin. |
email_taken | email taken |
invalid_profile | Profile object passed in is not valid JSON (make sure it is URL encoded!). |
must_clear_both_status_text_and_status_emoji | Clearing the status requires setting both |
name_not_allowed | name cannot contain URL. |
not_admin | Only admins can update the profile of another user. Some fields, like |
not_app_admin | Only team owners and selected members can update the profile of a bot user. |
partial_profile_set_failed | Failed to set user profile. |
profile_set_failed | Failed to set user profile. |
reserved_name | First or last name are reserved. |
sudo_required | Request requires sudo session. |
too_long | You attempted to set a custom status but it was longer than the maximum allowed, 100. |
access_denied | Access to a resource specified in the request is denied. |
account_inactive | Authentication token is for a deleted user or workspace when using a |
deprecated_endpoint | The endpoint has been deprecated. |
ekm_access_denied | Administrators have suspended the ability to post a message. |
enterprise_is_restricted | The method cannot be called from an Enterprise. |
invalid_auth | Some aspect of authentication cannot be validated. Either the provided token is invalid or the request originates from an IP address disallowed from making the request. |
is_bot | This method cannot be called by a legacy bot. |
method_deprecated | The method has been deprecated. |
missing_scope | The token used is not granted the specific scope permissions required to complete this request. |
not_allowed_token_type | The token type used in this request is not allowed. |
not_authed | No authentication token provided. |
no_permission | The workspace token used in this request does not have the permissions necessary to complete the request. Make sure your app is a member of the conversation it's attempting to post a message to. |
org_login_required | The workspace is undergoing an enterprise migration and will not be available until migration is complete. |
token_expired | Authentication token has expired |
token_revoked | Authentication token is for a deleted user or workspace or the app has been removed when using a |
two_factor_setup_required | Two factor setup is required. |
accesslimited | Access to this method is limited on the current network |
fatal_error | The server could not complete your operation(s) without encountering a catastrophic error. It's possible some aspect of the operation succeeded before the error was raised. |
internal_error | The server could not complete your operation(s) without encountering an error, likely due to a transient issue on our end. It's possible some aspect of the operation succeeded before the error was raised. |
invalid_arg_name | The method was passed an argument whose name falls outside the bounds of accepted or expected values. This includes very long names and names with non-alphanumeric characters other than |
invalid_arguments | The method was either called with invalid arguments or some detail about the arguments passed is invalid, which is more likely when using complex arguments like blocks or attachments. |
invalid_array_arg | The method was passed an array as an argument. Please only input valid strings. |
invalid_charset | The method was called via a |
invalid_form_data | The method was called via a |
invalid_post_type | The method was called via a |
missing_post_type | The method was called via a |
ratelimited | The request has been ratelimited. Refer to the |
request_timeout | The method was called via a |
service_unavailable | The service is temporarily unavailable |
team_added_to_org | The workspace associated with your request is currently undergoing migration to an Enterprise Organization. Web API and other platform operations will be intermittently unavailable until the transition is complete. |
This table lists the expected warnings that this method will return. However, other warnings can be returned in the case where the service is experiencing unexpected trouble.
Warning | Description |
---|---|
missing_charset | The method was called via a |
superfluous_charset | The method was called via a |