From 3639fb1d7112ff1cb537d24422a660190e593403 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Tue, 11 May 2021 22:38:46 +0530 Subject: [PATCH] chore: Add documentation for APIs (#2248) --- swagger/definitions/index.yml | 2 + .../resource/contactable_inboxes.yml | 8 + swagger/parameters/index.yml | 5 + swagger/parameters/source_id.yml | 2 + swagger/paths/contact_inboxes/create.yml | 2 + swagger/paths/contactable_inboxes/get.yml | 17 ++ .../paths/conversation/index_or_create.yml | 11 +- .../messages/create_attachment.yml | 47 +++++ swagger/paths/index.yml | 6 +- swagger/swagger.json | 166 +++++++++++++++++- 10 files changed, 260 insertions(+), 6 deletions(-) create mode 100644 swagger/definitions/resource/contactable_inboxes.yml create mode 100644 swagger/parameters/source_id.yml create mode 100644 swagger/paths/contactable_inboxes/get.yml create mode 100644 swagger/paths/conversation/messages/create_attachment.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index 7f6546a89..e72c1743d 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -21,6 +21,8 @@ agent_bot: $ref: ./resource/agent_bot.yml contact_inboxes: $ref: ./resource/contact_inboxes.yml +contactable_inboxes: + $ref: ./resource/contactable_inboxes.yml account: $ref: ./resource/account.yml team: diff --git a/swagger/definitions/resource/contactable_inboxes.yml b/swagger/definitions/resource/contactable_inboxes.yml new file mode 100644 index 000000000..a223490ff --- /dev/null +++ b/swagger/definitions/resource/contactable_inboxes.yml @@ -0,0 +1,8 @@ +type: object +properties: + source_id: + type: string + description: Contact Inbox Source Id + inbox: + type: object + $ref: '#/definitions/inbox' diff --git a/swagger/parameters/index.yml b/swagger/parameters/index.yml index 46dc0914f..587e95893 100644 --- a/swagger/parameters/index.yml +++ b/swagger/parameters/index.yml @@ -4,8 +4,13 @@ account_id: team_id: $ref: ./team_id.yml + +source_id: + $ref: ./source_id.yml + conversation_id: $ref: ./conversation_id.yml message_id: $ref: ./message_id.yml + diff --git a/swagger/parameters/source_id.yml b/swagger/parameters/source_id.yml new file mode 100644 index 000000000..47536332f --- /dev/null +++ b/swagger/parameters/source_id.yml @@ -0,0 +1,2 @@ +type: string +description: "Id of the session for which the conversation is created.\n\n\n\n Source Ids can be obtained through contactable inboxes API or via generated.

Website: Chatwoot generated string which can be obtained from webhook events.
Phone Channels(Twilio): Phone number in e164 format
Email Channels: Contact Email address
API Channel: Any Random String" \ No newline at end of file diff --git a/swagger/paths/contact_inboxes/create.yml b/swagger/paths/contact_inboxes/create.yml index c6943d162..a0f641867 100644 --- a/swagger/paths/contact_inboxes/create.yml +++ b/swagger/paths/contact_inboxes/create.yml @@ -15,6 +15,8 @@ post: type: number description: The id of the inbox required: true + source_id: + $ref: '#/parameters/source_id' responses: 200: description: Success diff --git a/swagger/paths/contactable_inboxes/get.yml b/swagger/paths/contactable_inboxes/get.yml new file mode 100644 index 000000000..5e6b651cb --- /dev/null +++ b/swagger/paths/contactable_inboxes/get.yml @@ -0,0 +1,17 @@ +get: + tags: + - Contact + operationId: contactableInboxesGet + description: Get List of contactable Inboxes + summary: Get Contactable Inboxes + responses: + 200: + description: Success + schema: + $ref: '#/definitions/contactable_inboxes' + 401: + description: Authentication error + schema: + $ref: '#/definitions/bad_request_error' + 422: + description: Incorrect payload diff --git a/swagger/paths/conversation/index_or_create.yml b/swagger/paths/conversation/index_or_create.yml index 1c6784bec..0fc253fff 100644 --- a/swagger/paths/conversation/index_or_create.yml +++ b/swagger/paths/conversation/index_or_create.yml @@ -88,7 +88,7 @@ post: - Conversation operationId: newConversation summary: Create New Conversation - description: Create conversation + description: "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://github.com/chatwoot/chatwoot/wiki/Building-on-Top-of-Chatwoot:-Importing-Existing-Contacts-and-Creating-Conversations" security: - userApiKey: [] - agentBotApiKey: [] @@ -100,9 +100,14 @@ post: schema: type: object properties: - source_id: + source_id: + $ref: '#/parameters/source_id' + inbox_id: type: string - description: Contact Source Id + description: "Id of inbox in which the conversation is created
Allowed Inbox Types: Website, Phone, Api, Email " + contact_id: + type: string + description: Contact Id for which conversation is created additional_attributes: type: object description: Lets you specify attributes like browser information diff --git a/swagger/paths/conversation/messages/create_attachment.yml b/swagger/paths/conversation/messages/create_attachment.yml new file mode 100644 index 000000000..e6bbd6854 --- /dev/null +++ b/swagger/paths/conversation/messages/create_attachment.yml @@ -0,0 +1,47 @@ +post: + tags: + - Messages + operationId: conversationNewMessageAttachment + summary: Create New Message Attachment + description: Create an attachment Message + consumes: + - multipart/form-data + security: + - userApiKey: [] + - agentBotApiKey: [] + parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/conversation_id' + required: true + - in: formData + name: content + type: string + description: The content of the message + required: true + - in: formData + name: message_type + type: string + enum: ['outgoing', 'incoming'] + - in: formData + name: private + type: boolean + description: Flag to identify if it is a private note + - in: formData + name: attachments + type: array + description: The files to be uploaded. + items: + type: file + + + 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/index.yml b/swagger/paths/index.yml index 53946c457..b47d6cb9c 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -4,7 +4,7 @@ # Inboxes /accounts/{account_id}/inboxes: $ref: ./inboxes/index.yml -/accounts/{account_id}/inboxes: +/accounts/{account_id}/inboxes/: $ref: ./inboxes/create.yml /accounts/{account_id}/inboxes/{id}: $ref: ./inboxes/update.yml @@ -35,6 +35,8 @@ $ref: ./conversation/toggle_status.yml # Messages +/accounts/{account_id}/conversations/{id}/messages: + $ref: ./conversation/messages/create_attachment.yml /accounts/{account_id}/conversations/{converstion_id}/messages: parameters: - $ref: '#/parameters/account_id' @@ -84,6 +86,8 @@ /accounts/{account_id}/contacts/{id}/contact_inboxes: $ref: ./contact_inboxes/create.yml +/accounts/{account_id}/contacts/{id}/contactable_inboxes: + $ref: ./contactable_inboxes/get.yml # Profile diff --git a/swagger/swagger.json b/swagger/swagger.json index b48486319..40dba44cf 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -53,6 +53,30 @@ ], "paths": { "/accounts/{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" + } + } + } + }, + "/accounts/{account_id}/inboxes/": { "post": { "tags": [ "Inbox" @@ -356,7 +380,7 @@ ], "operationId": "newConversation", "summary": "Create New Conversation", - "description": "Create conversation", + "description": "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://github.com/chatwoot/chatwoot/wiki/Building-on-Top-of-Chatwoot:-Importing-Existing-Contacts-and-Creating-Conversations", "security": [ { "userApiKey": [ @@ -381,8 +405,15 @@ "type": "object", "properties": { "source_id": { + "$ref": "#/parameters/source_id" + }, + "inbox_id": { "type": "string", - "description": "Contact Source Id" + "description": "Id of inbox in which the conversation is created
Allowed Inbox Types: Website, Phone, Api, Email " + }, + "contact_id": { + "type": "string", + "description": "Contact Id for which conversation is created" }, "additional_attributes": { "type": "object", @@ -517,6 +548,91 @@ } } }, + "/accounts/{account_id}/conversations/{id}/messages": { + "post": { + "tags": [ + "Messages" + ], + "operationId": "conversationNewMessageAttachment", + "summary": "Create New Message Attachment", + "description": "Create an attachment Message", + "consumes": [ + "multipart/form-data" + ], + "security": [ + { + "userApiKey": [ + + ] + }, + { + "agentBotApiKey": [ + + ] + } + ], + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/conversation_id" + }, + { + "in": "formData", + "name": "content", + "type": "string", + "description": "The content of the message", + "required": true + }, + { + "in": "formData", + "name": "message_type", + "type": "string", + "enum": [ + "outgoing", + "incoming" + ] + }, + { + "in": "formData", + "name": "private", + "type": "boolean", + "description": "Flag to identify if it is a private note" + }, + { + "in": "formData", + "name": "attachments", + "type": "array", + "description": "The files to be uploaded.", + "items": { + "type": "file" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/generic_id" + }, + { + "$ref": "#/definitions/message" + } + ] + } + }, + "404": { + "description": "Conversation not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, "/accounts/{account_id}/conversations/{converstion_id}/messages": { "parameters": [ { @@ -986,6 +1102,9 @@ "type": "number", "description": "The id of the inbox", "required": true + }, + "source_id": { + "$ref": "#/parameters/source_id" } } } @@ -1010,6 +1129,33 @@ } } }, + "/accounts/{account_id}/contacts/{id}/contactable_inboxes": { + "get": { + "tags": [ + "Contact" + ], + "operationId": "contactableInboxesGet", + "description": "Get List of contactable Inboxes", + "summary": "Get Contactable Inboxes", + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/contactable_inboxes" + } + }, + "401": { + "description": "Authentication error", + "schema": { + "$ref": "#/definitions/bad_request_error" + } + }, + "422": { + "description": "Incorrect payload" + } + } + } + }, "/profile": { "get": { "tags": [ @@ -1471,6 +1617,18 @@ } } }, + "contactable_inboxes": { + "type": "object", + "properties": { + "source_id": { + "type": "string", + "description": "Contact Inbox Source Id" + }, + "inbox": { + "$ref": "#/definitions/inbox" + } + } + }, "account": { "type": "object", "properties": { @@ -1904,6 +2062,10 @@ "required": true, "description": "The id of the team to be updated" }, + "source_id": { + "type": "string", + "description": "Id of the session for which the conversation is created.\n\n\n\n Source Ids can be obtained through contactable inboxes API or via generated.

Website: Chatwoot generated string which can be obtained from webhook events.
Phone Channels(Twilio): Phone number in e164 format
Email Channels: Contact Email address
API Channel: Any Random String" + }, "conversation_id": { "in": "path", "name": "conversation_id",