{ "swagger": 2.0, "info": { "description": "This is the API documentation for Chatwoot server.", "version": "1.0.0", "title": "Chatwoot", "termsOfService": "https://www.chatwoot.com/terms-of-service/", "contact": { "email": "support@chatwoot.com" }, "license": { "name": "MIT License", "url": "https://opensource.org/licenses/MIT" } }, "host": "app.chatwoot.com", "basePath": "/api/v1/", "schemes": [ "https" ], "produces": [ "application/json; charset=utf-8" ], "consumes": [ "application/json; charset=utf-8" ], "paths": { "/accounts/{account_id}/inboxes": { "post": { "tags": [ "Inbox" ], "operationId": "inboxCreation", "summary": "Create an inbox", "description": "You can create more than one website inbox in each account", "parameters": [ { "name": "data", "in": "body", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the inbox" }, "avatar": { "type": "file", "description": "File for avatar image" }, "channel": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_widget" ] }, "website_url": { "type": "string", "description": "URL at which the widget will be loaded" }, "welcome_title": { "type": "string", "description": "Welcome title to be displayed on the widget" }, "welcome_tagline": { "type": "string", "description": "Welcome tagline to be displayed on the widget" }, "agent_away_message": { "type": "string", "description": "A message which will be sent if there is not agent available. This is not available if agentbot is connected" }, "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" } } } }, "/accounts/{account_id}/inboxes/{id}": { "patch": { "tags": [ "Inbox" ], "operationId": "updateInbox", "summary": "Update Inbox", "description": "Add avatar and 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": { "name": { "type": "string", "description": "The name of the inbox" }, "enable_auto_assignment": { "type": "boolean", "required": true, "description": "Enable Auto Assignment" }, "avatar": { "type": "file", "required": false, "description": "Image file for avatar" }, "channel": { "type": "object", "properties": { "website_url": { "type": "string", "description": "URL at which the widget will be loaded" }, "welcome_title": { "type": "string", "description": "Welcome title to be displayed on the widget" }, "welcome_tagline": { "type": "string", "description": "Welcome tagline to be displayed on the widget" }, "agent_away_message": { "type": "string", "description": "A message which will be sent if there is not agent available. This is not available if agentbot is connected" }, "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" } } } }, "/accounts/{account_id}/inboxes/{id}/set_agent_bot": { "post": { "tags": [ "Inbox" ], "operationId": "updateAgentBot", "summary": "Add or remove agent bot", "description": "To add an agent bot pass agent_bot id, to remove agent bot from an inbox pass null", "parameters": [ { "name": "id", "in": "path", "type": "number", "description": "ID of the inbox", "required": true }, { "name": "data", "in": "body", "required": true, "schema": { "type": "object", "properties": { "agent_bot": { "type": "number", "required": true, "description": "Agent bot ID" } } } } ], "responses": { "204": { "description": "Success" }, "404": { "description": "Inbox not found, Agent bot not found" }, "403": { "description": "Access denied" } } } }, "/agent_bots": { "get": { "tags": [ "AgentBot" ], "operationId": "listAgentBots", "summary": "List all agentbots", "description": "List all available agentbots for the current installation", "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/agent_bot" } }, "404": { "description": "Inbox not found, Agent bot not found" }, "403": { "description": "Access denied" } } } }, "/accounts/{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" } }, "description": "Access denied" } }, "post": { "tags": [ "Conversation" ], "operationId": "newConversation", "summary": "Create New Conversation", "description": "Create conversation", "parameters": [ { "name": "data", "in": "body", "required": true, "schema": { "type": "object", "properties": { "source_id": { "type": "string", "description": "Contact Source Id" } } } } ], "responses": { "200": { "description": "Success", "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the conversation" }, "account_id": { "type": "number", "description": "Account Id" }, "inbox_id": { "type": "number", "description": "ID of the inbox" } } } }, "403": { "description": "Access denied" } } } }, "/accounts/{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" } } } }, "/accounts/{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" } } } }, "/accounts/{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" } } } }, "/accounts/{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" } } } }, "/accounts/{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" } } } }, "/accounts/{account_id}/contacts": { "get": { "tags": [ "Contact" ], "operationId": "contactList", "description": "Listing all the contacts with pagination", "summary": "List Contacts", "parameters": [ { "name": "query_hash", "in": "query", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/contact_list" } }, "400": { "description": "Bad Request Error", "schema": { "$ref": "#/definitions/bad_request_error" } } } }, "post": { "tags": [ "Contact" ], "operationId": "contactCreate", "description": "Create New Contact", "parameters": [ { "name": "data", "in": "body", "required": true, "schema": { "$ref": "#/definitions/contact_create" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/extended_contact" } }, "400": { "description": "Bad Request Error", "schema": { "$ref": "#/definitions/bad_request_error" } } } } }, "/accounts/{account_id}/contacts/{id}": { "get": { "tags": [ "Contact" ], "operationId": "contactDetails", "summary": "Show Contact", "parameters": [ { "name": "id", "in": "path", "type": "number", "description": "id of the contact", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/extended_contact" } }, "404": { "description": "Contact not found" }, "403": { "description": "Access denied" } } }, "put": { "tags": [ "Contact" ], "operationId": "contactUpdate", "summary": "Update Contact", "parameters": [ { "name": "id", "in": "path", "type": "number", "description": "id of the contact", "required": true }, { "name": "data", "in": "body", "required": true, "schema": { "$ref": "#/definitions/contact_update" } } ], "responses": { "204": { "description": "Success", "schema": { "$ref": "#/definitions/contact_base" } }, "404": { "description": "Contact not found" }, "403": { "description": "Access denied" } } } }, "/accounts/{account_id}/contacts/{id}/conversations": { "get": { "tags": [ "Contact" ], "operationId": "contactConversations", "summary": "Conversations", "parameters": [ { "name": "id", "in": "path", "type": "number", "description": "id of the contact", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/contact_conversations" } }, "404": { "description": "Contact not found" }, "403": { "description": "Access denied" } } } } }, "definitions": { "bad_request_error": { "title": "data", "type": "object", "properties": { "description": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/definitions/request_error" } } } }, "request_error": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } }, "generic_id": { "type": "object", "properties": { "id": { "type": "number" } } }, "contact": { "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" } } }, "conversation": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the conversation" }, "messages": { "type": "array" }, "account_id": { "type": "number", "description": "Account Id" }, "inbox_id": { "type": "number", "description": "ID of the inbox" }, "status": { "type": "string", "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" } } }, "message": { "type": "object", "properties": { "content": { "type": "string", "description": "The text content of the message" }, "content_type": { "type": "string", "enum": [ "text", "input_select", "cards", "form" ], "description": "The type of the template message" }, "content_attributes": { "type": "object", "description": "The content attributes for each content_type" }, "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" } } }, "user": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "account_id": { "type": "number" }, "role": { "type": "string", "enum": [ "agent", "administrator" ] }, "confirmed": { "type": "boolean" }, "nickname": { "type": "string" } } }, "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" }, "web_widget_script": { "type": "string", "description": "Script used to load the website widget" }, "welcome_title": { "type": "string", "description": "Welcome title to be displayed on the widget" }, "welcome_tagline": { "type": "string", "description": "Welcome tagline to be displayed on the widget" }, "agent_away_message": { "type": "string", "description": "A message which will be sent if there is not agent available. This is not available if agentbot is connected" } } }, "agent_bot": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the agent bot" }, "description": { "type": "string", "description": "The description about the agent bot" }, "name": { "type": "string", "description": "The name of the agent bot" }, "outgoing_url": { "type": "string", "description": "The webhook URL for the bot" } } }, "extended_contact": { "allOf": [ { "$ref": "#/definitions/contact" }, { "type": "object", "properties": { "id": { "type": "number", "description": "Id of the user" }, "availability_status": { "type": "string", "enum": [ "online", "offline" ], "description": "Availability status of the user" } } } ] }, "contact_base": { "allOf": [ { "$ref": "#/definitions/generic_id" }, { "$ref": "#/definitions/contact" } ] }, "contact_list": { "type": "array", "description": "array of contacts", "items": { "allOf": [ { "$ref": "#/definitions/generic_id" }, { "$ref": "#/definitions/contact" } ] } }, "contact_conversations": { "type": "array", "description": "array of conversations", "items": { "allOf": [ { "$ref": "#/definitions/conversation" }, { "type": "object", "properties": { "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" } } } } }, { "type": "object", "properties": { "display_id": { "type": "number" } } } ] } }, "conversation_list": { "type": "object", "properties": { "data": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "mine_count": { "type": "number" }, "unassigned_count": { "type": "number" }, "all_count": { "type": "number" } } }, "payload": { "type": "array", "description": "array of conversations", "items": { "allOf": [ { "$ref": "#/definitions/generic_id" }, { "$ref": "#/definitions/conversation" }, { "type": "object", "properties": { "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" } } } } } ] } } } } } }, "conversation_show": { "type": "object", "allOf": [ { "$ref": "#/definitions/generic_id" }, { "$ref": "#/definitions/conversation" }, { "type": "object", "properties": { "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" } } } } } ] }, "conversation_status_toggle": { "type": "object", "properties": { "meta": { "type": "object" }, "payload": { "type": "object", "properties": { "success": { "type": "boolean" }, "current_status": { "type": "string", "enum": [ "open", "resolved" ] }, "conversation_id": { "type": "number" } } } } }, "conversation_labels": { "type": "object", "properties": { "payload": { "type": "array", "description": "Array of labels", "items": { "type": "string" } } } }, "extended_message": { "allOf": [ { "$ref": "#/definitions/generic_id" }, { "$ref": "#/definitions/message" }, { "type": "object", "properties": { "source_id": { "type": "number" }, "sender": { "type": "object" } } } ] }, "contact_create": { "type": "object", "properties": { "account_id": { "type": "number" }, "inbox_id": { "type": "number" } } }, "contact_update": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone_number": { "type": "string" } } }, "conversation_message_create": { "type": "object", "properties": { "conversation_id": { "type": "number", "description": "ID of the conversation", "required": true }, "content": { "type": "string", "description": "The content of the message", "required": true }, "private": { "type": "boolean", "description": "Flag to identify if it is a private note" }, "content_type": { "type": "string", "enum": [ "input_select", "form", "cards" ] }, "content_attributes": { "type": "object", "description": "options/form object" } } } } }