---
agentTools:
  projectIndex: https://waapi.readme.io/llms.txt
---

# get all chats

Retrieves a list of all chats with their latest messages and metadata. Supports pagination.

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "WaAPI API",
    "description": "WaAPI is a simple API gateway for sending messages.\n\n## Response envelopes\n\nEvery `/instances/{id}/client/action/*` call answers with two status fields:\n\n| Field | Answers |\n|---|---|\n| `status` | Did the request reach the instance? |\n| `data.status` | Did the instance carry the action out? **This is the authoritative one.** |\n\n```json\n{\n  \"status\": \"success\",\n  \"links\": { \"self\": \"https://waapi.app/api/v1/instances/123/client/action/send-message\" },\n  \"data\": {\n    \"status\": \"success\",\n    \"instanceId\": \"123\",\n    \"data\": { }\n  }\n}\n```\n\nA malformed input is **not** an HTTP error. It comes back as HTTP 200 with\n`status: success` and `data.status: error`, and nothing was sent:\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": { \"status\": \"error\", \"message\": \"incorrect chatId format.\", \"explanation\": \"…\" }\n}\n```\n\nCheck `data.status` before treating any action as done.\n\n## Chat and contact IDs\n\n| Form | Addresses |\n|---|---|\n| `<number>@c.us` | a contact by phone number — country code and number, digits only (`491729682587@c.us`) |\n| `<lid>@lid` | the same contact by its Linked ID (LID), an identifier that does not reveal the phone number |\n| `<id>@g.us` | a group |\n| `<id>@newsletter` | a channel |\n\nIncoming messages and events can carry a contact's `@lid` form in `from`, `author` and participant lists —\nalso for contacts you know by phone number. Both forms address the same one-to-one chat: replying to the\n`from` you received reaches that person, whether it ends in `@c.us` or `@lid`. To map one form to the\nother, call `get-lid`; it resolves in both directions. Every `chatId`, `contactId` and `participant`\nparameter accepts the `@lid` form.",
    "version": "v1.7.0"
  },
  "servers": [
    {
      "url": "https://waapi.app/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "chat",
      "description": "Operations related to managing chats."
    }
  ],
  "paths": {
    "/instances/{id}/client/action/get-chats": {
      "post": {
        "tags": [
          "chat"
        ],
        "summary": "get all chats",
        "description": "Retrieves a list of all chats with their latest messages and metadata. Supports pagination.",
        "operationId": "get-chats",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Instance ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "offset": {
                    "type": "integer",
                    "description": "The number of items to skip before starting to collect the result set",
                    "example": 0
                  },
                  "limit": {
                    "type": "integer",
                    "description": "The number of items to return",
                    "example": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request reached the instance. `data.status` reports whether the action was carried out; on error `data` carries `message` and `explanation`. Payload: Returns a list of chats with their metadata and latest messages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The action's outcome. `status: success` carries the payload; `status: error` is an `actionError`.",
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "status": {
                              "$ref": "#/components/schemas/actionStatus"
                            },
                            "instanceId": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "example": "123"
                            },
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "object",
                                    "properties": {
                                      "server": {
                                        "type": "string",
                                        "example": "c.us"
                                      },
                                      "user": {
                                        "type": "string",
                                        "example": "xxxxxxxxxxxx"
                                      },
                                      "_serialized": {
                                        "type": "string",
                                        "example": "xxxxxxxxxxxx@c.us"
                                      }
                                    }
                                  },
                                  "name": {
                                    "type": "string",
                                    "example": "Contact Name"
                                  },
                                  "isGroup": {
                                    "type": "boolean",
                                    "example": false
                                  },
                                  "isReadOnly": {
                                    "type": "boolean",
                                    "example": false
                                  },
                                  "unreadCount": {
                                    "type": "integer",
                                    "example": 0
                                  },
                                  "timestamp": {
                                    "type": "integer",
                                    "example": 1738947027
                                  },
                                  "archived": {
                                    "type": "boolean",
                                    "example": false
                                  },
                                  "pinned": {
                                    "type": "boolean",
                                    "example": false
                                  },
                                  "isMuted": {
                                    "type": "boolean",
                                    "example": false
                                  },
                                  "muteExpiration": {
                                    "type": "integer",
                                    "example": 0
                                  },
                                  "lastMessage": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "object",
                                        "properties": {
                                          "fromMe": {
                                            "type": "boolean",
                                            "example": true
                                          },
                                          "remote": {
                                            "type": "string",
                                            "example": "xxxxxxxxxxxx@c.us"
                                          },
                                          "id": {
                                            "type": "string",
                                            "example": "XXXXXXXXXXXXXXXXXXXX"
                                          },
                                          "_serialized": {
                                            "type": "string",
                                            "example": "true_xxxxxxxxxxxx@c.us_XXXXXXXXXXXXXXXXXXXX"
                                          }
                                        }
                                      },
                                      "body": {
                                        "type": "string",
                                        "example": "Message content"
                                      },
                                      "type": {
                                        "type": "string",
                                        "example": "chat"
                                      },
                                      "timestamp": {
                                        "type": "integer",
                                        "example": 1738947027
                                      },
                                      "from": {
                                        "type": "string",
                                        "example": "xxxxxxxxxxxx@c.us"
                                      },
                                      "to": {
                                        "type": "string",
                                        "example": "xxxxxxxxxxxx@c.us"
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "required": [
                            "status"
                          ]
                        },
                        {
                          "$ref": "#/components/schemas/actionError"
                        }
                      ]
                    },
                    "status": {
                      "$ref": "#/components/schemas/requestStatus"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing bearer token"
          },
          "403": {
            "description": "Forbidden — insufficient permissions or account blocked"
          },
          "404": {
            "description": "Not found — instance does not exist or does not belong to you"
          },
          "409": {
            "description": "Conflict — instance is not ready"
          },
          "422": {
            "description": "Validation error — invalid or missing request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — rate limit exceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "errorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "The given data was invalid."
          },
          "errors": {
            "type": "object",
            "example": {}
          },
          "status": {
            "type": "string",
            "example": "error"
          }
        }
      },
      "requestStatus": {
        "type": "string",
        "enum": [
          "success",
          "error"
        ],
        "example": "success",
        "description": "Whether the request reached the instance. `success` here does **not** mean the action was carried out — that is reported by `data.status`, which is the authoritative one. A malformed input arrives as `status: success` with `data.status: error`."
      },
      "actionStatus": {
        "type": "string",
        "enum": [
          "success"
        ],
        "example": "success",
        "description": "Whether the instance carried the action out — the authoritative field. In this branch it is always `success`; when the instance refused the action the whole `data` object is an `actionError` with `status: error`, `message` and `explanation`."
      },
      "actionError": {
        "type": "object",
        "description": "Shape of `data` when the instance refused the action. HTTP status is still 200 and the outer `status` is still `success`.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "example": "error"
          },
          "message": {
            "type": "string",
            "example": "incorrect chatId format."
          },
          "explanation": {
            "type": "string",
            "example": "\"bogus\" is missing a domain, expected <id>@c.us."
          },
          "instanceId": {
            "type": [
              "integer",
              "string",
              "null"
            ],
            "example": null
          }
        },
        "additionalProperties": true,
        "required": [
          "status"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 105,
      "1": 230,
      "2": 58,
      "3": 131,
      "4": 222,
      "5": 157,
      "6": 92,
      "7": 217,
      "8": 143,
      "9": 179,
      "10": 112,
      "11": 32
    }
  }
}
````