chore: API documentation updates for CSAT surveys (#7255)

- Expose conversation uuid in APIs
- swagger documentation for cast survey update via public/message/update endpoints
- swagger documentation for survey/responses/conversation_uuid endpoint

Fixes: #6328

app/views/api/v1/conversations/partials/_conversation.json.jbuilder

@@ -26,6 +26,7 @@ else
 end
 
 json.account_id conversation.account_id
+json.uuid conversation.uuid
 json.additional_attributes conversation.additional_attributes
 json.agent_last_seen_at conversation.agent_last_seen_at.to_i
 json.assignee_last_seen_at conversation.assignee_last_seen_at.to_i

app/views/api/v1/models/_conversation.json.jbuilder

@@ -1,4 +1,5 @@
 json.id conversation.display_id
+json.uuid conversation.uuid
 json.created_at conversation.created_at.to_i
 json.contact do
   json.id conversation.contact.id

app/views/public/api/v1/models/_conversation.json.jbuilder

@@ -1,4 +1,5 @@
 json.id resource.display_id
+json.uuid resource.uuid
 json.inbox_id resource.inbox_id
 json.contact_last_seen_at resource.contact_last_seen_at.to_i
 json.status resource.status

spec/controllers/api/v1/accounts/conversations_controller_spec.rb

@@ -32,6 +32,7 @@ RSpec.describe 'Conversations API', type: :request do
         body = JSON.parse(response.body, symbolize_names: true)
         expect(body[:data][:meta][:all_count]).to eq(1)
         expect(body[:data][:meta].keys).to include(:all_count, :mine_count, :assigned_count, :unassigned_count)
+        expect(body[:data][:payload].first[:uuid]).to eq(conversation.uuid)
         expect(body[:data][:payload].first[:messages].first[:id]).to eq(message.id)
       end
 

spec/controllers/public/api/v1/inbox/conversations_controller_spec.rb

@@ -13,6 +13,7 @@ RSpec.describe 'Public Inbox Contact Conversations API', type: :request do
       expect(response).to have_http_status(:success)
       data = response.parsed_body
       expect(data.length).to eq 1
+      expect(data.first['uuid']).to eq contact_inbox.conversations.first.uuid
     end
 
     it 'does not return any private or activity message' do

swagger/definitions/request/public/message/update_payload.yml

@@ -2,7 +2,19 @@
 type: object
 properties:
   submitted_values:
-    type: object
+    oneOf:
-    description: Replies to the Bot Message Types
+      - type: object
-
+        description: Replies to the Bot Message Types
-  
+        properties:
+          csat_survey_response:
+            type: object
+            description: CSAT Survey Response if original message is CSAT Survey
+            properties:
+              rating:
+                type: integer
+                description: CSAT Rating
+                example: 5
+              feedback_message:
+                type: string
+                description: CSAT Comment
+                example: 'Great'

swagger/index.yml

@@ -75,3 +75,6 @@ x-tagGroups:
       - Contacts API
       - Conversations API
       - Messages API
+  - name: Others
+    tags:
+      - CSAT Survey Page

swagger/parameters/conversation_uuid.yml

@@ -0,0 +1,5 @@
+in: path
+name: conversation_uuid
+type: integer
+required: true
+description: The uuid of the conversation

swagger/parameters/index.yml

@@ -22,6 +22,9 @@ contact_sort_param:
 conversation_id:
   $ref: ./conversation_id.yml
 
+conversation_uuid:
+  $ref: ./conversation_uuid.yml
+
 custom_filter_id:
   $ref: ./custom_filter_id.yml
 

swagger/paths/index.yml

@@ -124,6 +124,16 @@
 
 # ---------------- end of public api routes-----------#
 
+# ------------ Other routes  ------------#
+
+/survey/responses/{conversation_uuid}:
+  parameters:
+    - $ref: '#/parameters/conversation_uuid'
+  get:
+    $ref: ./survey/show.yml
+
+# ----------- end of other routes -----------#
+
 # ------------  Application API routes  ------------#
 
 

swagger/paths/survey/show.yml

@@ -0,0 +1,9 @@
+tags:
+  - CSAT Survey Page
+operationId: get-csat-survey-page
+summary: Get CSAT survey page
+description: You can redirect the client to this URL, instead of implementing the CSAT survey component yourself.
+security: []
+responses:
+  200:
+    description: Success

swagger/swagger.json

@@ -1000,6 +1000,29 @@
         }
       }
     },
+    "/survey/responses/{conversation_uuid}": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/conversation_uuid"
+        }
+      ],
+      "get": {
+        "tags": [
+          "CSAT Survey Page"
+        ],
+        "operationId": "get-csat-survey-page",
+        "summary": "Get CSAT survey page",
+        "description": "You can redirect the client to this URL, instead of implementing the CSAT survey component yourself.",
+        "security": [
+
+        ],
+        "responses": {
+          "200": {
+            "description": "Success"
+          }
+        }
+      }
+    },
     "/api/v1/accounts/{account_id}/agent_bots": {
       "parameters": [
         {
@@ -6567,8 +6590,30 @@
       "type": "object",
       "properties": {
         "submitted_values": {
-          "type": "object",
+          "oneOf": [
-          "description": "Replies to the Bot Message Types"
+            {
+              "type": "object",
+              "description": "Replies to the Bot Message Types",
+              "properties": {
+                "csat_survey_response": {
+                  "type": "object",
+                  "description": "CSAT Survey Response if original message is CSAT Survey",
+                  "properties": {
+                    "rating": {
+                      "type": "integer",
+                      "description": "CSAT Rating",
+                      "example": 5
+                    },
+                    "feedback_message": {
+                      "type": "string",
+                      "description": "CSAT Comment",
+                      "example": "Great"
+                    }
+                  }
+                }
+              }
+            }
+          ]
         }
       }
     },
@@ -6973,6 +7018,13 @@
       "required": true,
       "description": "The numeric ID of the conversation"
     },
+    "conversation_uuid": {
+      "in": "path",
+      "name": "conversation_uuid",
+      "type": "integer",
+      "required": true,
+      "description": "The uuid of the conversation"
+    },
     "custom_filter_id": {
       "in": "path",
       "name": "custom_filter_id",
@@ -7093,6 +7145,12 @@
         "Conversations API",
         "Messages API"
       ]
+    },
+    {
+      "name": "Others",
+      "tags": [
+        "CSAT Survey Page"
+      ]
     }
   ]
 }