> ## Documentation Index > Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Messages > Get filtered chat history (messages only) for a specific chat. Supports filtering by direction, date range, and message UID. ## OpenAPI ````yaml get /chats/{chat_id}/messages openapi: 3.0.3 info: title: Timelines Public API description: > # Timelines Public API _Some API calls may utilize message sending quota or be subject to message sending rate limits as described below._ ### Credit Utilization - Sending a message via API consumes 1 credit from message sending quota. - Sending a message with non-empty text and attachment consumes 2 credits from message sending quota. - If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), message sending quota will be restored (usually within a couple of hours). ### Message sending rate - Messages will be sent with random delay of about 2 seconds between each two messages (to avoid WhatsApp spam detection mechanisms). Contact support@timelines.ai if you want to modify delay for your workspace (available on Business plan only). - If you exceed message sending frequency, messages be queued and sent out with delay. Each queued message will consume a message sending credit, so the number of queued messages cannot exceed the available quota. ### Authorization: - Copy API token from [Public API page](https://app.timelines.ai/integrations/api/) in your TimelinesAI account. - Put the token in *Authorization* header of request as follows: ``` Authorization: Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8 ``` ### Message formatting: - use "\n" for line breaks version: 1.3.0 servers: - url: /integrations/api description: Public API root URL security: - bearerAuth: [] paths: /chats/{chat_id}/messages: get: summary: Get filtered chat history (messages only) of the chat description: >- Leave filtering parameters empty to get the unfiltered list of all messages in the specified chat. When multiple filtering parameters are specified, logical AND operation is applied. The result is paginated, page size is 50 records. The result is ordered the timestamp of messages (descending). parameters: - $ref: '#/components/parameters/chat_id' - in: query name: from_me schema: type: boolean description: >- specify true to filter messages sent from my WhatsApp account (from any session), false to filter messages received from other WhatsApp users. example: true - in: query name: after schema: type: string description: >- can specify date or datetime in ISO format to filter out messages created AFTER the specified date (inclusive) example: 2024-01-17 10:35 - in: query name: before schema: type: string description: >- can specify date or datetime in ISO format to filter out messages created BEFORE the specified date (inclusive) example: 2024-01-19 15:30 - in: query name: after_message schema: type: string description: >- can specify message uid to filter out messages created after the specified message (excluding the specified message itself) example: d8cc5a02-b676-4956-8710-3ee56330f356 - in: query name: before_message schema: type: string description: >- can specify message uid to filter out messages created before the specified message (excluding the specified message itself) example: d8cc5a02-b676-4956-8710-3ee56330f356 - in: query name: sorting_order schema: type: string enum: - asc - desc description: 'order messages by timestamp, according to possible values: asc, desc' example: asc responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MessageListResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' components: parameters: chat_id: in: path name: chat_id schema: type: integer required: true description: >- an id of the chat as appears in TimelinesAI (can be found in the URL of the chat page, or in the payload of outbound webhook). _Supports sending messages to a group._ schemas: MessageListResponse: type: object required: - status - data properties: status: type: string example: ok enum: - ok - error data: type: object properties: has_more_pages: type: boolean messages: type: array items: $ref: '#/components/schemas/MessageInfo' MessageInfo: type: object required: - uid - chat_id - timestamp - received_timestamp - sender_phone - sender_name - recipient_phone - recipient_name - from_me - status - origin - has_attachment - message_type - data - created_by properties: uid: type: string example: de919486-0c93-409d-ae66-c2bbb544faca chat_id: example: '1000001' type: integer timestamp: description: message creation timestamp, WhatsApp message time example: 2023-06-18 15:19:23 +0300 type: string received_timestamp: description: >- message creation timestamp in TimelinesAI, in ISO format with timezone example: 2023-06-18 14:39:25 +0300 type: string sender_phone: example: '+972540000001' type: string sender_name: example: John Doe type: string recipient_phone: example: '+972540000002' type: string recipient_name: example: Kate Smith type: string from_me: example: true type: boolean text: example: Hello, KateπŸ‘ type: string description: > Message body text. `null` for attachment-only messages and for call / event messages. attachment_url: example: https://acme.com/logo.png type: string attachment_filename: example: logo.png type: string status: example: Read type: string description: > Delivery status, one of: `Sending`, `Sent`, `Delivered`, `Read`, `Failed`, `Pending`. For call messages, a call status (e.g. `answered`, `missed`) is returned instead. origin: example: Public API type: string description: > Human-readable origin of the message, e.g. `Public API`, `Shared Inbox`, `Mass Messaging`, `Chrome Extension`, `synced from WhatsApp`, `Webhook`. Additional values are possible (e.g. from OIDC / connected third-party apps), so treat this as an open-ended, display-only string rather than an exhaustive enum. has_attachment: example: true type: boolean message_type: example: Note type: string description: > Type of message: one of `whatsapp`, `whatsapp_call`, `note`, `email`, `summary`. reactions: $ref: '#/components/schemas/MessageReactionsObject' data: example: key1: value1 key2: value2 type: object description: > Free-form metadata object whose contents vary by `message_type` (for example, call status, or scheduled-event start/end times). Shape is not stable across message types. created_by: example: Kate Smith type: string description: > Display name of the team member who created the message; empty string for messages not created by a member (e.g. synced or inbound messages). ErrorResponse: required: - message - status type: object properties: message: type: string status: type: string example: error enum: - ok - error error_code: type: string description: >- Stable, machine-readable error code. Use this for branching in client integrations. example: validation_error enum: - missing_credentials - invalid_token - member_not_found - permission_denied - plan_feature_unavailable - quota_exceeded - rate_limit_exceeded - validation_error - not_supported - internal_error errors: type: array description: >- Per-field validation diagnostics. Present on `validation_error` responses; absent on auth/authorization/quota errors. items: $ref: '#/components/schemas/ValidationError' MessageReactionsObject: type: object required: - users - reactions - total properties: users: type: array items: $ref: '#/components/schemas/MessageReactionUser' reactions: type: object additionalProperties: type: integer example: πŸ‘: 2 ❀️: 5 total: type: integer example: 7 example: users: - name: John Doe phone: '+972540000001' reaction: πŸ‘ current: true - name: Kate Smith phone: '+972540000002' reaction: πŸ‘ current: false reactions: πŸ‘: 2 total: 2 ValidationError: type: object required: - fields - msg properties: fields: type: array items: type: string description: >- Path of the offending field, as a list of keys/indexes from the request root. example: - url msg: type: string description: Validator message for that field. example: must be a valid http(s) URL MessageReactionUser: type: object required: - name - phone - reaction - current properties: name: example: John Doe type: string phone: example: '+972540000001' type: string reaction: type: string example: πŸ‘ current: type: boolean description: >- True if the reaction was placed by the chat's contact (the remote end of a 1:1 conversation). False if placed by the workspace's own WhatsApp account, or in any group chat (groups have no single "remote contact" identity). example: true responses: BadRequestError: description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnauthorizedError: description: Access token is missing or invalid AccessDenied: description: Access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Specified entities not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer ````