Chatwoot/swagger/swagger.json

{
  "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": {
    "/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"
        ],
        "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"
            }
          }
        }
      }
    },
    "/account/{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"
          }
        }
      }
    },
    "/account/{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"
        },
        "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"
        },
        "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"
        }
      }
    },
    "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
        },
        "message": {
          "type": "string",
          "description": "The content of the message",
          "required": true
        },
        "private": {
          "type": "boolean",
          "description": "Flag to identify if it is a private note"
        }
      }
    }
  }
}