> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # List All Messages > This endpoint retrieves a paginated list of all messages across chats (in descending order of timestamp) ## OpenAPI ````yaml GET /chats/messages openapi: 3.0.3 info: title: API - Local description: >- #### Welcome to the official Postman collection of Periskope API Periskope APIs enable you automate actions on your WhatsApp phone, and the Periskope platform - Read more about the APIs & webhooks here - [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction) - We encourage responsible usage of the APIs. Follow these best practices and recommendations for safe actions on WhatsApp - [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices) #### Getting Started ##### Pre-requisites: 1. **Sign up for a free account on Periskope:** To use the Periskope API, you need to have an active Periskope account. If you don’t have one, you can sign up for a 7-day free trial [here](https://console.periskope.app). 2. **Scan the QR code from WhatsApp to connect your phone:** A connected phone is required to use the APIs 3. **Go to** [Settings > API](https://console.periskope.app/settings/api), and generate an API key for your organization - The API key is used to authenticate every request. Please keep this secure ##### Using Postman: 1. **Fork the collection so you can edit values and test the APIs in your own postman environment:** To fork the collection, click on the three dots next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F)._ 2. **Update the value of the variables in the collection:** \- Update the API key with the key generated in Step 3 \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_ For any help or feedback, please contact us at [support@periskope.app](https://mailto:support@periskope.app), or ping us on [WhatsApp](https://what.sapp.link/periskope) version: 1.0.0 contact: {} servers: - url: https://api.periskope.app/v1 security: - bearerAuth: [] tags: - name: contacts - name: tickets - name: tasks - name: phones - name: message - name: queue - name: chats - name: group - name: members - name: webhooks paths: /chats/messages: get: tags: - chats summary: List All Messages description: > This endpoint retrieves a paginated list of all messages across chats (in descending order of timestamp) operationId: listAllMessages parameters: - name: offset in: query schema: type: number example: '0' description: |- - The offset value for paginating the results - Default 0 - name: limit in: query schema: type: number example: '10' description: |- - The maximum number of messages to retrieve - Default 2000 - name: x-phone in: header schema: type: string example: '{{orgPhone}}' description: >- **Optional.** The phone to scope this request to — in country code + number format with no spaces or special characters (e.g. 919876543210), or the phone_id (phone-xxxxxxxxxxxx). When set, only messages for that phone are returned. When omitted, messages are returned — across all phones your token can access (the phones in your token's scope, or every phone in your organization if the token is unscoped). Passing a phone that is outside your token's scope returns a 401. - name: start_time in: query schema: type: string example: 2025-04-25 or 2025-04-25T00:00:00Z description: '- The start_time to filter the results' - name: end_time in: query schema: type: string example: 2025-04-31 or 2025-04-31T23:59:59Z description: '- The end_time to filter the results' responses: '200': description: 200 OK headers: Access-Control-Allow-Origin: schema: type: string example: '*' Connection: schema: type: string example: keep-alive Content-Length: schema: type: string example: '15052' Date: schema: type: string example: Fri, 24 Jan 2025 12:04:20 GMT ETag: schema: type: string example: W/"3acc-fvp5KujdZIathXpX7lmxPxDSdWc" Keep-Alive: schema: type: string example: timeout=5 X-Powered-By: schema: type: string example: Express X-RateLimit-Limit: schema: type: string example: '10' X-RateLimit-Remaining: schema: type: string example: '9' X-RateLimit-Reset: schema: type: string example: '1737720262' x-periskope-org-id: schema: type: string example: 2997dd64-89bf-48d3-9a22-b314fca017e5 x-periskope-phone-id: schema: type: string example: phone-bqzvyibhmwkaergr x-periskope-trace-id: schema: type: string example: 580db370-da4b-11ef-b1ab-4fe0c2e6e4c5 content: application/json: schema: type: object description: 'The response is a JSON object with the following properties:' properties: from: type: number example: 1 description: The starting index of the returned messages. to: type: number example: 10 description: The ending index of the returned messages. count: type: number example: 10 description: The total count of messages. messages: type: array description: >- An array of message objects. Refer to [the message object here](/api-reference/objects/the-message-object) examples: 200 OK: value: count: 10 from: 1 messages: - ack: '4' author: null body: >- You have been invited to join Test New 1039 https://chat.whatsapp.com/invite/CGiTdfn1dUM8J67GEx1lyx If you cannot click the link, please respond to this message, and the link will become active broadcast: null broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered: 919537851844@c.us: 1737695471721 delivered_count: 1 pending: [] read: 919537851844@c.us: 1737711828823 read_count: 1 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: true fts: >- '/invite/cgitdfn1dum8j67gex1lyx':12 '1039':9 'activ':29 'becom':28 'cannot':15 'chat.whatsapp.com':11 'chat.whatsapp.com/invite/cgitdfn1dum8j67gex1lyx':10 'click':16 'invit':4 'join':6 'link':18,26 'messag':23 'new':8 'pleas':19 'respond':20 'test':7 has_media: null has_quoted_msg: null has_reaction: null id: from_me: true id: 3EB0ABB7C973860FC19EBE05FD934141CCEC2D8B remote: 919537851844@c.us serialized: >- true_919537851844@c.us_3EB0ABB7C973860FC19EBE05FD934141CCEC2D8B interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: >- true_919537851844@c.us_3EB0ABB7C973860FC19EBE05FD934141CCEC2D8B message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 918527184400@c.us sent_message_id: 02a54379-36cc-456b-81c4-09074adf9597 timestamp: '2025-01-24T05:11:08+00:00' to: null token: null unique_id: 3EB0ABB7C973860FC19EBE05FD934141CCEC2D8B updated_at: '2025-01-24T09:43:48.884+00:00' vcards: null - ack: '0' author: null body: hello broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3FEBFB04480C6E256A37 remote: 919537851844@c.us serialized: false_919537851844@c.us_3FEBFB04480C6E256A37 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3FEBFB04480C6E256A37 message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T12:05:29+00:00' to: null token: null unique_id: 3FEBFB04480C6E256A37 updated_at: '2025-01-23T12:05:30.038+00:00' vcards: null - ack: '0' author: null body: hello broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3F5E1F0061E439AABF93 remote: 919537851844@c.us serialized: false_919537851844@c.us_3F5E1F0061E439AABF93 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3F5E1F0061E439AABF93 message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T12:04:57+00:00' to: null token: null unique_id: 3F5E1F0061E439AABF93 updated_at: '2025-01-23T12:04:58.332+00:00' vcards: null - ack: '0' author: null body: hello 4 broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''4'':2 ''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3FB3DB0CD9143F36DA1B remote: 919537851844@c.us serialized: false_919537851844@c.us_3FB3DB0CD9143F36DA1B interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3FB3DB0CD9143F36DA1B message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:24:08+00:00' to: null token: null unique_id: 3FB3DB0CD9143F36DA1B updated_at: '2025-01-23T11:24:09.265+00:00' vcards: null - ack: '0' author: null body: hello 3 broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''3'':2 ''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3FF19C7504579A580127 remote: 919537851844@c.us serialized: false_919537851844@c.us_3FF19C7504579A580127 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3FF19C7504579A580127 message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:24:07+00:00' to: null token: null unique_id: 3FF19C7504579A580127 updated_at: '2025-01-23T11:24:07.941+00:00' vcards: null - ack: '0' author: null body: hello 2 broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''2'':2 ''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3FBB9CD4D1AD736B47BA remote: 919537851844@c.us serialized: false_919537851844@c.us_3FBB9CD4D1AD736B47BA interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3FBB9CD4D1AD736B47BA message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:24:02+00:00' to: null token: null unique_id: 3FBB9CD4D1AD736B47BA updated_at: '2025-01-23T11:24:02.466+00:00' vcards: null - ack: '0' author: null body: hello 1 broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: '''1'':2 ''hello'':1' has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 3F7080525761DE5CE341 remote: 919537851844@c.us serialized: false_919537851844@c.us_3F7080525761DE5CE341 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: null media_key: null mentioned_ids: [] message_id: false_919537851844@c.us_3F7080525761DE5CE341 message_ticket_id: null message_type: chat order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:22:51+00:00' to: null token: null unique_id: 3F7080525761DE5CE341 updated_at: '2025-01-23T11:22:51.548+00:00' vcards: null - ack: '0' author: null body: null broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: null has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 17DEFC0BE5C1813C76E6267816452A02 remote: 919537851844@c.us serialized: >- false_919537851844@c.us_17DEFC0BE5C1813C76E6267816452A02 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: dimensions: ar: 0.3541666666666667 height: 1200 width: 425 filename: 17DEFC0BE5C1813C76E6267816452A02 mimetype: image/jpeg path: >- https://storage.googleapis.com/periskope-attachments/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us%2F17DEFC0BE5C1813C76E6267816452A02.jpeg size: 60511 thumbnail: >- https://storage.googleapis.com/periskope-attachments/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us%2F17DEFC0BE5C1813C76E6267816452A02%2Fthumbnail.png media_key: null mentioned_ids: [] message_id: >- false_919537851844@c.us_17DEFC0BE5C1813C76E6267816452A02 message_ticket_id: null message_type: image order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:17:00+00:00' to: null token: null unique_id: 17DEFC0BE5C1813C76E6267816452A02 updated_at: '2025-01-23T11:17:02.802+00:00' vcards: null - ack: '0' author: null body: null broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: null has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 6970084ECDA312DCA9D0C62A16697E31 remote: 919537851844@c.us serialized: >- false_919537851844@c.us_6970084ECDA312DCA9D0C62A16697E31 interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: dimensions: ar: 0.53515625 height: 1280 width: 685 filename: 6970084ECDA312DCA9D0C62A16697E31 mimetype: image/jpeg path: >- https://storage.googleapis.com/periskope-attachments/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us%2F6970084ECDA312DCA9D0C62A16697E31.jpeg size: 68972 thumbnail: >- https://storage.googleapis.com/periskope-attachments/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us%2F6970084ECDA312DCA9D0C62A16697E31%2Fthumbnail.png media_key: null mentioned_ids: [] message_id: >- false_919537851844@c.us_6970084ECDA312DCA9D0C62A16697E31 message_ticket_id: null message_type: image order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:15:35+00:00' to: null token: null unique_id: 6970084ECDA312DCA9D0C62A16697E31 updated_at: '2025-01-23T11:15:36.298+00:00' vcards: null - ack: '0' author: null body: null broadcast: false broadcast_id: null chat_id: 919537851844@c.us delivery_info: delivered_count: 0 pending: [] read_count: 0 device_type: null duration: null flag_metadata: null flag_response_time: null flag_status: null forwarding_score: null from: null from_me: false fts: null has_media: null has_quoted_msg: null has_reaction: null id: from_me: false id: 018456CD73B9C9E4AF84836F809A02BF remote: 919537851844@c.us serialized: >- false_919537851844@c.us_018456CD73B9C9E4AF84836F809A02BF interactive: null invite_v4: null is_deleted: null is_ephemeral: null is_forwarded: null is_gif: null is_starred: null is_status: null links: null location: null media: dimensions: ar: 0.4545454545454546 height: 1188 width: 540 filename: 018456CD73B9C9E4AF84836F809A02BF mimetype: image/jpeg path: >- https://storage.googleapis.com/periskope-attachments/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us%2F018456CD73B9C9E4AF84836F809A02BF.jpeg size: 57218 thumbnail: >- https://storage.googleapis.com/periskope-attachments/%7Bclient.org_id%7D%2F919537851844%40c.us%2F018456CD73B9C9E4AF84836F809A02BF%2Fthumbnail.jpeg media_key: null mentioned_ids: [] message_id: >- false_919537851844@c.us_018456CD73B9C9E4AF84836F809A02BF message_ticket_id: null message_type: image order_id: null org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 org_phone: 918527184400@c.us performed_by: null poll_info: null poll_results: null prev_body: null quoted_message_id: null raw_data: null sender_phone: 919537851844@c.us sent_message_id: null timestamp: '2025-01-23T11:14:23+00:00' to: null token: null unique_id: 018456CD73B9C9E4AF84836F809A02BF updated_at: '2025-01-23T11:14:24.598+00:00' vcards: null to: 10 '422': description: 422 Invalid Limit headers: Access-Control-Allow-Origin: schema: type: string example: '*' Connection: schema: type: string example: keep-alive Content-Length: schema: type: string example: '197' Date: schema: type: string example: Thu, 09 Jan 2025 09:08:02 GMT ETag: schema: type: string example: W/"c5-sOfQmoGHJ22vOJ8WnucWzYQT5DI" Keep-Alive: schema: type: string example: timeout=5 X-Powered-By: schema: type: string example: Express X-RateLimit-Limit: schema: type: string example: '10' X-RateLimit-Remaining: schema: type: string example: '9' X-RateLimit-Reset: schema: type: string example: '1736413684' org_id: schema: type: string example: 2997dd64-89bf-48d3-9a22-b314fca017e5 x-periskope-trace-id: schema: type: string example: 3afe7fa0-ce69-11ef-9fd2-914300695506 content: application/json: schema: type: object properties: code: type: string example: VALIDATION_ERROR fields: type: object properties: limit: type: object properties: message: type: string example: Limit should be less than 2000 value: type: string example: '10000' message: type: string example: Limit should be less than ${MAX_LIMIT} name: type: string example: Validation Error status: type: number example: 422 examples: 422 Invalid Limit: value: code: VALIDATION_ERROR fields: limit: message: Limit should be less than 2000 value: '10000' message: Limit should be less than ${MAX_LIMIT} name: Validation Error status: 422 x-codeSamples: - lang: TypeScript label: Node.js source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: 'YOUR_PHONE_NUMBER', // Optional for this endpoint — omit to return messages across all phones your token can access }); async function getMessages() { const response = await client.chat.getMessages(); console.log(response); } getMessages(); - lang: cURL label: cURL source: > # x-phone is optional for this endpoint — omit it to return messages across all phones your token can access curl -X GET \ https://api.periskope.app/v1/chats/messages \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'x-phone: YOUR_PHONE_NUMBER' \ components: securitySchemes: bearerAuth: type: http scheme: bearer ````