From 260e40831a3256b2c2008e588b5efe29c7adeefb Mon Sep 17 00:00:00 2001 From: Pranav Raj S Date: Wed, 11 Mar 2020 16:19:13 +0530 Subject: [PATCH] Chore: Update Swagger API docs (#608) --- swagger/definitions/index.yml | 3 +- .../request/conversation/create_message.yml | 7 +- swagger/definitions/resource/contact.yml | 5 + swagger/definitions/resource/conversation.yml | 14 +- .../extension/contact/conversation.yml | 4 + .../resource/extension/contact/show.yml | 4 +- .../extension/conversation/labels.yml | 2 +- .../resource/extension/conversation/show.yml | 22 +- swagger/definitions/resource/inbox.yml | 20 + swagger/definitions/resource/message.yml | 16 +- swagger/index.yml | 13 +- swagger/paths/conversation/assignments.yml | 4 +- swagger/paths/conversation/labels.yml | 12 +- swagger/paths/conversation/list.yml | 22 +- swagger/paths/conversation/messages.yml | 28 - .../conversation/messages/index_create.yml | 54 + swagger/paths/conversation/toggle_status.yml | 15 +- swagger/paths/inboxes/index.yml | 17 + swagger/paths/inboxes/update.yml | 33 + swagger/paths/index.yml | 46 +- swagger/paths/widget/inboxes/create.yml | 34 + swagger/paths/widget/inboxes/update.yml | 28 + swagger/swagger.json | 1074 +++++++++++------ 23 files changed, 1014 insertions(+), 463 deletions(-) create mode 100644 swagger/definitions/resource/inbox.yml delete mode 100644 swagger/paths/conversation/messages.yml create mode 100644 swagger/paths/conversation/messages/index_create.yml create mode 100644 swagger/paths/inboxes/index.yml create mode 100644 swagger/paths/inboxes/update.yml create mode 100644 swagger/paths/widget/inboxes/create.yml create mode 100644 swagger/paths/widget/inboxes/update.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index e1e78e421..f88892efd 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -15,7 +15,8 @@ message: $ref: ./resource/message.yml user: $ref: ./resource/user.yml - +inbox: + $ref: ./resource/inbox.yml # RESPONSE ## contact diff --git a/swagger/definitions/request/conversation/create_message.yml b/swagger/definitions/request/conversation/create_message.yml index e307f461b..02a5564cb 100644 --- a/swagger/definitions/request/conversation/create_message.yml +++ b/swagger/definitions/request/conversation/create_message.yml @@ -2,9 +2,12 @@ type: object properties: conversation_id: type: number + description: ID of the conversation + required: true message: type: string + description: The content of the message + required: true private: type: boolean - fb_id: - type: number + description: Flag to identify if it is a private note diff --git a/swagger/definitions/resource/contact.yml b/swagger/definitions/resource/contact.yml index 01261239a..be407b20b 100644 --- a/swagger/definitions/resource/contact.yml +++ b/swagger/definitions/resource/contact.yml @@ -2,11 +2,16 @@ type: object properties: email: type: string + description: Email address of the contact name: type: string + description: The name of the contact phone_number: type: string + description: Phone number of the contact thumbnail: type: string + description: Avatar URL of the contact additional_attributes: type: object + description: The object containing additional attributes related to the contact diff --git a/swagger/definitions/resource/conversation.yml b/swagger/definitions/resource/conversation.yml index bb9d008ce..204810534 100644 --- a/swagger/definitions/resource/conversation.yml +++ b/swagger/definitions/resource/conversation.yml @@ -1,19 +1,27 @@ type: object properties: + id: + type: number + description: ID of the conversation messages: type: array - items: - type: object inbox_id: type: number + description: ID of the inbox status: type: string - enum: ['open', 'resolved'] + enum: ['open', 'resolved', 'bot'] + description: The status of the conversation timestamp: type: string + description: The time at which conversation was created user_last_seen_at: type: string agent_last_seen_at: type: agent_last_seen_at unread_count: type: number + description: The number of unread messages + additional_attributes: + type: object + description: The object containing additional attributes related to the conversation diff --git a/swagger/definitions/resource/extension/contact/conversation.yml b/swagger/definitions/resource/extension/contact/conversation.yml index 57be12bdc..6e6576f80 100644 --- a/swagger/definitions/resource/extension/contact/conversation.yml +++ b/swagger/definitions/resource/extension/contact/conversation.yml @@ -8,11 +8,15 @@ properties: properties: id: type: number + description: ID fo the sender name: type: string + description: The name of the sender thumbnail: type: string + description: Avatar URL of the contact channel: type: string + description: Channel Type assignee: $ref: '#/definitions/user' diff --git a/swagger/definitions/resource/extension/contact/show.yml b/swagger/definitions/resource/extension/contact/show.yml index a4c26f306..2f29ee0a9 100644 --- a/swagger/definitions/resource/extension/contact/show.yml +++ b/swagger/definitions/resource/extension/contact/show.yml @@ -2,6 +2,8 @@ type: object properties: id: type: number + description: Id of the user availability_status: type: string - enum: ['online', 'offline'] \ No newline at end of file + enum: ['online', 'offline'] + description: Availability status of the user diff --git a/swagger/definitions/resource/extension/conversation/labels.yml b/swagger/definitions/resource/extension/conversation/labels.yml index d8b181269..2922d9b4b 100644 --- a/swagger/definitions/resource/extension/conversation/labels.yml +++ b/swagger/definitions/resource/extension/conversation/labels.yml @@ -2,6 +2,6 @@ type: object properties: payload: type: array - description: 'array of labels' + description: Array of labels items: type: string diff --git a/swagger/definitions/resource/extension/conversation/show.yml b/swagger/definitions/resource/extension/conversation/show.yml index 15d0007fb..8f44436e9 100644 --- a/swagger/definitions/resource/extension/conversation/show.yml +++ b/swagger/definitions/resource/extension/conversation/show.yml @@ -1,19 +1,5 @@ type: object -properties: - meta: - type: object - properties: - labels: - type: array - items: - type: string - additional_attributes: - type: object - contact_id: - type: number - payload: - type: array - description: 'array of messages' - items: - allOf: - - $ref: '#/definitions/extended_message' +allOf: + - $ref: '#/definitions/generic_id' + - $ref: '#/definitions/conversation' + - $ref: '../contact/conversation.yml' diff --git a/swagger/definitions/resource/inbox.yml b/swagger/definitions/resource/inbox.yml new file mode 100644 index 000000000..9575bebfe --- /dev/null +++ b/swagger/definitions/resource/inbox.yml @@ -0,0 +1,20 @@ +type: object +properties: + id: + type: number + description: ID of the inbox + channel_type: + type: string + description: The type of the inbox + avatar_url: + type: string + description: The avatar image of the inbox + widget_color: + type: string + description: Widget Color used for customization of the widget + website_token: + type: string + description: Website Token + enable_auto_assignment: + type: boolean + description: The flag which shows whether Auto Assignment is enabled or not diff --git a/swagger/definitions/resource/message.yml b/swagger/definitions/resource/message.yml index 7b0d90706..a27a88d76 100644 --- a/swagger/definitions/resource/message.yml +++ b/swagger/definitions/resource/message.yml @@ -2,15 +2,23 @@ type: object properties: content: type: string - inbox_id: - type: number - conversation_id: - type: number + description: The text content of the message message_type: type: string + enum: ["incoming", "outgoing", "activity", "template"] + description: The type of the message created_at: type: integer + description: The time at which message was created private: type: boolean + description: The flags which shows whether the message is private or not attachment: type: object + description: The file object attached to the image + sender: + type: object + description: User/Agent/AgentBot object + conversation_id: + type: number + description: ID of the conversation diff --git a/swagger/index.yml b/swagger/index.yml index 44b75ca20..5fd289f37 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -1,6 +1,6 @@ swagger: 2.0 info: - description: This is the api documentation for Chatwoot server. + description: This is the API documentation for Chatwoot server. version: 1.0.0 title: Chatwoot termsOfService: https://www.chatwoot.com/terms-of-service/ @@ -9,8 +9,15 @@ info: license: name: MIT License url: https://opensource.org/licenses/MIT - host: app.chatwoot.com - basePath: /api/v1/ +host: app.chatwoot.com +basePath: /api/v1/ +schemes: + - https +produces: +- application/json; charset=utf-8 +consumes: +- application/json; charset=utf-8 + paths: $ref: ./paths/index.yml definitions: diff --git a/swagger/paths/conversation/assignments.yml b/swagger/paths/conversation/assignments.yml index 5f64d894d..7edfb0b48 100644 --- a/swagger/paths/conversation/assignments.yml +++ b/swagger/paths/conversation/assignments.yml @@ -1,6 +1,6 @@ post: tags: - - Conversation + - ConversationAssignment operationId: conversationAssignment summary: Assign Conversation description: Assign a conversation to an agent @@ -19,7 +19,7 @@ post: assignee_id: type: number responses: - 204: + 200: description: Success schema: $ref: '#/definitions/user' diff --git a/swagger/paths/conversation/labels.yml b/swagger/paths/conversation/labels.yml index 491fb0b20..d67c5de1a 100644 --- a/swagger/paths/conversation/labels.yml +++ b/swagger/paths/conversation/labels.yml @@ -1,6 +1,6 @@ get: tags: - - Conversation + - ConversationLabels operationId: conversationLabelsList summary: List Labels description: Lists all the labels of a conversation @@ -8,7 +8,7 @@ get: - name: id in: path type: number - description: id of the conversation + description: ID of the conversation required: true responses: 200: @@ -22,7 +22,7 @@ get: post: tags: - - Conversation + - ConversationLabels operationId: conversationAddLabels summary: Add Labels description: Creates new labels and associates it with the conversation @@ -30,7 +30,7 @@ post: - name: id in: path type: number - description: id of the conversation + description: ID of the conversation required: true - name: data in: body @@ -40,11 +40,11 @@ post: properties: labels: type: array - description: 'array of labels' + description: 'Array of labels' properties: type: string responses: - 204: + 200: description: Success schema: $ref: '#/definitions/conversation_labels' diff --git a/swagger/paths/conversation/list.yml b/swagger/paths/conversation/list.yml index b85b26a2a..1583bdfd5 100644 --- a/swagger/paths/conversation/list.yml +++ b/swagger/paths/conversation/list.yml @@ -5,9 +5,29 @@ get: description: List all the conversations with pagination summary: Conversations List parameters: - - name: query_hash + - name: assignee_type in: query type: string + enum: ['me', 'unassigned', 'all'] + required: true + - name: status + in: query + type: string + enum: ['open', 'resolved', 'bot'] + required: true + - name: page + in: query + type: integer + required: true + - name: inbox_id + in: query + type: integer + - name: labels + in: query + type: array + items: + type: string + responses: 200: description: Success diff --git a/swagger/paths/conversation/messages.yml b/swagger/paths/conversation/messages.yml deleted file mode 100644 index 7c57130ad..000000000 --- a/swagger/paths/conversation/messages.yml +++ /dev/null @@ -1,28 +0,0 @@ -post: - tags: - - Conversation - operationId: conversationNewMessage - summary: Create New Message - description: All the agent replies are created as new messages through this endpoint - parameters: - - name: id - in: path - type: number - description: id of the conversation - required: true - - name: data - in: body - required: true - schema: - $ref: '#/definitions/conversation_message_create' - responses: - 204: - description: Success - schema: - allOf: - - $ref: '#/definitions/generic_id' - - $ref: '#/definitions/message' - 404: - description: Conversation not found - 403: - description: Access denied diff --git a/swagger/paths/conversation/messages/index_create.yml b/swagger/paths/conversation/messages/index_create.yml new file mode 100644 index 000000000..a1f9e3279 --- /dev/null +++ b/swagger/paths/conversation/messages/index_create.yml @@ -0,0 +1,54 @@ +get: + tags: + - Messages + operationId: listAllMessages + summary: Get messages + description: List all messages of a conversation + parameters: + - name: id + in: path + type: number + description: ID of the conversation + required: true + responses: + 200: + description: Success + type: array + description: Array of messages + schema: + allOf: + - $ref: '#/definitions/generic_id' + - $ref: '#/definitions/message' + 404: + description: Conversation not found + 403: + description: Access denied + +post: + tags: + - Messages + operationId: conversationNewMessage + summary: Create New Message + description: All the agent replies are created as new messages through this endpoint + parameters: + - name: id + in: path + type: number + description: ID of the conversation + required: true + - name: data + in: body + required: true + schema: + $ref: '#/definitions/conversation_message_create' + responses: + 200: + description: Success + schema: + allOf: + - $ref: '#/definitions/generic_id' + - $ref: '#/definitions/message' + 404: + description: Conversation not found + 403: + description: Access denied diff --git a/swagger/paths/conversation/toggle_status.yml b/swagger/paths/conversation/toggle_status.yml index e1dd74bf5..5c934dde9 100644 --- a/swagger/paths/conversation/toggle_status.yml +++ b/swagger/paths/conversation/toggle_status.yml @@ -8,10 +8,21 @@ post: - name: id in: path type: number - description: id of the conversation + description: ID of the conversation required: true + - name: data + in: body + required: true + schema: + type: object + properties: + status: + type: string + enum: ["open", "resolved"] + required: true + description: The status of the conversation responses: - 204: + 200: description: Success schema: $ref: '#/definitions/conversation_status_toggle' diff --git a/swagger/paths/inboxes/index.yml b/swagger/paths/inboxes/index.yml new file mode 100644 index 000000000..dcb0e4b10 --- /dev/null +++ b/swagger/paths/inboxes/index.yml @@ -0,0 +1,17 @@ +get: + tags: + - Inbox + operationId: listAllInboxes + summary: List all inboxes + description: List all inboxes available in the current account + responses: + 200: + description: Success + schema: + type: array + description: 'Array of inboxes' + $ref: '#/definitions/inbox' + 404: + description: Inbox not found + 403: + description: Access denied diff --git a/swagger/paths/inboxes/update.yml b/swagger/paths/inboxes/update.yml new file mode 100644 index 000000000..bfa79c27c --- /dev/null +++ b/swagger/paths/inboxes/update.yml @@ -0,0 +1,33 @@ +patch: + tags: + - Inbox + operationId: disableAutoAssignment + summary: Disable auto assignment + description: Disable Auto Assignment for an inbox + parameters: + - name: id + in: path + type: number + description: ID of the inbox + required: true + - name: data + in: body + required: true + schema: + type: object + properties: + enable_auto_assignment: + type: boolean + required: true + description: 'Enable Auto Assignment' + responses: + 200: + description: Success + schema: + type: object + description: 'Updated inbox object' + $ref: '#/definitions/inbox' + 404: + description: Inbox not found + 403: + description: Access denied diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index c35912122..dbbd8ce89 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -1,23 +1,37 @@ -# Contacts -/contacts: - $ref: ./contact/list_create.yml -/contacts/{id}: - $ref: ./contact/crud.yml -/contacts/{id}/conversations: - $ref: ./contact/conversations.yml +# Widget +/account/{account_id}/widget/inboxes: + $ref: ./widget/inboxes/create.yml +/account/{account_id}/widget/inboxes/${id}: + $ref: ./widget/inboxes/update.yml + +# Inboxes +/account/{account_id}/inboxes: + $ref: ./inboxes/index.yml +/account/{account_id}/inboxes/{id}: + $ref: ./inboxes/update.yml # Conversations -/conversations: +/account/{account_id}/conversations: $ref: ./conversation/list.yml -/conversations/{id}: +/account/{account_id}/conversations/{id}: $ref: ./conversation/crud.yml -/conversations/{id}/toggle_status: +/account/{account_id}/conversations/{id}/toggle_status: $ref: ./conversation/toggle_status.yml -/conversations/{id}/update_last_seen: - $ref: ./conversation/update_last_seen.yml -/conversations/{id}/labels: + +# Messages +/account/{account_id}/conversations/{id}/messages: + $ref: ./conversation/messages/index_create.yml + +/account/{account_id}/conversations/{id}/labels: $ref: ./conversation/labels.yml -/conversations/{id}/assignments: + +/account/{account_id}/conversations/{id}/assignments: $ref: ./conversation/assignments.yml -/conversations/{id}/messages: - $ref: ./conversation/messages.yml + +# Contacts +/account/{account_id}/contacts: + $ref: ./contact/list_create.yml +/account/{account_id}/contacts/{id}: + $ref: ./contact/crud.yml +/account/{account_id}/contacts/{id}/conversations: + $ref: ./contact/conversations.yml diff --git a/swagger/paths/widget/inboxes/create.yml b/swagger/paths/widget/inboxes/create.yml new file mode 100644 index 000000000..7a92add34 --- /dev/null +++ b/swagger/paths/widget/inboxes/create.yml @@ -0,0 +1,34 @@ +post: + tags: + - Widget + operationId: widgetInboxCreation + summary: Create a website inbox + description: You can create more than one website inbox in each account + parameters: + - name: data + in: body + required: true + schema: + type: object + properties: + website: + type: object + properties: + website_name: + type: string + description: The name of the inbox + website_url: + type: string + description: URL at which the widget will be loaded + widget_color: + type: string + description: A Hex-color string used to customize the widget + responses: + 200: + description: Success + schema: + $ref: '#/definitions/inbox' + 404: + description: Inbox not found + 403: + description: Access denied diff --git a/swagger/paths/widget/inboxes/update.yml b/swagger/paths/widget/inboxes/update.yml new file mode 100644 index 000000000..30afbc9d3 --- /dev/null +++ b/swagger/paths/widget/inboxes/update.yml @@ -0,0 +1,28 @@ +patch: + tags: + - Widget + operationId: widgetInboxUpdate + summary: Update a website inbox + description: Update widget color of an inbox + parameters: + - name: data + in: body + required: true + schema: + type: object + properties: + website: + type: object + properties: + widget_color: + type: string + description: A Hex-color string used to customize the widget + responses: + 200: + description: Success + schema: + $ref: '#/definitions/inbox' + 404: + description: Inbox not found + 403: + description: Access denied diff --git a/swagger/swagger.json b/swagger/swagger.json index fcfd814bf..ac28523b0 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -1,7 +1,7 @@ { "swagger": 2.0, "info": { - "description": "This is the api documentation for Chatwoot server.", + "description": "This is the API documentation for Chatwoot server.", "version": "1.0.0", "title": "Chatwoot", "termsOfService": "https://www.chatwoot.com/terms-of-service/", @@ -11,12 +11,557 @@ "license": { "name": "MIT License", "url": "https://opensource.org/licenses/MIT" - }, - "host": "app.chatwoot.com", - "basePath": "/api/v1/" + } }, + "host": "app.chatwoot.com", + "basePath": "/api/v1/", + "schemes": [ + "https" + ], + "produces": [ + "application/json; charset=utf-8" + ], + "consumes": [ + "application/json; charset=utf-8" + ], "paths": { - "/contacts": { + "/account/{account_id}/widget/inboxes": { + "post": { + "tags": [ + "Widget" + ], + "operationId": "widgetInboxCreation", + "summary": "Create a website inbox", + "description": "You can create more than one website inbox in each account", + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "website": { + "type": "object", + "properties": { + "website_name": { + "type": "string", + "description": "The name of the inbox" + }, + "website_url": { + "type": "string", + "description": "URL at which the widget will be loaded" + }, + "widget_color": { + "type": "string", + "description": "A Hex-color string used to customize the widget" + } + } + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/inbox" + } + }, + "404": { + "description": "Inbox not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/widget/inboxes/${id}": { + "patch": { + "tags": [ + "Widget" + ], + "operationId": "widgetInboxUpdate", + "summary": "Update a website inbox", + "description": "Update widget color of an inbox", + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "website": { + "type": "object", + "properties": { + "widget_color": { + "type": "string", + "description": "A Hex-color string used to customize the widget" + } + } + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/inbox" + } + }, + "404": { + "description": "Inbox not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/inboxes": { + "get": { + "tags": [ + "Inbox" + ], + "operationId": "listAllInboxes", + "summary": "List all inboxes", + "description": "List all inboxes available in the current account", + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/inbox" + } + }, + "404": { + "description": "Inbox not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/inboxes/{id}": { + "patch": { + "tags": [ + "Inbox" + ], + "operationId": "disableAutoAssignment", + "summary": "Disable auto assignment", + "description": "Disable Auto Assignment for an inbox", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the inbox", + "required": true + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "enable_auto_assignment": { + "type": "boolean", + "required": true, + "description": "Enable Auto Assignment" + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/inbox" + } + }, + "404": { + "description": "Inbox not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/conversations": { + "get": { + "tags": [ + "Conversation" + ], + "operationId": "conversationList", + "description": "List all the conversations with pagination", + "summary": "Conversations List", + "parameters": [ + { + "name": "assignee_type", + "in": "query", + "type": "string", + "enum": [ + "me", + "unassigned", + "all" + ], + "required": true + }, + { + "name": "status", + "in": "query", + "type": "string", + "enum": [ + "open", + "resolved", + "bot" + ], + "required": true + }, + { + "name": "page", + "in": "query", + "type": "integer", + "required": true + }, + { + "name": "inbox_id", + "in": "query", + "type": "integer" + }, + { + "name": "labels", + "in": "query", + "type": "array", + "items": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/conversation_list" + } + }, + "400": { + "description": "Bad Request Error", + "schema": { + "$ref": "#/definitions/bad_request_error" + } + } + } + } + }, + "/account/{account_id}/conversations/{id}": { + "get": { + "tags": [ + "Conversation" + ], + "operationId": "conversationDetails", + "summary": "Conversation Details", + "description": "Get all details regarding a conversation with all messages in the conversation", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of Conversation", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/conversation_show" + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/conversations/{id}/toggle_status": { + "post": { + "tags": [ + "Conversation" + ], + "operationId": "conversationToggleStatus", + "summary": "Toggle Status", + "description": "Toggles the status of the conversation between open and resolved", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the conversation", + "required": true + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "open", + "resolved" + ], + "required": true, + "description": "The status of the conversation" + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/conversation_status_toggle" + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/conversations/{id}/messages": { + "get": { + "tags": [ + "Messages" + ], + "operationId": "listAllMessages", + "summary": "Get messages", + "description": "List all messages of a conversation", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the conversation", + "required": true + } + ], + "responses": { + "200": { + "description": "Array of messages", + "type": "array", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/generic_id" + }, + { + "$ref": "#/definitions/message" + } + ] + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + }, + "post": { + "tags": [ + "Messages" + ], + "operationId": "conversationNewMessage", + "summary": "Create New Message", + "description": "All the agent replies are created as new messages through this endpoint", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the conversation", + "required": true + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/conversation_message_create" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/generic_id" + }, + { + "$ref": "#/definitions/message" + } + ] + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/conversations/{id}/labels": { + "get": { + "tags": [ + "ConversationLabels" + ], + "operationId": "conversationLabelsList", + "summary": "List Labels", + "description": "Lists all the labels of a conversation", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the conversation", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/conversation_labels" + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + }, + "post": { + "tags": [ + "ConversationLabels" + ], + "operationId": "conversationAddLabels", + "summary": "Add Labels", + "description": "Creates new labels and associates it with the conversation", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "ID of the conversation", + "required": true + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "labels": { + "type": "array", + "description": "Array of labels", + "properties": { + "type": "string" + } + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/conversation_labels" + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/conversations/{id}/assignments": { + "post": { + "tags": [ + "ConversationAssignment" + ], + "operationId": "conversationAssignment", + "summary": "Assign Conversation", + "description": "Assign a conversation to an agent", + "parameters": [ + { + "name": "id", + "in": "path", + "type": "number", + "description": "id of the conversation", + "required": true + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "assignee_id": { + "type": "number" + } + } + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/user" + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/account/{account_id}/contacts": { "get": { "tags": [ "Contact" @@ -78,7 +623,7 @@ } } }, - "/contacts/{id}": { + "/account/{account_id}/contacts/{id}": { "get": { "tags": [ "Contact" @@ -148,7 +693,7 @@ } } }, - "/contacts/{id}/conversations": { + "/account/{account_id}/contacts/{id}/conversations": { "get": { "tags": [ "Contact" @@ -179,308 +724,6 @@ } } } - }, - "/conversations": { - "get": { - "tags": [ - "Conversation" - ], - "operationId": "conversationList", - "description": "List all the conversations with pagination", - "summary": "Conversations List", - "parameters": [ - { - "name": "query_hash", - "in": "query", - "type": "string" - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/conversation_list" - } - }, - "400": { - "description": "Bad Request Error", - "schema": { - "$ref": "#/definitions/bad_request_error" - } - } - } - } - }, - "/conversations/{id}": { - "get": { - "tags": [ - "Conversation" - ], - "operationId": "conversationDetails", - "summary": "Conversation Details", - "description": "Get all details regarding a conversation with all messages in the conversation", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "ID of Conversation", - "required": true - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/conversation_show" - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - } - }, - "/conversations/{id}/toggle_status": { - "post": { - "tags": [ - "Conversation" - ], - "operationId": "conversationToggleStatus", - "summary": "Toggle Status", - "description": "Toggles the status of the conversation between open and resolved", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - } - ], - "responses": { - "204": { - "description": "Success", - "schema": { - "$ref": "#/definitions/conversation_status_toggle" - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - } - }, - "/conversations/{id}/update_last_seen": { - "post": { - "tags": [ - "Conversation" - ], - "operationId": "conversationUpdateLastSeen", - "summary": "Update Last Seen", - "description": "Updates the last seen of the conversation so that conversations will have the bubbles in the agents screen", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - } - ], - "responses": { - "200": { - "description": "Success" - }, - "404": { - "description": "Contact not found" - }, - "403": { - "description": "Access denied" - } - } - } - }, - "/conversations/{id}/labels": { - "get": { - "tags": [ - "Conversation" - ], - "operationId": "conversationLabelsList", - "summary": "List Labels", - "description": "Lists all the labels of a conversation", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - } - ], - "responses": { - "200": { - "description": "Success", - "schema": { - "$ref": "#/definitions/conversation_labels" - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - }, - "post": { - "tags": [ - "Conversation" - ], - "operationId": "conversationAddLabels", - "summary": "Add Labels", - "description": "Creates new labels and associates it with the conversation", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - }, - { - "name": "data", - "in": "body", - "required": true, - "schema": { - "type": "object", - "properties": { - "labels": { - "type": "array", - "description": "array of labels", - "properties": { - "type": "string" - } - } - } - } - } - ], - "responses": { - "204": { - "description": "Success", - "schema": { - "$ref": "#/definitions/conversation_labels" - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - } - }, - "/conversations/{id}/assignments": { - "post": { - "tags": [ - "Conversation" - ], - "operationId": "conversationAssignment", - "summary": "Assign Conversation", - "description": "Assign a conversation to an agent", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - }, - { - "name": "data", - "in": "body", - "required": true, - "schema": { - "type": "object", - "properties": { - "assignee_id": { - "type": "number" - } - } - } - } - ], - "responses": { - "204": { - "description": "Success", - "schema": { - "$ref": "#/definitions/user" - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - } - }, - "/conversations/{id}/messages": { - "post": { - "tags": [ - "Conversation" - ], - "operationId": "conversationNewMessage", - "summary": "Create New Message", - "description": "All the agent replies are created as new messages through this endpoint", - "parameters": [ - { - "name": "id", - "in": "path", - "type": "number", - "description": "id of the conversation", - "required": true - }, - { - "name": "data", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/conversation_message_create" - } - } - ], - "responses": { - "204": { - "description": "Success", - "schema": { - "allOf": [ - { - "$ref": "#/definitions/generic_id" - }, - { - "$ref": "#/definitions/message" - } - ] - } - }, - "404": { - "description": "Conversation not found" - }, - "403": { - "description": "Access denied" - } - } - } } }, "definitions": { @@ -525,43 +768,53 @@ "type": "object", "properties": { "email": { - "type": "string" + "type": "string", + "description": "Email address of the contact" }, "name": { - "type": "string" + "type": "string", + "description": "The name of the contact" }, "phone_number": { - "type": "string" + "type": "string", + "description": "Phone number of the contact" }, "thumbnail": { - "type": "string" + "type": "string", + "description": "Avatar URL of the contact" }, "additional_attributes": { - "type": "object" + "type": "object", + "description": "The object containing additional attributes related to the contact" } } }, "conversation": { "type": "object", "properties": { + "id": { + "type": "number", + "description": "ID of the conversation" + }, "messages": { - "type": "array", - "items": { - "type": "object" - } + "type": "array" }, "inbox_id": { - "type": "number" + "type": "number", + "description": "ID of the inbox" }, "status": { "type": "string", "enum": [ "open", - "resolved" - ] + "resolved", + "bot" + ], + "description": "The status of the conversation" }, "timestamp": { - "type": "string" + "type": "string", + "description": "The time at which conversation was created" }, "user_last_seen_at": { "type": "string" @@ -570,7 +823,12 @@ "type": "agent_last_seen_at" }, "unread_count": { - "type": "number" + "type": "number", + "description": "The number of unread messages" + }, + "additional_attributes": { + "type": "object", + "description": "The object containing additional attributes related to the conversation" } } }, @@ -578,25 +836,38 @@ "type": "object", "properties": { "content": { - "type": "string" - }, - "inbox_id": { - "type": "number" - }, - "conversation_id": { - "type": "number" + "type": "string", + "description": "The text content of the message" }, "message_type": { - "type": "string" + "type": "string", + "enum": [ + "incoming", + "outgoing", + "activity", + "template" + ], + "description": "The type of the message" }, "created_at": { - "type": "integer" + "type": "integer", + "description": "The time at which message was created" }, "private": { - "type": "boolean" + "type": "boolean", + "description": "The flags which shows whether the message is private or not" }, "attachment": { - "type": "object" + "type": "object", + "description": "The file object attached to the image" + }, + "sender": { + "type": "object", + "description": "User/Agent/AgentBot object" + }, + "conversation_id": { + "type": "number", + "description": "ID of the conversation" } } }, @@ -633,6 +904,35 @@ } } }, + "inbox": { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "ID of the inbox" + }, + "channel_type": { + "type": "string", + "description": "The type of the inbox" + }, + "avatar_url": { + "type": "string", + "description": "The avatar image of the inbox" + }, + "widget_color": { + "type": "string", + "description": "Widget Color used for customization of the widget" + }, + "website_token": { + "type": "string", + "description": "Website Token" + }, + "enable_auto_assignment": { + "type": "boolean", + "description": "The flag which shows whether Auto Assignment is enabled or not" + } + } + }, "extended_contact": { "allOf": [ { @@ -642,14 +942,16 @@ "type": "object", "properties": { "id": { - "type": "number" + "type": "number", + "description": "Id of the user" }, "availability_status": { "type": "string", "enum": [ "online", "offline" - ] + ], + "description": "Availability status of the user" } } } @@ -697,16 +999,20 @@ "type": "object", "properties": { "id": { - "type": "number" + "type": "number", + "description": "ID fo the sender" }, "name": { - "type": "string" + "type": "string", + "description": "The name of the sender" }, "thumbnail": { - "type": "string" + "type": "string", + "description": "Avatar URL of the contact" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel Type" } } }, @@ -769,16 +1075,20 @@ "type": "object", "properties": { "id": { - "type": "number" + "type": "number", + "description": "ID fo the sender" }, "name": { - "type": "string" + "type": "string", + "description": "The name of the sender" }, "thumbnail": { - "type": "string" + "type": "string", + "description": "Avatar URL of the contact" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel Type" } } }, @@ -798,36 +1108,48 @@ }, "conversation_show": { "type": "object", - "properties": { - "meta": { + "allOf": [ + { + "$ref": "#/definitions/generic_id" + }, + { + "$ref": "#/definitions/conversation" + }, + { "type": "object", "properties": { - "labels": { - "type": "array", - "items": { - "type": "string" + "meta": { + "type": "object", + "properties": { + "sender": { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "ID fo the sender" + }, + "name": { + "type": "string", + "description": "The name of the sender" + }, + "thumbnail": { + "type": "string", + "description": "Avatar URL of the contact" + }, + "channel": { + "type": "string", + "description": "Channel Type" + } + } + }, + "assignee": { + "$ref": "#/definitions/user" + } } - }, - "additional_attributes": { - "type": "object" - }, - "contact_id": { - "type": "number" } } - }, - "payload": { - "type": "array", - "description": "array of messages", - "items": { - "allOf": [ - { - "$ref": "#/definitions/extended_message" - } - ] - } } - } + ] }, "conversation_status_toggle": { "type": "object", @@ -860,7 +1182,7 @@ "properties": { "payload": { "type": "array", - "description": "array of labels", + "description": "Array of labels", "items": { "type": "string" } @@ -917,16 +1239,18 @@ "type": "object", "properties": { "conversation_id": { - "type": "number" + "type": "number", + "description": "ID of the conversation", + "required": true }, "message": { - "type": "string" + "type": "string", + "description": "The content of the message", + "required": true }, "private": { - "type": "boolean" - }, - "fb_id": { - "type": "number" + "type": "boolean", + "description": "Flag to identify if it is a private note" } } }