> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingmee.co.il/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Messages

> Fetches messages for a conversation identified by the business phone number and the customer (target) phone number. Results are ordered newest first. Omit `startKey` on the first request. For each following batch, set `startKey` to the `lastEvaluatedKey` value returned by the previous response.

<Note>
  **Pagination:** For the first request, omit `startKey`. To fetch the next batch, take **`lastEvaluatedKey`** from the previous response and send it as **`startKey`** in the next request. That object has the shape `{ "messageId": "<string>", "createdAt": <number> }` (Unix time in milliseconds).
</Note>


## OpenAPI

````yaml POST /getMessages
openapi: 3.1.0
info:
  title: Pingmee API
  description: A complete guide to Pingmee micro service architecture.
  version: 1.0.0
servers:
  - url: https://api.pingmee.co.il
security:
  - cookieAuth: []
    ApiKeyAuth: []
paths:
  /getMessages:
    post:
      description: >-
        Fetches messages for a conversation identified by the business phone
        number and the customer (target) phone number. Results are ordered
        newest first. Omit `startKey` on the first request. For each following
        batch, set `startKey` to the `lastEvaluatedKey` value returned by the
        previous response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMessagesRequest'
      responses:
        '200':
          description: Messages and pagination metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesResponse'
        '400':
          description: Missing or invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GetMessagesRequest:
      type: object
      description: >-
        Use `startKey` only after the first page: set it to `lastEvaluatedKey`
        from the prior response to fetch the next batch.
      required:
        - phoneNumberId
        - targetPhoneNumberId
      properties:
        phoneNumberId:
          type: string
          description: Business / sender phone number ID
        targetPhoneNumberId:
          type: string
          description: Customer (other party) phone number ID
        startKey:
          $ref: '#/components/schemas/MessagesCursorKey'
      additionalProperties: false
    GetMessagesResponse:
      type: object
      required:
        - dbObject
        - hasMoreItemsToFetch
      properties:
        dbObject:
          type: array
          description: Messages (newest first), each a prepared `Message` object
          items:
            $ref: '#/components/schemas/Message'
        hasMoreItemsToFetch:
          type: boolean
          description: Whether more messages exist beyond this page
        lastEvaluatedKey:
          $ref: '#/components/schemas/MessagesCursorKey'
          description: >-
            When present, use this value as `startKey` in the next request to
            fetch the next batch of (older) messages.
      additionalProperties: false
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    MessagesCursorKey:
      type: object
      description: >-
        Pagination cursor. Returned as `lastEvaluatedKey` in the response; send
        the same object as `startKey` on the next request to load the next
        batch. Shape: `{ "messageId": "<string>", "createdAt": <number> }` (Unix
        milliseconds). Omit `startKey` on the first request.
      required:
        - messageId
        - createdAt
      properties:
        messageId:
          type: string
          description: Message ID from the pagination cursor (`lastEvaluatedKey`)
        createdAt:
          type: number
          description: Created-at timestamp in Unix milliseconds (from `lastEvaluatedKey`)
      additionalProperties: false
    Message:
      type: object
      description: A prepared message returned by getMessages
      required:
        - messageId
        - createdAt
        - sender
        - receiver
        - initiator
        - status
        - updatedAt
        - participantsIdentifiers
        - message
        - type
        - messagePlatform
        - creationPlatform
        - associatedTo
        - messageDirection
      properties:
        messageId:
          type: string
          description: Unique message ID
        createdAt:
          type: number
          description: Created at (Unix milliseconds)
        sender:
          type: string
          description: Sender identifier (e.g. phone number ID)
        receiver:
          type: string
          description: Receiver identifier
        initiator:
          type: string
          description: Who initiated the message (`Initiator`, e.g. person, bot, ai)
        status:
          type: string
          description: WhatsApp / platform delivery status (`WhatsAppMessageStatus`)
        updatedAt:
          type: number
          description: Last update (Unix milliseconds)
        participantsIdentifiers:
          type: string
          description: Stable conversation participant key
        message:
          type: string
          description: Message body text
        type:
          type: string
          description: Message type (`MessageType`)
        messagePlatform:
          type: string
          description: Platform the message was sent on (`PlatformType`)
        creationPlatform:
          type: string
          description: Platform where the message was created (`PlatformType`)
        associatedTo:
          type: string
          description: Business / account association
        messageDirection:
          type: string
          description: Direction relative to the business (`MessageDirection`)
        hasReaction:
          type: boolean
          description: Whether the message has reactions
        hasAttachment:
          type: boolean
          description: Whether the message includes media
        translation:
          $ref: '#/components/schemas/AITranslation'
        error:
          $ref: '#/components/schemas/WhatsAppErrorMessage'
        agentIdentification:
          $ref: '#/components/schemas/AgentIdentification'
        context:
          $ref: '#/components/schemas/WhatsAppMessageContext'
        comment:
          $ref: '#/components/schemas/SocialComment'
        attachment:
          $ref: '#/components/schemas/FileMetadata'
        attachmentBase64:
          $ref: '#/components/schemas/MessageBase64Attachment'
        reactions:
          type: array
          items:
            $ref: '#/components/schemas/MessageReaction'
        richContent:
          $ref: '#/components/schemas/RichContent'
        informativeMessageType:
          type: string
          description: >-
            System / informative message subtype when applicable
            (`InformativeMessageType`)
      additionalProperties: false
    AITranslation:
      type: object
      description: AI translation payload for the message
      additionalProperties: false
    WhatsAppErrorMessage:
      type: object
      description: WhatsApp / platform error details when sending failed
      additionalProperties: false
    AgentIdentification:
      type: object
      description: Agent who sent or handled the message
      additionalProperties: false
    WhatsAppMessageContext:
      type: object
      description: Reply context for a WhatsApp message
      properties:
        from:
          type: string
          description: Original sender phone number ID
        id:
          type: string
          description: Original message ID
      additionalProperties: false
    SocialComment:
      type: object
      description: Social (e.g. Instagram/Facebook) comment payload
      additionalProperties: false
    FileMetadata:
      type: object
      description: Attachment file metadata
      additionalProperties: false
    MessageBase64Attachment:
      type: object
      description: Base64-encoded media attachment metadata
      properties:
        resourceId:
          type: string
        fileName:
          type: string
        fileMimeType:
          type: string
        fileSize:
          type: number
        fileType:
          type: string
      additionalProperties: false
    MessageReaction:
      type: object
      description: Single reaction on the message
      additionalProperties: false
    RichContent:
      type: object
      description: Structured rich content (buttons, lists, etc.)
      additionalProperties: false
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: header
      name: Cookie
      description: Personal access token from Pingmee Settings → Developer Tools
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Business API key from Pingmee Settings → Developer Tools

````