> ## Documentation Index > Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt > Use this file to discover all available pages before exploring further. # List conversation messages > Messages in this thread, newest first, across every channel it has carried. Reply with `POST /v1/messages`, passing the conversation's `senderId` as the `Zavu-Sender` header so the answer leaves from the number the contact already knows. ## OpenAPI ````yaml /openapi.json get /v1/conversations/{conversationId}/messages openapi: 3.0.3 info: title: Zavu Unified Messaging Layer API version: 0.2.0 description: > Unified multi-channel messaging API for Zavu. Supported channels: - **SMS**: Simple text messages - **WhatsApp**: Rich messaging with media, buttons, lists, CTA URL buttons, location requests, and templates - **Telegram**: Bot messaging with text, media, and interactive elements - **Email**: Transactional emails via Amazon SES Design goals: - Simple `send()` entrypoint for developers - Project-level authentication via Bearer token - Support for all WhatsApp message types (text, image, video, audio, document, sticker, location, contact, buttons, list, cta_url, location_request, reaction, template) - If a non-text message type is sent, WhatsApp channel is used automatically - 24-hour WhatsApp conversation window enforcement - Universal `to` field accepts phone numbers (E.164), email addresses, or numeric chat IDs (Telegram/Instagram/Messenger) servers: - url: https://api.zavu.dev security: - bearerAuth: [] paths: /v1/conversations/{conversationId}/messages: get: tags: - Conversations summary: List conversation messages description: >- Messages in this thread, newest first, across every channel it has carried. Reply with `POST /v1/messages`, passing the conversation's `senderId` as the `Zavu-Sender` header so the answer leaves from the number the contact already knows. operationId: listConversationMessages parameters: - $ref: '#/components/parameters/ConversationIdParam' - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: cursor in: query description: Opaque cursor from a previous response's `nextCursor`. schema: type: string responses: '200': description: List of messages. content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Message' nextCursor: type: string nullable: true '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Conversation not found. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: parameters: ConversationIdParam: name: conversationId in: path required: true schema: type: string schemas: Message: type: object required: - id - to - status - channel - messageType - createdAt properties: id: type: string example: jd7x2k3m4n5p6q7r8s9t0 to: type: string example: '+56912345678' from: type: string example: '+13125551212' senderId: type: string example: sender_12345 channel: $ref: '#/components/schemas/Channel' messageType: $ref: '#/components/schemas/MessageType' status: $ref: '#/components/schemas/MessageStatus' text: type: string description: Text content or caption. content: $ref: '#/components/schemas/MessageContent' conversationId: type: string description: >- ID of the conversation (inbox thread) this message belongs to. Use it to build a direct dashboard link: `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. Omitted only on legacy messages created before conversation threading. example: js723987cyghwqxxaxcf590qd18axd95 providerMessageId: type: string description: Message ID from the delivery provider. errorCode: type: string nullable: true errorMessage: type: string nullable: true cost: type: number nullable: true description: >- Zavu platform charge in USD for this message. Messaging is billed against your plan's monthly limits plus usage-based overage. costProvider: type: number nullable: true description: Carrier and delivery cost in USD. costTotal: type: number nullable: true description: Total cost in USD (platform charge + delivery cost). metadata: type: object additionalProperties: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object required: - code - message properties: code: type: string example: invalid_request message: type: string example: Phone number is invalid details: type: object additionalProperties: true Channel: type: string description: Delivery channel. Use 'auto' for intelligent routing. enum: - auto - sms - sms_oneway - whatsapp - telegram - email - instagram - messenger - voice MessageType: type: string description: >- Type of message. Non-text types are supported by WhatsApp and Telegram (varies by type). `location_request` asks the recipient to share their location and is WhatsApp-only. It takes no `content` object — the prompt goes in `text` (max 1024 characters) and the button label is fixed by WhatsApp. The recipient's answer arrives as an inbound `location` message whose `content.replyToMessageId` is the ID of the request. `request_contact_info` asks the recipient to share their phone number and is WhatsApp-only. Like `location_request` it takes no `content` object — the prompt goes in `text` (max 1024 characters) and WhatsApp renders a fixed **Share Contact Info** button. The answer arrives as an inbound `contact` message. Use it to recover the phone number of a contact who adopted a WhatsApp username and is only known by their business-scoped user ID (BSUID); when they share it, Zavu automatically links the phone number to that contact. enum: - text - image - video - audio - document - sticker - location - contact - buttons - list - cta_url - request_contact_info - location_request - reaction - template MessageStatus: type: string enum: - queued - sending - sent - delivered - read - failed - received - pending_url_verification MessageContent: type: object description: Content for non-text message types (WhatsApp and Telegram). properties: mediaUrl: type: string description: URL of the media file (for image, video, audio, document, sticker). example: https://example.com/image.jpg mediaId: type: string description: WhatsApp media ID if already uploaded. mimeType: type: string description: MIME type of the media. example: image/jpeg filename: type: string description: Filename for documents. example: invoice.pdf latitude: type: number description: Latitude for location messages. longitude: type: number description: Longitude for location messages. locationName: type: string description: Name of the location. locationAddress: type: string description: Address of the location. contacts: type: array description: Contact cards for contact messages. items: type: object properties: name: type: string phones: type: array items: type: string buttons: type: array description: Interactive buttons (max 3). maxItems: 3 items: type: object required: - id - title properties: id: type: string maxLength: 256 title: type: string maxLength: 20 listButton: type: string description: Button text for list messages. maxLength: 20 sections: type: array description: Sections for list messages. items: type: object required: - title - rows properties: title: type: string rows: type: array maxItems: 10 items: type: object required: - id - title properties: id: type: string title: type: string maxLength: 24 description: type: string maxLength: 72 ctaDisplayText: type: string description: Button label for cta_url messages. maxLength: 20 example: See Dates ctaUrl: type: string format: uri description: >- Destination URL opened in the device's default browser when the button is tapped. Used with messageType=cta_url. WhatsApp requires HTTPS in production. example: https://example.com/schedule ctaHeaderType: type: string description: Optional header type for cta_url messages. enum: - text - image - video - document ctaHeaderText: type: string description: Header text when ctaHeaderType is 'text'. maxLength: 60 ctaHeaderMediaUrl: type: string format: uri description: >- Public HTTPS URL of the header media when ctaHeaderType is 'image', 'video', or 'document'. WhatsApp fetches this URL — it must be publicly reachable and return the declared content type. footerText: type: string description: Optional footer text for cta_url messages. maxLength: 60 example: Dates subject to change. emoji: type: string description: Emoji for reaction messages. reactToMessageId: type: string description: Message ID to react to. replyToMessageId: type: string description: >- Zavu message ID of the quoted message this message replies to. Present on inbound messages that quote an earlier message. Omitted when the quoted message is not found in Zavu (e.g. an old or unknown message) — use replyToProviderMessageId in that case. replyToProviderMessageId: type: string description: >- Provider message ID (WhatsApp WAMID) of the quoted message. Present whenever an inbound message is a reply, even if the quoted message is not stored in Zavu. replyToFrom: type: string description: Sender of the quoted message (phone number in E.164 format). replyToText: type: string description: >- Truncated snippet of the quoted message's text, for display. Empty when the quoted message has no text (e.g. media). replyToMessageType: type: string description: Type of the quoted message (text, image, video, etc.). templateId: type: string description: Template ID for template messages. templateVariables: type: object description: >- Variables for body placeholders. Key them to match the template body: by position (`1`, `2`, ...) for positional templates, or by name (e.g. `customer_name`) for named templates. Zavu detects the template's format and sends the correct payload to Meta. Named keys also resolve a named text-header variable. Do not mix positional and named keys in the same request. additionalProperties: type: string example: '1': John '2': ORD-12345 templateButtonVariables: type: object description: >- Variables for dynamic button placeholders (URL buttons and OTP buttons). Keys are the button index (0, 1, 2) in the template's `buttons` array — not the placeholder name. Values substitute the `{{1}}` placeholder inside that button's URL. **WhatsApp constraints:** - URL buttons only accept `{{1}}` — positional, numeric, no whitespace, no name. Named placeholders like `{{token}}` are stored as literal URL text by Meta and cannot be substituted. - At most one placeholder per URL button. - A template may have at most three buttons. - Static URL buttons (no placeholder) and `quick_reply` buttons are not included here. additionalProperties: type: string example: '0': abc-report-token templateHeaderVariables: type: object description: >- Value for a text-header variable, keyed by `1` (WhatsApp text headers allow at most one variable). Optional override. If omitted, Zavu resolves the header from `templateVariables` using the header placeholder's name (e.g. `novios`). Static text headers need no value. additionalProperties: type: string example: '1': Jorge y Laura securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````