# Get messages by tracking number (v2)

Retrieve the conversation history for a tracking number (GSTN or CTN) as lean MessageResponse objects, scoped to your client. Replaces the deprecated Get chat messages by tracking number.

Endpoint: GET /pl4chat-service/api/v2/messages/tracking/{trackingNumber}
Version: 3.0.0
Security: apikeyAuth

## Path parameters:

  - `trackingNumber` (string, required)
    The global system tracking number (GSTN) or conversation tracking number (CTN).
    Example: "GSTN-12345"

## Response 200 fields (application/json):

  - `id` (string)
    Example: "c9d01234-e5f6-a7b8-c9d0-1234e5f6a7b8"

  - `tempId` (string)
    Temporary client-generated id used to correlate a send request with its response. Present only when the sender supplied one.
    Example: "c9f0b308-1a0d-3f3f-7912-464f06677c6b"

  - `sequenceNumber` (integer)
    Monotonic ordering hint within the conversation.
    Example: 42

  - `direction` (string)
    Enum: "OUTGOING", "INCOMING"

  - `contentType` (string)
    Enum: "BUTTON", "CAROUSEL", "DROPDOWN", "IMAGE", "TEXT", "DATE", "FILE", "MEDIA", "LOCATION", "RATING"

  - `channel` (string)
    Enum: "WHATSAPP", "WEB", "FACEBOOK"

  - `text` (string)
    Example: "Hello, I need help with my account."

  - `createdTime` (string)
    Example: "2026-01-15T10:30:00Z"

  - `userOriginated` (boolean)
    true when a human typed the message (agent or customer); false for bot-generated messages.
    Example: true

  - `messageOwner` (string)
    Enum: "agent", "customer", "system"

  - `sender` (string)
    Address the message was sent from (e.g. the customer's phone number for inbound, the business number for outbound).
    Example: "+27987654321"

  - `receiver` (string)
    Address the message was delivered to.
    Example: "+27123456789"

  - `ctId` (string)
    Custom tracking id for the message, if one was supplied on send.
    Example: "order-1234-confirm"

  - `sent` (boolean)
    Example: true

  - `delivered` (boolean)
    Example: true

  - `read` (boolean)

  - `played` (boolean)
    True when a voice note was played (listened to) by the recipient.

  - `sentTime` (string)
    Example: "2026-01-15T10:30:01Z"

  - `deliveredTime` (string)
    Example: "2026-01-15T10:30:05Z"

  - `readTime` (string)
    Example: "2026-01-15T10:31:00Z"

  - `playedTime` (string)
    Timestamp the voice note was played.
    Example: "2026-01-15T10:31:30Z"

  - `mediaURL` (string)
    Example: "https://example.com/media/photo.jpg"

  - `fileExtension` (string)
    File extension of the attached media, when present.
    Example: "jpg"

  - `mediaType` (string)
    Enum: "DOCUMENT", "IMAGE", "VIDEO", "NULL", "BUTTON", "FILE", "AUDIO", "VOICE"

  - `latitude` (string)
    Example: "-26.2041"

  - `longitude` (string)
    Example: "28.0473"

  - `address` (string)
    Example: "123 Main St, Johannesburg"

  - `label` (string)
    Example: "Head Office"

  - `agent` (object)
    Lean reference to the agent who sent or owns a message.

  - `agent.id` (string)
    Example: "b2c3d4e5-f6a7-8901-b2c3-d4e5f6a78901"

  - `agent.firstName` (string)
    Example: "Alice"

  - `agent.lastName` (string)
    Example: "Smith"

  - `agent.email` (string)
    Example: "alice.smith@example.com"

  - `agent.avatar` (string)
    URL of the agent's avatar image.
    Example: "https://example.com/avatars/alice.png"

  - `reaction` (object)

  - `reaction.reactorName` (string)
    Example: "John Doe"

  - `reaction.reactorNumber` (string)
    Example: "+27821234567"

  - `reaction.reactionEmoji` (string)
    Example: "👍"

  - `whatsAppMessageId` (string)
    Provider (WhatsApp) message id.
    Example: "3EB09839C39C57F54A9EC5"

  - `facebookMessageId` (string)
    Provider (Facebook) message id.
    Example: "m_AbCdEf123456"

  - `quotedExternalMessageId` (string)
    WhatsApp id of the message this one replies to/quotes (present when the message is a reply).
    Example: "3EB0123456789ABCDEF0"

  - `quotedText` (string)
    Snapshot of the quoted message's text, captured at reply time.
    Example: "Hi, is this about order #1234?"

## Response 401 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Unauthorized user"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"