From 37cb46238af99b78ba44093e0e41ff453d496cb9 Mon Sep 17 00:00:00 2001 From: Tejaswini Chile Date: Tue, 14 Jun 2022 10:35:56 +0530 Subject: [PATCH] chore: Add documentation for automation rule, fix conversation/inbox_members (#4852) --- swagger/definitions/index.yml | 6 + .../automation_rule/create_update_payload.yml | 41 ++ .../definitions/resource/automation_rule.yml | 45 ++ swagger/definitions/resource/contact.yml | 4 + swagger/definitions/resource/conversation.yml | 4 + swagger/index.yml | 1 + .../application/automation_rule/create.yml | 20 + .../application/automation_rule/delete.yml | 20 + .../application/automation_rule/index.yml | 20 + .../application/automation_rule/show.yml | 20 + .../application/automation_rule/update.yml | 27 + .../paths/application/conversation/index.yml | 6 +- .../application/custom_attributes/delete.yml | 1 + .../application/custom_attributes/show.yml | 7 + .../paths/application/team_members/index.yml | 1 + swagger/paths/index.yml | 35 +- swagger/swagger.json | 506 +++++++++++++++--- 17 files changed, 695 insertions(+), 69 deletions(-) create mode 100644 swagger/definitions/request/automation_rule/create_update_payload.yml create mode 100644 swagger/definitions/resource/automation_rule.yml create mode 100644 swagger/paths/application/automation_rule/create.yml create mode 100644 swagger/paths/application/automation_rule/delete.yml create mode 100644 swagger/paths/application/automation_rule/index.yml create mode 100644 swagger/paths/application/automation_rule/show.yml create mode 100644 swagger/paths/application/automation_rule/update.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index 5e22a7099..5e4e50b04 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -16,6 +16,8 @@ canned_response: $ref: ./resource/canned_response.yml custom_attribute: $ref: ./resource/custom_attribute.yml +automation_rule: + $ref: ./resource/automation_rule.yml contact: $ref: ./resource/contact.yml conversation: @@ -102,6 +104,10 @@ integrations_hook_create_payload: integrations_hook_update_payload: $ref: ./request/integrations/hook_update_payload.yml +# Automation Rule +automation_rule_create_update_payload: + $ref: ./request/automation_rule/create_update_payload.yml + ## public requests public_contact_create_update_payload: diff --git a/swagger/definitions/request/automation_rule/create_update_payload.yml b/swagger/definitions/request/automation_rule/create_update_payload.yml new file mode 100644 index 000000000..20d362e48 --- /dev/null +++ b/swagger/definitions/request/automation_rule/create_update_payload.yml @@ -0,0 +1,41 @@ +type: object +properties: + name: + type: string + description: Rule name + example: Add label on message create event + description: + type: string + description: The description about the automation and actions + example: Add label support and sales on message create event if incoming message content contains text help + event_name: + type: string + enum: + - conversation_created + - conversation_updated + - message_created + example: message_created + description: The event when you want to execute the automation actions + active: + type: boolean + description: Enable/disable automation rule + actions: + type: array + description: Array of actions which you want to perform when condition matches, e.g add label support if message contains content help. + items: + type: object + example: + action_name: add_label + action_params: + - support + conditions: + type: array + description: Array of conditions on which conversation filter would work, e.g message content contains text help. + items: + type: object + example: + attribute_key: content + filter_operator: contains + query_operator: nil + values: + - help diff --git a/swagger/definitions/resource/automation_rule.yml b/swagger/definitions/resource/automation_rule.yml new file mode 100644 index 000000000..4a3a03d01 --- /dev/null +++ b/swagger/definitions/resource/automation_rule.yml @@ -0,0 +1,45 @@ +type: object +properties: + event_name: + type: string + description: Automation Rule event, on which we call the actions(conversation_created, conversation_updated, message_created) + enum: + - conversation_created + - conversation_updated + - message_created + example: message_created + name: + type: string + description: The name of the rule + example: Add label on message create event + description: + type: string + description: Description to give more context about the rule + example: Add label support and sales on message create event if incoming message content contains text help + active: + type: boolean + description: Enable/disable automation rule + actions: + type: array + description: Array of actions which we perform when condition matches + items: + type: object + example: + action_name: add_label + action_params: + - support + - sales + conditions: + type: array + description: Array of conditions on which conversation/message filter would work + items: + type: object + example: + attribute_key: content + filter_operator: contains + values: + - help + query_operator: nil + account_id: + type: integer + description: Account Id diff --git a/swagger/definitions/resource/contact.yml b/swagger/definitions/resource/contact.yml index e2462c08b..2e72a9834 100644 --- a/swagger/definitions/resource/contact.yml +++ b/swagger/definitions/resource/contact.yml @@ -15,6 +15,10 @@ properties: additional_attributes: type: object description: The object containing additional attributes related to the contact + custom_attributes: + type: object + description: The object to save custom attributes for contact, accepts custom attributes key and value + example: { attribute_key: attribute_value, signed_up_at: dd/mm/yyyy } contact_inboxes: type: array items: diff --git a/swagger/definitions/resource/conversation.yml b/swagger/definitions/resource/conversation.yml index 24c27f681..085d21879 100644 --- a/swagger/definitions/resource/conversation.yml +++ b/swagger/definitions/resource/conversation.yml @@ -30,3 +30,7 @@ properties: additional_attributes: type: object description: The object containing additional attributes related to the conversation + custom_attributes: + type: object + description: The object to save custom attributes for conversation, accepts custom attributes key and value + example: { attribute_key: attribute_value, priority_conversation_number: 3 } diff --git a/swagger/index.yml b/swagger/index.yml index f64a090e7..3dc245ddf 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -68,6 +68,7 @@ x-tagGroups: - Reports - Teams - Webhooks + - Automation Rule - name: Client tags: - Contacts API diff --git a/swagger/paths/application/automation_rule/create.yml b/swagger/paths/application/automation_rule/create.yml new file mode 100644 index 000000000..ac5de803a --- /dev/null +++ b/swagger/paths/application/automation_rule/create.yml @@ -0,0 +1,20 @@ +tags: + - Automation Rule +operationId: add-new-automation-rule-to-account +summary: Add a new automation rule +description: Add a new automation rule to account +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/automation_rule_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/automation_rule' + '403': + description: Access denied diff --git a/swagger/paths/application/automation_rule/delete.yml b/swagger/paths/application/automation_rule/delete.yml new file mode 100644 index 000000000..f82647d1d --- /dev/null +++ b/swagger/paths/application/automation_rule/delete.yml @@ -0,0 +1,20 @@ +tags: + - Automation Rule +operationId: delete-automation-rule-from-account +summary: Remove a automation rule from account +description: Remove a automation rule from account +security: + - userApiKey: [] +parameters: + - in: path + name: id + type: integer + required: true + description: The ID of the automation rule to be deleted +responses: + '200': + description: Success + '403': + description: Access denied + '404': + description: automation rule not found diff --git a/swagger/paths/application/automation_rule/index.yml b/swagger/paths/application/automation_rule/index.yml new file mode 100644 index 000000000..031696aeb --- /dev/null +++ b/swagger/paths/application/automation_rule/index.yml @@ -0,0 +1,20 @@ +tags: + - Automation Rule +operationId: get-account-automation-rule +summary: List all automation rules in an account +parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/page' +description: Get details of automation rules in an Account +security: + - userApiKey: [] +responses: + '200': + description: Success + schema: + type: array + description: Array of all automation rules + items: + $ref: '#/definitions/automation_rule' + '403': + description: Access denied diff --git a/swagger/paths/application/automation_rule/show.yml b/swagger/paths/application/automation_rule/show.yml new file mode 100644 index 000000000..d99f8170b --- /dev/null +++ b/swagger/paths/application/automation_rule/show.yml @@ -0,0 +1,20 @@ +tags: + - Automation Rule +operationId: get-details-of-a-single-automation-rule +summary: Get a automation rule details +description: Get the details of a automation rule in the account +parameters: + - in: path + name: id + type: integer + required: true + description: The ID of the automation rule to be updated. +responses: + '200': + description: Success + schema: + $ref: '#/definitions/automation_rule' + '401': + description: Unauthorized + '404': + description: The given rule ID does not exist in the account diff --git a/swagger/paths/application/automation_rule/update.yml b/swagger/paths/application/automation_rule/update.yml new file mode 100644 index 000000000..35a4cb67a --- /dev/null +++ b/swagger/paths/application/automation_rule/update.yml @@ -0,0 +1,27 @@ +tags: + - Automation Rule +operationId: update-automation-rule-in-account +summary: Update automation rule in Account +description: Update a automation rule in account +security: + - userApiKey: [] +parameters: + - in: path + name: id + type: integer + required: true + description: The ID of the automation rule to be updated. + - name: data + in: body + required: true + schema: + $ref: '#/definitions/automation_rule_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/automation_rule' + '403': + description: Access denied + '404': + description: Rule not found diff --git a/swagger/paths/application/conversation/index.yml b/swagger/paths/application/conversation/index.yml index 54650f4d2..4c9241464 100644 --- a/swagger/paths/application/conversation/index.yml +++ b/swagger/paths/application/conversation/index.yml @@ -40,7 +40,7 @@ get: type: integer default: 1 description: paginate through conversations - + responses: 200: description: Success @@ -79,6 +79,10 @@ post: additional_attributes: type: object description: Lets you specify attributes like browser information + custom_attributes: + type: object + description: The object to save custom attributes for conversation, accepts custom attributes key and value + example: { attribute_key: attribute_value, priority_conversation_number: 3 } status: type: string enum: ['open', 'resolved', 'pending'] diff --git a/swagger/paths/application/custom_attributes/delete.yml b/swagger/paths/application/custom_attributes/delete.yml index cfdb68adc..0c9aaedee 100644 --- a/swagger/paths/application/custom_attributes/delete.yml +++ b/swagger/paths/application/custom_attributes/delete.yml @@ -6,6 +6,7 @@ description: Remove a custom attribute from account security: - userApiKey: [] parameters: + - $ref: '#/parameters/account_id' - in: path name: id type: integer diff --git a/swagger/paths/application/custom_attributes/show.yml b/swagger/paths/application/custom_attributes/show.yml index 4e6f61e49..8449ba9be 100644 --- a/swagger/paths/application/custom_attributes/show.yml +++ b/swagger/paths/application/custom_attributes/show.yml @@ -3,6 +3,13 @@ tags: operationId: get-details-of-a-single-custom-attribute summary: Get a custom attribute details description: Get the details of a custom attribute in the account +parameters: + - $ref: '#/parameters/account_id' + - in: path + name: id + type: integer + required: true + description: The ID of the custom attribute to be updated. responses: 200: description: Success diff --git a/swagger/paths/application/team_members/index.yml b/swagger/paths/application/team_members/index.yml index dc28f2e99..c57705223 100644 --- a/swagger/paths/application/team_members/index.yml +++ b/swagger/paths/application/team_members/index.yml @@ -6,6 +6,7 @@ description: Get Details of Agents in an Team security: - userApiKey: [] parameters: + - $ref: '#/parameters/account_id' - $ref: '#/parameters/team_id' responses: 200: diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index 084065a9a..a7b853cb8 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -181,6 +181,11 @@ /api/v1/accounts/{account_id}/custom_attribute_definitions/{id}: parameters: - $ref: '#/parameters/account_id' + - name: id + in: path + type: number + description: ID of the custom attribute + required: true get: $ref: './application/custom_attributes/show.yml' patch: @@ -208,6 +213,30 @@ $ref: ./application/contactable_inboxes/get.yml +# Automation Rule +/api/v1/accounts/{account_id}/automation_rule_definitions: + parameters: + - $ref: '#/parameters/account_id' + get: + $ref: ./application/automation_rule/index.yml + post: + $ref: ./application/automation_rule/create.yml +/api/v1/accounts/{account_id}/automation_rule_definitions/{id}: + parameters: + - $ref: '#/parameters/account_id' + - name: id + in: path + type: number + description: ID of the Automation Rule + required: true + get: + $ref: ./application/automation_rule/show.yml + patch: + $ref: ./application/automation_rule/update.yml + delete: + $ref: ./application/automation_rule/delete.yml + + # Conversations /api/v1/accounts/{account_id}/conversations/meta: $ref: ./application/conversation/meta.yml @@ -273,8 +302,6 @@ - $ref: '#/parameters/inbox_id' get: $ref: ./application/inboxes/inbox_members/show.yml - patch: - $ref: ./application/inboxes/inbox_members/update.yml delete: $ref: ./application/inboxes/inbox_members/delete.yml @@ -283,6 +310,8 @@ - $ref: '#/parameters/account_id' post: $ref: ./application/inboxes/inbox_members/create.yml + patch: + $ref: ./application/inboxes/inbox_members/update.yml @@ -345,7 +374,7 @@ $ref: ./application/teams/update.yml delete: $ref: ./application/teams/delete.yml -/accounts/{account-id}/teams/{team_id}/team_members: +/accounts/{account_id}/teams/{team_id}/team_members: parameters: - $ref: '#/parameters/account_id' - $ref: '#/parameters/team_id' diff --git a/swagger/swagger.json b/swagger/swagger.json index 9103fe13e..483aa3402 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -1584,6 +1584,13 @@ "parameters": [ { "$ref": "#/parameters/account_id" + }, + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the custom attribute", + "required": true } ], "get": { @@ -1593,6 +1600,18 @@ "operationId": "get-details-of-a-single-custom-attribute", "summary": "Get a custom attribute details", "description": "Get the details of a custom attribute in the account", + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the custom attribute to be updated." + } + ], "responses": { "200": { "description": "Success", @@ -1669,6 +1688,9 @@ } ], "parameters": [ + { + "$ref": "#/parameters/account_id" + }, { "in": "path", "name": "id", @@ -2135,6 +2157,213 @@ } } }, + "/api/v1/accounts/{account_id}/automation_rule_definitions": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "get": { + "tags": [ + "Automation Rule" + ], + "operationId": "get-account-automation-rule", + "summary": "List all automation rules in an account", + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/page" + } + ], + "description": "Get details of automation rules in an Account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "type": "array", + "description": "Array of all automation rules", + "items": { + "$ref": "#/definitions/automation_rule" + } + } + }, + "403": { + "description": "Access denied" + } + } + }, + "post": { + "tags": [ + "Automation Rule" + ], + "operationId": "add-new-automation-rule-to-account", + "summary": "Add a new automation rule", + "description": "Add a new automation rule to account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/automation_rule_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/automation_rule" + } + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/api/v1/accounts/{account_id}/automation_rule_definitions/{id}": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the Automation Rule", + "required": true + } + ], + "get": { + "tags": [ + "Automation Rule" + ], + "operationId": "get-details-of-a-single-automation-rule", + "summary": "Get a automation rule details", + "description": "Get the details of a automation rule in the account", + "parameters": [ + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the automation rule to be updated." + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/automation_rule" + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "The given rule ID does not exist in the account" + } + } + }, + "patch": { + "tags": [ + "Automation Rule" + ], + "operationId": "update-automation-rule-in-account", + "summary": "Update automation rule in Account", + "description": "Update a automation rule in account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the automation rule to be updated." + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/automation_rule_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/automation_rule" + } + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "Rule not found" + } + } + }, + "delete": { + "tags": [ + "Automation Rule" + ], + "operationId": "delete-automation-rule-from-account", + "summary": "Remove a automation rule from account", + "description": "Remove a automation rule from account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the automation rule to be deleted" + } + ], + "responses": { + "200": { + "description": "Success" + }, + "403": { + "description": "Access denied" + }, + "404": { + "description": "automation rule not found" + } + } + } + }, "/api/v1/accounts/{account_id}/conversations/meta": { "parameters": [ { @@ -2352,6 +2581,14 @@ "type": "object", "description": "Lets you specify attributes like browser information" }, + "custom_attributes": { + "type": "object", + "description": "The object to save custom attributes for conversation, accepts custom attributes key and value", + "example": { + "attribute_key": "attribute_value", + "priority_conversation_number": 3 + } + }, "status": { "type": "string", "enum": [ @@ -3101,69 +3338,6 @@ } } }, - "patch": { - "tags": [ - "Inboxes" - ], - "operationId": "update-agents-in-inbox", - "summary": "Update Agents in Inbox", - "description": "All agents except the one passed in params will be removed", - "security": [ - { - "userApiKey": [ - - ] - } - ], - "parameters": [ - { - "name": "data", - "in": "body", - "required": true, - "schema": { - "type": "object", - "required": [ - "inbox_id", - "user_ids" - ], - "properties": { - "inbox_id": { - "type": "string", - "description": "The ID of the inbox" - }, - "user_ids": { - "type": "array", - "items": { - "type": "integer" - }, - "description": "IDs of users to be added to the inbox" - } - } - } - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "type": "array", - "description": "Array of all active agents", - "items": { - "$ref": "#/definitions/agent" - } - } - }, - "404": { - "description": "Inbox not found" - }, - "403": { - "description": "Access denied" - }, - "422": { - "description": "User must exist" - } - } - }, "delete": { "tags": [ "Inboxes" @@ -3289,6 +3463,69 @@ "description": "User must exist" } } + }, + "patch": { + "tags": [ + "Inboxes" + ], + "operationId": "update-agents-in-inbox", + "summary": "Update Agents in Inbox", + "description": "All agents except the one passed in params will be removed", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "required": [ + "inbox_id", + "user_ids" + ], + "properties": { + "inbox_id": { + "type": "string", + "description": "The ID of the inbox" + }, + "user_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "IDs of users to be added to the inbox" + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "type": "array", + "description": "Array of all active agents", + "items": { + "$ref": "#/definitions/agent" + } + } + }, + "404": { + "description": "Inbox not found" + }, + "403": { + "description": "Access denied" + }, + "422": { + "description": "User must exist" + } + } } }, "/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages": { @@ -3711,7 +3948,7 @@ } } }, - "/accounts/{account-id}/teams/{team_id}/team_members": { + "/accounts/{account_id}/teams/{team_id}/team_members": { "parameters": [ { "$ref": "#/parameters/account_id" @@ -3735,6 +3972,9 @@ } ], "parameters": [ + { + "$ref": "#/parameters/account_id" + }, { "$ref": "#/parameters/team_id" } @@ -4520,6 +4760,68 @@ } } }, + "automation_rule": { + "type": "object", + "properties": { + "event_name": { + "type": "string", + "description": "Automation Rule event, on which we call the actions(conversation_created, conversation_updated, message_created)", + "enum": [ + "conversation_created", + "conversation_updated", + "message_created" + ], + "example": "message_created" + }, + "name": { + "type": "string", + "description": "The name of the rule", + "example": "Add label on message create event" + }, + "description": { + "type": "string", + "description": "Description to give more context about the rule", + "example": "Add label support and sales on message create event if incoming message content contains text help" + }, + "active": { + "type": "boolean", + "description": "Enable/disable automation rule" + }, + "actions": { + "type": "array", + "description": "Array of actions which we perform when condition matches", + "items": { + "type": "object", + "example": { + "action_name": "add_label", + "action_params": [ + "support", + "sales" + ] + } + } + }, + "conditions": { + "type": "array", + "description": "Array of conditions on which conversation/message filter would work", + "items": { + "type": "object", + "example": { + "attribute_key": "content", + "filter_operator": "contains", + "values": [ + "help" + ], + "query_operator": "nil" + } + } + }, + "account_id": { + "type": "integer", + "description": "Account Id" + } + } + }, "contact": { "type": "object", "properties": { @@ -4543,6 +4845,14 @@ "type": "object", "description": "The object containing additional attributes related to the contact" }, + "custom_attributes": { + "type": "object", + "description": "The object to save custom attributes for contact, accepts custom attributes key and value", + "example": { + "attribute_key": "attribute_value", + "signed_up_at": "dd/mm/yyyy" + } + }, "contact_inboxes": { "type": "array", "items": { @@ -4598,6 +4908,14 @@ "additional_attributes": { "type": "object", "description": "The object containing additional attributes related to the conversation" + }, + "custom_attributes": { + "type": "object", + "description": "The object to save custom attributes for conversation, accepts custom attributes key and value", + "example": { + "attribute_key": "attribute_value", + "priority_conversation_number": 3 + } } } }, @@ -5428,6 +5746,63 @@ } } }, + "automation_rule_create_update_payload": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Rule name", + "example": "Add label on message create event" + }, + "description": { + "type": "string", + "description": "The description about the automation and actions", + "example": "Add label support and sales on message create event if incoming message content contains text help" + }, + "event_name": { + "type": "string", + "enum": [ + "conversation_created", + "conversation_updated", + "message_created" + ], + "example": "message_created", + "description": "The event when you want to execute the automation actions" + }, + "active": { + "type": "boolean", + "description": "Enable/disable automation rule" + }, + "actions": { + "type": "array", + "description": "Array of actions which you want to perform when condition matches, e.g add label support if message contains content help.", + "items": { + "type": "object", + "example": { + "action_name": "add_label", + "action_params": [ + "support" + ] + } + } + }, + "conditions": { + "type": "array", + "description": "Array of conditions on which conversation filter would work, e.g message content contains text help.", + "items": { + "type": "object", + "example": { + "attribute_key": "content", + "filter_operator": "contains", + "query_operator": "nil", + "values": [ + "help" + ] + } + } + } + } + }, "public_contact_create_update_payload": { "type": "object", "properties": { @@ -6016,7 +6391,8 @@ "Profile", "Reports", "Teams", - "Webhooks" + "Webhooks", + "Automation Rule" ] }, {