> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get message by ID > Retrieve a single WhatsApp message by its message ID. Returns the message with all its fields, including Kapso extensions like status, direction, and processing state. ## OpenAPI ````yaml /api/meta/whatsapp/openapi-whatsapp.yaml get /{phone_number_id}/messages/{message_id} openapi: 3.1.0 info: title: Kapso Meta Proxy API version: 1.0.0 description: > Kapso's Meta Proxy API provides a unified interface to WhatsApp Business Platform with enhanced features and Kapso-specific extensions. This API acts as a proxy layer between your application and WhatsApp, adding: - Simplified authentication with project-level API keys - Enhanced message metadata and tracking - Conversation management capabilities - Voice call integration - Extended contact and template management ## Base URL All API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0` ## Authentication The API supports authentication via **X-API-Key header** (recommended): ``` X-API-Key: your_project_api_key ``` Alternative: Bearer token authentication is also supported for backward compatibility: ``` Authorization: Bearer your_access_token ``` Note: X-API-Key is the recommended authentication method for the Meta Proxy API. contact: name: Kapso Support url: https://kapso.ai email: dev@kap.so servers: - url: https://api.kapso.ai/meta/whatsapp/v24.0 description: Production server security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Messages description: Send and retrieve WhatsApp messages - name: Conversations description: Manage WhatsApp conversations - name: Contacts description: Manage WhatsApp contacts - name: Templates description: Manage message templates - name: Media description: Upload and retrieve media files - name: Calls description: Manage voice calls - name: Settings description: Account settings and configuration - name: Business Profile description: Business profile management - name: Phone Numbers description: Phone number management - name: Flows description: WhatsApp Flow management (Beta) - name: Block Users description: Block and unblock WhatsApp users paths: /{phone_number_id}/messages/{message_id}: parameters: - name: phone_number_id in: path required: true description: WhatsApp Business Phone Number ID schema: type: string example: '110987654321' - name: message_id in: path required: true description: WhatsApp message ID schema: type: string example: wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== get: tags: - Messages summary: Get message by ID description: > Retrieve a single WhatsApp message by its message ID. Returns the message with all its fields, including Kapso extensions like status, direction, and processing state. operationId: getMessage parameters: - name: fields in: query description: > Filter response fields. Use `kapso()` to include Kapso-specific extensions. Example: `fields=kapso(direction,status,processing_status)` schema: type: string example: kapso() responses: '200': description: Successfully retrieved message content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageResponse' examples: inbound_text: summary: Inbound text message value: id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== timestamp: '1705328096' type: text from: '15551234567' text: body: Hello! I need help with my order kapso: direction: inbound status: delivered processing_status: completed phone_number: '+15551234567' has_media: false whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000 contact_name: John Doe content: Hello! I need help with my order outbound_image: summary: Outbound image with caption value: id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFCAA== timestamp: '1705328150' type: image to: '15551234567' image: id: abc123def456 caption: Your order has been shipped! kapso: direction: outbound status: sent processing_status: completed phone_number: '+15551234567' has_media: true whatsapp_conversation_id: 123e4567-e89b-12d3-a456-426614174000 contact_name: John Doe media_data: url: https://api.kapso.ai/storage/media/abc123.jpg filename: package.jpg content_type: image/jpeg byte_size: 245678 media_url: https://api.kapso.ai/storage/media/abc123.jpg message_type_data: caption: Your order has been shipped! has_media: true '401': description: Unauthorized (invalid or missing API key) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Message not found or doesn't belong to this phone number content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Message not found type: MessageError code: 404 components: schemas: WhatsappMessageResponse: type: object required: - id - timestamp - type properties: id: type: string description: Message ID example: wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== timestamp: type: string description: Message timestamp (Unix timestamp as string) example: '1705328096' type: $ref: '#/components/schemas/MessageType' from: type: string nullable: true description: Sender WhatsApp ID (phone-based identity when available) example: '15551234567' from_user_id: type: string nullable: true description: Sender business-scoped user ID when available example: US.13491208655302741918 from_parent_user_id: type: string nullable: true description: Sender parent business-scoped user ID when available example: US.ENT.506847293015824 to: type: string nullable: true description: Recipient WhatsApp ID (phone-based identity when available) example: '110987654321' to_user_id: type: string nullable: true description: Recipient business-scoped user ID when available example: US.13491208655302741918 to_parent_user_id: type: string nullable: true description: Recipient parent business-scoped user ID when available example: US.ENT.506847293015824 username: type: string nullable: true description: WhatsApp username when available example: '@testusername' context: type: object description: Reply context properties: from: type: string description: Sender of the original message id: type: string description: ID of the message being replied to referred_product: type: object description: Product reference (for catalog messages) properties: catalog_id: type: string product_retailer_id: type: string text: $ref: '#/components/schemas/TextMessage' image: $ref: '#/components/schemas/MediaMessage' video: $ref: '#/components/schemas/MediaMessage' audio: $ref: '#/components/schemas/AudioMessage' document: $ref: '#/components/schemas/MediaMessage' sticker: $ref: '#/components/schemas/StickerMessage' location: $ref: '#/components/schemas/LocationMessage' contacts: type: array items: $ref: '#/components/schemas/ContactCard' order: $ref: '#/components/schemas/OrderMessage' interactive: type: object description: Interactive message content (for inbound interactive responses). properties: type: type: string enum: - button_reply - list_reply - nfm_reply description: |- Type of interactive response: - button_reply: Reply button was tapped - list_reply: List item was selected - nfm_reply: Native Flow Message (address_message, etc.) example: button_reply button_reply: type: object description: Reply button response properties: id: type: string description: Button ID that was tapped example: button_1 title: type: string description: Button title that was tapped example: 'Yes' list_reply: type: object description: List selection response properties: id: type: string description: Row ID that was selected example: row_express title: type: string description: Row title that was selected example: Express Shipping description: type: string description: Row description example: 1-2 business days nfm_reply: type: object description: Native Flow Message response (e.g., address_message) properties: name: type: string description: NFM action name example: address_message response_json: type: string description: JSON string containing form response data example: '{"values":{"name":"John Doe","in_pin_code":"400063"}}' body: type: string description: Human-readable summary of response example: John Doe, +919876543210, 400063, Mumbai template: type: object description: Template message content reaction: $ref: '#/components/schemas/ReactionMessage' kapso: type: object description: Kapso-specific message extensions properties: direction: type: string enum: - inbound - outbound description: Message direction example: inbound status: type: string enum: - pending - sent - delivered - read - failed description: Delivery status example: delivered processing_status: type: string enum: - pending - processing - completed - failed description: Processing state example: completed phone_number: type: string nullable: true description: Associated phone number when phone-based identity is available example: '+15559876543' has_media: type: boolean description: Whether message has attached media files example: false whatsapp_conversation_id: type: string description: Conversation UUID example: 123e4567-e89b-12d3-a456-426614174000 contact_name: type: string nullable: true description: Contact display name from conversation example: John Doe content: type: string nullable: true description: Message text content example: Hello! I need help with my order media_data: type: object description: Complete media information (when has_media is true) properties: url: type: string format: uri description: Download URL for the media file example: https://api.kapso.ai/storage/media/abc123.jpg filename: type: string description: Original filename example: package.jpg content_type: type: string description: MIME type example: image/jpeg byte_size: type: integer description: File size in bytes example: 245678 media_url: type: string format: uri description: >- Convenience field with just the media URL (when has_media is true) example: https://api.kapso.ai/storage/media/abc123.jpg message_type_data: type: object description: Type-specific message data (structure varies by message type) additionalProperties: true flow_response: type: object description: Flow response data (for Flow messages) additionalProperties: true flow_token: type: string description: Flow session token (for Flow messages) example: user_session_abc123 flow_name: type: string description: Flow display name (for Flow messages) example: Appointment Booking order_text: type: string description: Order text (for order messages) example: I'd like to order this item Error: type: object required: - error properties: error: type: object required: - message - type - code properties: message: type: string description: Human-readable error message example: Invalid phone number format type: type: string description: Error category example: OAuthException code: type: integer description: Error code example: 400 error_subcode: type: integer description: More specific error code example: 1001 fbtrace_id: type: string description: Facebook trace ID for debugging example: AXk7s_8dR4eVHp9Kq2MmNlO MessageType: type: string enum: - text - image - video - audio - document - sticker - location - contacts - interactive - template - reaction description: Type of WhatsApp message TextMessage: type: object required: - body properties: body: type: string description: Text content of the message example: Hello! How can I help you today? preview_url: type: boolean description: Whether to show URL preview (defaults to false if omitted) example: true MediaMessage: type: object properties: id: type: string description: |- Media ID from WhatsApp (uploaded media). Recommended over `link` for better performance. example: abc123def456 link: type: string format: uri description: >- Public URL to media file (hosted media). Using uploaded media with `id` is recommended for better performance. example: https://example.com/image.jpg caption: type: string description: |- Media caption text. - Images: max 1024 characters - Videos: max 1024 characters - Documents: max 1024 characters Not supported for stickers or audio. maxLength: 1024 example: Check out this photo! filename: type: string description: >- Filename with extension (for documents only). WhatsApp client displays appropriate file type icon based on extension. example: report.pdf AudioMessage: type: object properties: id: type: string description: Media ID from WhatsApp (uploaded media) example: abc123def456 link: type: string format: uri description: >- Public URL to audio file (hosted media). Using uploaded media with `id` is recommended for better performance. example: https://example.com/audio.mp3 voice: type: boolean description: >- Set to `true` for voice messages (voice notes with transcription support). Voice messages must be .ogg files encoded with OPUS codec. Set to `false` or omit for basic audio messages. Voice messages include: automatic download, profile picture, voice icon, and optional transcription. Basic audio messages display a download icon and music icon. example: true StickerMessage: type: object properties: id: type: string description: Media ID from WhatsApp example: abc123def456 link: type: string format: uri description: Public URL to sticker file example: https://example.com/sticker.webp mime_type: type: string description: MIME type of the sticker example: image/webp animated: type: boolean description: Whether the sticker is animated example: false LocationMessage: type: object required: - latitude - longitude properties: latitude: type: number format: double description: Latitude coordinate example: 37.7749 longitude: type: number format: double description: Longitude coordinate example: -122.4194 name: type: string description: Location name example: Golden Gate Bridge address: type: string description: Location address example: San Francisco, CA ContactCard: type: object required: - name properties: addresses: type: array description: Physical addresses for the contact items: type: object properties: street: type: string description: Street number and name example: 1 Lucky Shrub Way city: type: string description: City name example: Menlo Park state: type: string description: State abbreviation or full name example: CA zip: type: string description: ZIP or postal code example: '94025' country: type: string description: Full country name example: United States country_code: type: string description: Two-letter country code (ISO 3166-1 alpha-2) example: US type: type: string description: Address type (HOME, WORK, etc.) example: WORK birthday: type: string format: date description: Contact's birthday in YYYY-MM-DD format example: '1999-01-23T00:00:00.000Z' emails: type: array items: type: object properties: email: type: string example: john@example.com type: type: string example: WORK name: type: object required: - formatted_name properties: formatted_name: type: string description: Full formatted name (appears in message) maxLength: 200 example: Barbara J. Johnson first_name: type: string description: First name example: Barbara last_name: type: string description: Last name example: Johnson middle_name: type: string description: Middle name example: Joana suffix: type: string description: Name suffix (Jr., Sr., etc.) example: Esq. prefix: type: string description: Name prefix (Dr., Mr., Ms., etc.) example: Dr. org: type: object description: Organization information properties: company: type: string description: Company name example: Lucky Shrub department: type: string description: Department name example: Legal title: type: string description: Job title example: Lead Counsel phones: type: array items: type: object properties: phone: type: string description: Phone number example: '+15551234567' type: type: string description: Phone type (MOBILE, HOME, WORK, etc.) example: MOBILE wa_id: type: string description: >- WhatsApp ID for this phone number. If omitted, message will display "Invite to WhatsApp" button instead of "Message" button. example: '15551234567' urls: type: array description: Website URLs associated with the contact items: type: object properties: url: type: string format: uri description: Website URL example: https://www.luckyshrub.com type: type: string description: Website type (WORK, HOME, etc.) example: WORK OrderMessage: type: object properties: catalog_id: type: string description: Catalog ID example: cat_12345 product_items: type: array description: Array of product items items: type: object order_text: type: string description: Order text example: I'd like to order this item ReactionMessage: type: object required: - message_id - emoji properties: message_id: type: string description: ID of message to react to example: wamid.HBgNMTU1NTE... emoji: type: string description: Emoji to react with example: 👍 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: > Project API key for authentication. This is the recommended authentication method. Get your API key from the Kapso dashboard under Integrations > API keys. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Bearer token authentication (alternative method). Note: X-API-Key authentication is recommended for the Meta Proxy API. ````