3 files changed, 39 insertions, 19 deletions
diff --git a/doc/api/users.md b/doc/api/users.md
index 8290279c295..a8858468cab 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -448,10 +448,17 @@ Get the status of the currently signed in user.
 GET /user/status
 ```
 
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/user/status"
+```
+
+Example response:
+
 ```json
 {
   "emoji":"coffee",
-  "message":"I crave coffee"
+  "message":"I crave coffee :coffee:",
+  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>"
 }
 ```
 
@@ -463,20 +470,24 @@ Get the status of a user.
 GET /users/:id_or_username/status
 ```
 
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id_or_username` | string | yes    | The id or username of the user to get a status of |
+
+```bash
+curl "https://gitlab.example.com/users/janedoe/status"
+```
+
+Example response:
+
 ```json
 {
   "emoji":"coffee",
-  "message":"I crave coffee"
+  "message":"I crave coffee :coffee:",
+  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>"
 }
 ```
 
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id_or_username` | string | yes    | The id or username of the user to get a status of |
-
-
 ## Set user status
 
 Set the status of the current user.
@@ -485,21 +496,26 @@ Set the status of the current user.
 PUT /user/status
 ```
 
-```json
-{
-  "emoji":"coffee",
-  "message":"I crave coffee"
-}
-```
-
-Parameters:
-
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `emoji`   | string | no     | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. |
 | `message` | string | no     | The message to set as a status. It can also contain emoji codes. |
 
-When both parameters are empty, the status will be cleared.
+When both parameters `emoji` and `message` are empty, the status will be cleared.
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "emoji=coffee" --data "emoji=I crave coffee" https://gitlab.example.com/api/v4/user/status
+```
+
+Example responses
+
+```json
+{
+  "emoji":"coffee",
+  "message":"I crave coffee",
+  "message_html": "I crave coffee"
+}
+```
 
 ## List user projects
 
diff --git a/lib/api/entities.rb b/lib/api/entities.rb
index f5a22e76efe..efd148c1a7f 100644
--- a/lib/api/entities.rb
+++ b/lib/api/entities.rb
@@ -65,6 +65,9 @@ module API
     class UserStatus < Grape::Entity
       expose :emoji
       expose :message
+      expose :message_html do |entity|
+        MarkupHelper.markdown_field(entity, :message)
+      end
     end
 
     class Email < Grape::Entity
diff --git a/spec/requests/api/users_spec.rb b/spec/requests/api/users_spec.rb
index da503897760..d48d577afa1 100644
--- a/spec/requests/api/users_spec.rb
+++ b/spec/requests/api/users_spec.rb
@@ -21,6 +21,7 @@ describe API::Users do
 
       expect(response).to have_gitlab_http_status(:success)
       expect(json_response['message']).to be_present
+      expect(json_response['message_html']).to be_present
       expect(json_response['emoji']).to be_present
     end