> ## Documentation Index > Fetch the complete documentation index at: https://devs.izap.ai/llms.txt > Use this file to discover all available pages before exploring further. # List a business's chats > Returns the business's conversations with paging, and optional filters for kind and assistant. The business is taken from the `business-id` header rather than the URL; the path-scoped form of this operation is deprecated. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/chats openapi: 3.1.0 info: contact: email: suporte@izap.ai name: iZap API Support description: Public REST API for the iZap WhatsApp business messaging platform. license: name: MIT url: https://opensource.org/licenses/MIT title: iZap API version: v1 servers: - description: Production url: https://api.izap.ai - description: Staging url: https://api-staging.izap.ai security: [] tags: - description: >- Personal access tokens for calling this API, plus introspection of the token presented on a request. name: api-tokens - description: >- Create a business, read and update its profile, and manage its opening hours. name: businesses - description: >- Reusable images belonging to the caller's business, referenced when composing messages. name: business-library - description: Product catalog menus a business publishes to its customers. name: menus - description: >- Provision and inspect the WhatsApp Cloud API numbers attached to a business: registration, WABA details, per-number assistant binding and catalog sends. name: whatsapp-cloud - description: >- Conversation lifecycle — list, create and delete chats, and control read, snooze, status and AI pause state. name: chats - description: >- Read a conversation's messages, send free-form or template replies, and upload attachments. name: messages - description: >- Manage WhatsApp message templates: draft them locally, submit them to Meta for review and sync approval status back. name: whatsapp-templates - description: >- Bulk template sends. A transmission is previewed into a draft, then confirmed or cancelled — confirming dispatches to real recipients. name: transmissions - description: >- Register URLs that receive signed event deliveries when something happens in a business, rotate their signing secrets, and replay an individual delivery. name: webhooks - description: >- Server-rendered order visualisation page for a business slug, behind HTTP Basic auth. name: orders paths: /api/v1/chats: get: tags: - chats summary: List a business's chats description: >- Returns the business's conversations with paging, and optional filters for kind and assistant. The business is taken from the `business-id` header rather than the URL; the path-scoped form of this operation is deprecated. operationId: listCurrentBusinessChats parameters: - description: >- Filter by Chat.kind. 'trainer' (default) returns sandbox conversations from the AI Trainer UI; 'real' returns customer conversations created from WhatsApp webhooks; 'all' returns both. The default is 'trainer' to preserve the historical behavior of this endpoint, which was trainer-only via a consumer-nickname heuristic. in: query name: kind required: false schema: default: trainer description: >- Filter by Chat.kind. 'trainer' (default) returns sandbox conversations from the AI Trainer UI; 'real' returns customer conversations created from WhatsApp webhooks; 'all' returns both. The default is 'trainer' to preserve the historical behavior of this endpoint, which was trainer-only via a consumer-nickname heuristic. title: Kind type: string - description: >- 1-based page number for chat pagination (used by the trainer's infinite scroll). in: query name: page required: false schema: default: 1 description: >- 1-based page number for chat pagination (used by the trainer's infinite scroll). minimum: 1 title: Page type: integer - description: Number of chats to return per page (default 30, max 100). in: query name: page_size required: false schema: default: 30 description: Number of chats to return per page (default 30, max 100). maximum: 100 minimum: 1 title: Page Size type: integer - description: >- How many of the most-recent messages to embed per chat. Defaults to 1, which is enough for the list's last-message preview and ordering. Full conversation threads should be fetched on demand from GET /chats/{chat_id}/messages (paginated) rather than over-fetched here — embedding the whole thread for every chat on the page made this endpoint load thousands of messages per request. in: query name: messages_per_chat required: false schema: default: 1 description: >- How many of the most-recent messages to embed per chat. Defaults to 1, which is enough for the list's last-message preview and ordering. Full conversation threads should be fetched on demand from GET /chats/{chat_id}/messages (paginated) rather than over-fetched here — embedding the whole thread for every chat on the page made this endpoint load thousands of messages per request. maximum: 200 minimum: 1 title: Messages Per Chat type: integer - description: >- Refine trainer queue filter for kind=real. 'pending' = no OK review and no issues; 'reviewed' = has OK review or any issue. in: query name: refine_queue required: false schema: anyOf: - type: string - type: 'null' description: >- Refine trainer queue filter for kind=real. 'pending' = no OK review and no issues; 'reviewed' = has OK review or any issue. title: Refine Queue - description: >- Optional assistant ID to filter chats by (per-assistant trainer from dash). in: query name: chatbot_id required: false schema: anyOf: - format: uuid type: string - type: 'null' description: >- Optional assistant ID to filter chats by (per-assistant trainer from dash). title: Chatbot Id - description: >- ISO-8601 timestamp. When set, only chats whose last activity (the same timestamp this list orders by) is strictly *newer than* `since` are returned — exclusive, not inclusive, so polling with `since=` never returns a chat already seen. For incremental sync: pass the newest `timestamp` from the previous response as `since` on the next poll instead of refetching and diffing a full page client-side. in: query name: since required: false schema: anyOf: - format: date-time type: string - type: 'null' description: >- ISO-8601 timestamp. When set, only chats whose last activity (the same timestamp this list orders by) is strictly *newer than* `since` are returned — exclusive, not inclusive, so polling with `since=` never returns a chat already seen. For incremental sync: pass the newest `timestamp` from the previous response as `since` on the next poll instead of refetching and diffing a full page client-side. title: Since - description: >- UUID of the business the request is scoped to. Required on this route; the deprecated /businesses/{business_id}/... form takes it from the path instead. in: header name: business-id required: true schema: anyOf: - type: string - type: 'null' description: >- UUID of the business the request is scoped to. Required on this route; the deprecated /businesses/{business_id}/... form takes it from the path instead. title: Business-Id responses: '200': content: application/json: schema: $ref: '#/components/schemas/ChatListOut' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Missing or invalid credentials. '403': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: The credential is valid but not authorized for this action. '404': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: The resource, or the business named in the request, does not exist. '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error default: content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Unexpected error. security: - bearerAuth: [] components: schemas: ChatListOut: properties: chats: items: $ref: '#/components/schemas/ChatOut' title: Chats type: array pagination: $ref: '#/components/schemas/PaginationMeta' required: - chats - pagination title: ChatListOut type: object ApiError: description: >- The response body of a handled API error. ``detail`` is either a plain string (FastAPI's default for an ``HTTPException`` raised with a string, and for the ``default`` fastapi-users messages like ``"Not authenticated"``) or the structured :class:`ApiErrorDetail` object described above. ``code`` is present only on the top-level shape ``aizap.core.exceptions.AppException`` produces for its own 5xx responses (``"INTERNAL_ERROR"`` / ``"DB_ERROR"``); it does not duplicate the ``code`` nested inside a structured ``detail``. properties: code: anyOf: - type: string - type: 'null' default: null title: Code detail: anyOf: - type: string - $ref: '#/components/schemas/ApiErrorDetail' title: Detail required: - detail title: ApiError type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ChatOut: properties: business_id: format: uuid title: Business Id type: string consumer: anyOf: - $ref: '#/components/schemas/ChatConsumerOut' - type: 'null' conversation_id: anyOf: - format: uuid type: string - type: 'null' title: Conversation Id created: format: date-time title: Created type: string custom_instructions: anyOf: - items: {} type: array - type: 'null' title: Custom Instructions id: format: uuid title: Id type: string instructions: anyOf: - items: {} type: array - type: 'null' title: Instructions kind: default: real title: Kind type: string last_message: anyOf: - $ref: '#/components/schemas/LastMessageOut' - type: 'null' messages: items: {} title: Messages type: array refine_reviewed: default: false title: Refine Reviewed type: boolean refine_verdict: anyOf: - type: string - type: 'null' title: Refine Verdict session_id: format: uuid title: Session Id type: string timestamp: format: date-time title: Timestamp type: string required: - id - business_id - session_id - timestamp - messages - created title: ChatOut type: object PaginationMeta: properties: has_next: title: Has Next type: boolean has_previous: title: Has Previous type: boolean page: title: Page type: integer page_size: title: Page Size type: integer total_count: title: Total Count type: integer total_pages: title: Total Pages type: integer required: - page - page_size - total_count - total_pages - has_next - has_previous title: PaginationMeta type: object ApiErrorDetail: additionalProperties: true description: |- The structured ``detail`` object some error responses carry. Several handlers (the REST API plan gate, the free-tier limits, the webhooks entitlement gate, the closed customer-service window) raise ``HTTPException(detail={"code": ..., "message": ..., ...})`` — a fixed ``code``/``message`` pair plus extra fields specific to that error. ``extra="allow"`` keeps those fields in the documented shape instead of dropping them. properties: code: title: Code type: string message: title: Message type: string required: - code - message title: ApiErrorDetail type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object ChatConsumerOut: properties: id: format: uuid title: Id type: string nickname: anyOf: - type: string - type: 'null' title: Nickname phone_number: anyOf: - type: string - type: 'null' title: Phone Number required: - id title: ChatConsumerOut type: object LastMessageOut: properties: content: title: Content type: string no_reply: default: false title: No Reply type: boolean status: title: Status type: string required: - status - content title: LastMessageOut type: object securitySchemes: bearerAuth: description: >- Personal access token (izap_pat_…) sent as Authorization: Bearer ; dashboard session JWTs are also accepted. scheme: bearer type: http ````