> ## 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. # Send a message > Send a WhatsApp message to a recipient. Use `to` for phone numbers. Use `recipient` for a BSUID or parent BSUID. If both are present, the phone number in `to` takes precedence. Supports all WhatsApp message types: - **text**: Plain text messages with optional URL preview - **image**: Images with optional caption - **video**: Videos with optional caption - **audio**: Audio files - **document**: Documents with optional caption and filename - **sticker**: Stickers - **location**: Location sharing - **contacts**: Contact cards - **interactive**: Interactive messages (buttons, lists, flows) - **template**: Message templates - **reaction**: Emoji reactions to messages ## OpenAPI ````yaml /api/meta/whatsapp/openapi-whatsapp.yaml post /{phone_number_id}/messages 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 - name: Usernames description: Reserve and manage WhatsApp business usernames paths: /{phone_number_id}/messages: parameters: - name: phone_number_id in: path required: true description: WhatsApp Business Phone Number ID schema: type: string example: '110987654321' post: tags: - Messages summary: Send a message description: | Send a WhatsApp message to a recipient. Use `to` for phone numbers. Use `recipient` for a BSUID or parent BSUID. If both are present, the phone number in `to` takes precedence. Supports all WhatsApp message types: - **text**: Plain text messages with optional URL preview - **image**: Images with optional caption - **video**: Videos with optional caption - **audio**: Audio files - **document**: Documents with optional caption and filename - **sticker**: Stickers - **location**: Location sharing - **contacts**: Contact cards - **interactive**: Interactive messages (buttons, lists, flows) - **template**: Message templates - **reaction**: Emoji reactions to messages operationId: sendMessage requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/WhatsappMessage' - $ref: '#/components/schemas/MarkReadRequest' examples: text_message: summary: Send text message value: messaging_product: whatsapp recipient_type: individual to: '15551234567' type: text text: body: 'Hello! Your order #12345 has been shipped.' text_message_to_bsuid: summary: Send text message to BSUID description: >- Non-template messages require an open 24-hour customer service window. value: messaging_product: whatsapp recipient_type: individual recipient: US.13491208655302741918 type: text text: body: 'Hello! Your order #12345 has been shipped.' template_to_bsuid: summary: Send template to BSUID value: messaging_product: whatsapp recipient_type: individual recipient: US.13491208655302741918 type: template template: name: order_update language: code: en_US image_message: summary: Send image with caption value: messaging_product: whatsapp to: '15551234567' type: image image: link: https://example.com/product.jpg caption: Check out our new product! voice_message: summary: Send voice message (voice note) description: >- Voice messages must be .ogg files encoded with OPUS codec. Includes automatic download, profile picture, voice icon, and optional transcription. value: messaging_product: whatsapp to: '15551234567' type: audio audio: id: '1013859600285441' voice: true basic_audio_message: summary: Send basic audio message description: |- Basic audio messages display a download icon and music icon. Supports AAC, AMR, MP3, MP4, and OGG formats (max 16MB). value: messaging_product: whatsapp to: '15551234567' type: audio audio: link: https://example.com/ringtone.mp3 template_named_params: summary: Template with named parameters description: | Named parameters allow flexible ordering and clearer intent. Use `parameter_name` field to specify which variable to fill. value: messaging_product: whatsapp to: '15551234567' type: template template: name: order_confirmation language: code: en_US components: - type: body parameters: - type: text parameter_name: first_name text: Jessica - type: text parameter_name: order_number text: SKBUP2-4CPIG9 template_positional_params: summary: Template with positional parameters description: > Positional parameters must appear in order ({{1}}, {{2}}, etc.). Order matters - first param fills {{1}}, second fills {{2}}. value: messaging_product: whatsapp to: '15551234567' type: template template: name: order_confirmation language: code: en_US components: - type: body parameters: - type: text text: Jessica - type: text text: SKBUP2-4CPIG9 template_with_media_header: summary: Template with image header and named params description: | Headers can include media (image/video/document). Use media ID from upload endpoint or public URL. value: messaging_product: whatsapp to: '15551234567' type: template template: name: seasonal_promotion language: code: en_US components: - type: header parameters: - type: image image: link: https://example.com/summer-sale.jpg - type: body parameters: - type: text parameter_name: sale_name text: Summer Sale - type: text parameter_name: discount_code text: SUMMER25 - type: text parameter_name: discount_amount text: 25% template_with_header_footer: summary: Template with text header and footer description: | Text headers support 1 parameter (named or positional). Footers are static text defined in template. value: messaging_product: whatsapp to: '15551234567' type: template template: name: seasonal_promotion language: code: en_US components: - type: header parameters: - type: text parameter_name: sale_name text: Black Friday Sale - type: body parameters: - type: text parameter_name: end_date text: November 30th - type: text parameter_name: discount_code text: BF2024 template_with_url_button: summary: Template with URL button variable description: | URL buttons can have 1 variable at the end. Use button component with sub_type URL and index. value: messaging_product: whatsapp to: '15551234567' type: template template: name: limited_time_offer language: code: en_US components: - type: body parameters: - type: text parameter_name: customer_name text: Mark - type: text parameter_name: package_name text: Premium Package - type: button sub_type: url index: '0' parameters: - type: text text: summer2024 template_with_quick_reply: summary: Template with quick reply buttons description: | Quick reply buttons use payload parameter. Index determines button order (0-based). value: messaging_product: whatsapp to: '15551234567' type: template template: name: customer_feedback language: code: en_US components: - type: body parameters: - type: text parameter_name: customer_name text: Sarah - type: button sub_type: quick_reply index: '0' parameters: - type: payload payload: yes_helpful - type: button sub_type: quick_reply index: '1' parameters: - type: payload payload: no_not_helpful template_with_flow: summary: Template with flow button description: | Flow buttons trigger WhatsApp Flows. Pass flow_token and flow_action_data as parameters. value: messaging_product: whatsapp to: '15551234567' type: template template: name: appointment_booking language: code: en_US components: - type: body parameters: - type: text parameter_name: customer_name text: Michael - type: button sub_type: flow index: '0' parameters: - type: action action: flow_token: user_session_abc123 flow_action_data: customer_id: cust_12345 preferred_date: '2024-02-15T00:00:00.000Z' interactive_button: summary: Send interactive button message value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: button body: text: Would you like to proceed with your order? action: buttons: - type: reply reply: id: btn_yes title: 'Yes' - type: reply reply: id: btn_no title: 'No' interactive_cta_url: summary: Interactive CTA URL button description: |- Send a call-to-action button that opens a URL. Useful for obscuring long tracking URLs. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: cta_url header: type: text text: New workshop dates announced! body: text: Tap the button below to see available dates. footer: text: Dates subject to change action: name: cta_url parameters: display_text: See Dates url: https://example.com/workshops?utm_source=whatsapp interactive_carousel_url: summary: Interactive carousel with URL buttons description: >- Send a free-form media carousel with 2-10 cards. Each card includes an image or video header and a CTA URL button. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: carousel body: text: Choose a trip option action: cards: - card_index: 0 type: cta_url header: type: image image: link: https://example.com/flight-a.jpg body: text: Morning flight action: name: cta_url parameters: display_text: View url: https://example.com/flights/a - card_index: 1 type: cta_url header: type: image image: link: https://example.com/flight-b.jpg body: text: Evening flight action: name: cta_url parameters: display_text: View url: https://example.com/flights/b interactive_carousel_quick_reply: summary: Interactive carousel with quick replies description: |- Send a free-form media carousel where every card has the same quick-reply button structure. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: carousel body: text: Pick a product action: cards: - card_index: 0 type: cta_url header: type: image image: link: https://example.com/product-a.jpg action: buttons: - type: quick_reply quick_reply: id: product_a_yes title: Select - card_index: 1 type: cta_url header: type: image image: link: https://example.com/product-b.jpg action: buttons: - type: quick_reply quick_reply: id: product_b_yes title: Select interactive_list: summary: Interactive list message description: |- Send a list picker with sections and rows. Maximum 10 sections, 10 total rows across all sections. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: list header: type: text text: Choose Shipping body: text: Which shipping option do you prefer? footer: text: Shipping estimates may vary action: button: View Options sections: - title: Fast Shipping rows: - id: express title: Express description: 1-2 days - id: priority title: Priority description: 2-3 days - title: Standard Shipping rows: - id: standard title: Standard description: 5-7 days interactive_location_request: summary: Request user's location description: |- Request the user to share their current location. Displays a "Send Location" button. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: location_request_message body: text: >- Please share your location so we can provide accurate delivery estimates. action: name: send_location interactive_request_contact_info: summary: Request user's phone number description: Ask a user to share their WhatsApp phone number in-thread. value: messaging_product: whatsapp recipient_type: individual recipient: US.13491208655302741918 type: interactive interactive: type: request_contact_info body: text: >- Please share your phone number so we can finish your request. action: name: request_contact_info interactive_address_message: summary: Request address (India only) description: >- Request a structured address from user. IMPORTANT: Address messages are only available for businesses based in India and their India customers. The `country` parameter must be "IN". Can include pre-filled values and saved addresses. value: messaging_product: whatsapp to: '919876543210' type: interactive interactive: type: address_message body: text: Please provide your delivery address. action: name: address_message parameters: country: IN values: name: John Doe phone_number: '+919876543210' saved_addresses: - id: home value: name: John Doe phone_number: '+919876543210' in_pin_code: '400063' floor_number: '8' building_name: Acme Tower address: MG Road landmark_area: Near Metro city: Mumbai interactive_address_validation_error: summary: Address validation error (India) description: |- Re-send address request with validation errors. User sees their previous input with error messages. value: messaging_product: whatsapp to: '919876543210' type: interactive interactive: type: address_message body: text: Please correct the errors in your address. action: name: address_message parameters: country: IN values: name: John Doe phone_number: '+919876543210' in_pin_code: '999999' address: Some Street city: Mumbai validation_errors: in_pin_code: Invalid PIN code. Please check and try again. interactive_flow: summary: WhatsApp Flow message description: |- Send a WhatsApp Flow to collect structured data. Requires pre-created Flow in WhatsApp Manager. value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: flow header: type: text text: Appointment Booking body: text: Book your appointment using our interactive form footer: text: Available slots shown in real-time action: name: flow parameters: flow_message_version: '3' flow_id: '123456789' flow_cta: Book Now mode: published flow_token: AQAAAAACS5FpgQ_cAAAAAD0QI3s. flow_action: navigate flow_action_payload: screen: BOOKING_SCREEN data: service_type: consultation preferred_date: '2024-02-15T00:00:00.000Z' call_permission_request: summary: Call permission request value: messaging_product: whatsapp recipient_type: individual to: '15551234567' type: interactive interactive: type: call_permission_request action: name: call_permission_request body: text: We would like to call you to help with your order. interactive_product: summary: Single product message value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: product body: text: Optional body text action: catalog_id: CATALOG_ID product_retailer_id: SKU_1234 interactive_product_list: summary: Multi-product message value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: product_list header: type: text text: Our bestsellers body: text: Choose a product footer: text: While supplies last action: catalog_id: CATALOG_ID sections: - title: Popular product_items: - product_retailer_id: SKU_1234 - product_retailer_id: SKU_2345 interactive_catalog_message: summary: Browse catalog value: messaging_product: whatsapp to: '15551234567' type: interactive interactive: type: catalog_message body: text: Browse our catalog on WhatsApp. action: name: catalog_message parameters: thumbnail_product_retailer_id: SKU_THUMBNAIL reply_message: summary: Reply to a message value: messaging_product: whatsapp to: '15551234567' type: text context: message_id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== text: body: Thank you for your message! I'll get back to you soon. document_message: summary: Send document with caption description: |- Send a PDF, Word, Excel, or other document file. Supports various document formats up to 100MB. value: messaging_product: whatsapp to: '15551234567' type: document document: id: '1376223850470843' filename: invoice_2024.pdf caption: Your invoice for January 2024 video_message: summary: Send video with caption description: |- Send a video file (3GP or MP4). H.264 video codec and AAC audio codec required. Maximum 16MB. value: messaging_product: whatsapp to: '15551234567' type: video video: id: '1166846181421424' caption: Product demonstration video sticker_message: summary: Send sticker description: |- Send animated or static sticker (WEBP format). Static: 100KB max, Animated: 500KB max. value: messaging_product: whatsapp to: '15551234567' type: sticker sticker: id: '798882015472548' location_message: summary: Send location description: Send a location with coordinates, name, and address. value: messaging_product: whatsapp to: '15551234567' type: location location: latitude: '37.7749' longitude: '-122.4194' name: San Francisco Office address: 123 Market St, San Francisco, CA 94103 reaction_message: summary: React to a message description: >- Send an emoji reaction to a previous message. LIMITATION: Reaction messages only trigger a 'sent' status webhook. Delivered and read webhooks are NOT triggered for reaction messages. value: messaging_product: whatsapp to: '15551234567' type: reaction reaction: message_id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== emoji: 👍 contacts_message: summary: Send contact card description: >- Send rich contact information with addresses, phones, emails, and more. WARNING: While the API supports up to 257 contacts per message, sending many contacts may result in negative user feedback. Consider sending fewer contacts for better UX. value: messaging_product: whatsapp to: '15551234567' type: contacts contacts: - addresses: - street: 1 Lucky Shrub Way city: Menlo Park state: CA zip: '94025' country: United States country_code: US type: Office birthday: '1999-01-23T00:00:00.000Z' emails: - email: bjohnson@luckyshrub.com type: Work name: formatted_name: Barbara J. Johnson first_name: Barbara last_name: Johnson middle_name: Joana suffix: Esq. prefix: Dr. org: company: Lucky Shrub department: Legal title: Lead Counsel phones: - phone: '+16505559999' type: Landline - phone: '+19175559999' type: Mobile wa_id: '19175559999' urls: - url: https://www.luckyshrub.com type: Company mark_read_with_typing: summary: Mark message as read and show typing value: messaging_product: whatsapp status: read message_id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== typing_indicator: type: text responses: '200': description: Message sent successfully content: application/json: schema: $ref: '#/components/schemas/SendMessageResponse' examples: success: summary: Successful send value: messaging_product: whatsapp contacts: - input: '15551234567' wa_id: '15551234567' messages: - id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== bsuid_success: summary: Successful BSUID send value: messaging_product: whatsapp contacts: - input: US.13491208655302741918 user_id: US.13491208655302741918 messages: - id: >- wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdCMDEyOTcxQzFFQkFBAA== '400': description: Bad request (invalid message format or parameters) content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_phone: summary: Invalid phone number value: error: message: Invalid phone number format type: OAuthException code: 400 error_subcode: 1001 '401': description: Unauthorized (invalid or missing API key) content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Project has insufficient Kapso credits for Meta messaging fees content: application/json: schema: type: object required: - error - code - billing_url properties: error: type: string description: Human-readable error message code: type: string enum: - insufficient_credits billing_url: type: string format: uri description: Kapso billing page where credits can be added example: error: Your Kapso balance doesn't cover Meta's fee for this message. code: insufficient_credits billing_url: >- https://app.kapso.ai/projects/00000000-0000-0000-0000-000000000000/billing '404': description: Phone number not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict - Another message is already being sent to this recipient content: application/json: schema: $ref: '#/components/schemas/Error' examples: message_in_flight: summary: Message already in-flight description: >- A message is currently being sent to this recipient. Wait and retry. value: error: >- Another message is already in-flight for this conversation. Please retry shortly. '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Error' examples: window_expired: summary: 24-hour window expired description: Cannot send non-template messages outside the 24-hour window value: error: message: >- Cannot send non-template messages outside the 24-hour window. type: MessageError code: 131047 error_subcode: 131047 fbtrace_id: AXk7s_8dR4eVHp9Kq2MmNlO address_not_supported: summary: Address message not supported description: |- Client does not support address_message feature. Message is silently dropped. value: error: message: Receiver Incapable type: MessageError code: 1026 error_subcode: 1026 href: >- https://developers.facebook.com/docs/whatsapp/api/errors/ components: schemas: WhatsappMessage: type: object required: - messaging_product - type anyOf: - required: - to - required: - recipient properties: messaging_product: type: string enum: - whatsapp description: Always "whatsapp" example: whatsapp recipient_type: type: string enum: - individual - group default: individual description: >- Recipient type. Use `individual` for 1:1, `group` for group messages. When `group`, `to` must be a Group ID obtained via the Groups API. biz_opaque_callback_data: type: string maxLength: 512 description: Arbitrary string for tracking (echoed in webhooks) to: type: string description: Recipient phone number or group ID. Use `recipient` for BSUID sends. example: '15551234567' recipient: type: string description: >- Recipient BSUID or parent BSUID. If `to` is also present, the phone number in `to` takes precedence. example: US.13491208655302741918 type: $ref: '#/components/schemas/MessageType' context: type: object description: Reply context properties: message_id: type: string description: ID of message being replied to example: wamid.HBgNMTU1NTE... 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/MediaMessage' location: $ref: '#/components/schemas/LocationMessage' contacts: type: array items: $ref: '#/components/schemas/ContactCard' interactive: $ref: '#/components/schemas/InteractiveMessage' template: $ref: '#/components/schemas/TemplateMessage' reaction: $ref: '#/components/schemas/ReactionMessage' MarkReadRequest: type: object required: - messaging_product - status - message_id properties: messaging_product: type: string enum: - whatsapp status: type: string enum: - read message_id: type: string description: WhatsApp message ID to mark as read typing_indicator: type: object description: >- Optional typing indicator to display while preparing a reply (dismissed on send or after ~25s) properties: type: type: string enum: - text description: Typing indicator type (currently only "text") SendMessageResponse: type: object required: - messaging_product - contacts - messages properties: messaging_product: type: string enum: - whatsapp example: whatsapp contacts: type: array items: type: object properties: input: type: string description: Input phone number, BSUID, or parent BSUID example: '15551234567' wa_id: type: string nullable: true description: >- WhatsApp phone number when the message was sent to a phone number example: '15551234567' user_id: type: string nullable: true description: BSUID or parent BSUID when the message was sent to `recipient` example: US.13491208655302741918 messages: type: array items: type: object required: - id properties: id: type: string description: Message ID example: wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA== message_status: type: string enum: - accepted - held_for_quality_assessment description: Message pacing status when applicable 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 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 InteractiveMessage: type: object required: - type - action properties: type: type: string enum: - button - list - flow - cta_url - carousel - location_request_message - request_contact_info - address_message - product - product_list - call_permission_request - catalog_message description: |- Interactive message type: - button: Reply buttons (up to 3) - list: List picker (up to 10 rows across sections) - flow: WhatsApp Flow integration - cta_url: Call-to-action URL button - carousel: Free-form media carousel with 2-10 cards - location_request_message: Request user's location - request_contact_info: Request user's phone number and contact info - address_message: Address collection (India only) - product: Single product message - product_list: Multi-product message (up to 30 products) - call_permission_request: Request permission to call - catalog_message: Browse full catalog body: type: object description: >- Message body text. Required for all types except location_request_message (where it's optional). required: - text properties: text: type: string description: Body text (supports URLs and markdown) maxLength: 1024 example: Please select an option header: type: object properties: type: type: string enum: - text - image - video - document text: type: string maxLength: 60 image: $ref: '#/components/schemas/MediaMessage' video: $ref: '#/components/schemas/MediaMessage' document: $ref: '#/components/schemas/MediaMessage' footer: type: object properties: text: type: string description: Footer text maxLength: 60 example: Powered by Kapso action: type: object description: >- Action definition. Structure varies by interactive type. NOTE: The structure of the action object varies by type: - type=button: Requires `buttons` array - type=list: Requires `button` (string) and `sections` array - type=flow: Requires `name="flow"` and `parameters` with flow config - type=cta_url: Requires `name="cta_url"` and `parameters` with display_text and url - type=carousel: Requires `cards` array with 2-10 media cards. Top-level header/footer are not supported. - type=location_request_message: Requires `name="send_location"` - type=request_contact_info: Requires `name="request_contact_info"` - type=address_message: Requires `name="address_message"` and `parameters` with country properties: buttons: type: array description: |- Reply buttons (for type=button). Minimum 1, maximum 3 buttons. maxItems: 3 items: type: object required: - type - reply properties: type: type: string enum: - reply reply: type: object required: - id - title properties: id: type: string description: Unique button identifier maxLength: 256 example: button_1 title: type: string description: Button label text maxLength: 20 example: 'Yes' button: type: string description: |- Button label for list picker (for type=list). When tapped, displays the list modal. maxLength: 20 example: View Options sections: type: array description: |- List sections (for type=list). Maximum 10 sections, maximum 10 rows total across all sections. maxItems: 10 items: type: object required: - rows properties: title: type: string description: Section title maxLength: 24 example: Popular Items rows: type: array description: Rows within this section items: type: object required: - id - title properties: id: type: string description: Unique row identifier (returned in webhook) maxLength: 200 example: row_1 title: type: string description: Row title maxLength: 24 example: Option 1 description: type: string description: Row description maxLength: 72 example: This is option 1 cards: type: array minItems: 2 maxItems: 10 description: >- Carousel cards (for type=carousel). Each card must include a media header with image or video and all cards must use the same button structure: either one CTA URL button per card, or the same number of quick-reply buttons per card. items: type: object required: - card_index - header - action properties: card_index: type: integer minimum: 0 description: Zero-based card index. Values should be sequential. type: type: string description: Meta examples use `cta_url` for carousel cards. example: cta_url header: type: object required: - type properties: type: type: string enum: - image - video image: $ref: '#/components/schemas/MediaMessage' video: $ref: '#/components/schemas/MediaMessage' body: type: object properties: text: type: string maxLength: 160 description: Optional card body text. Maximum 2 line breaks. action: type: object properties: name: type: string enum: - cta_url parameters: type: object properties: display_text: type: string maxLength: 20 url: type: string format: uri buttons: type: array items: type: object required: - type - quick_reply properties: type: type: string enum: - quick_reply quick_reply: type: object required: - id - title properties: id: type: string maxLength: 256 title: type: string maxLength: 20 name: type: string description: |- Action name. - "cta_url" for CTA URL buttons - "send_location" for location requests - "request_contact_info" for phone number/contact info requests - "address_message" for address collection - "flow" for WhatsApp Flows - "call_permission_request" for call permission request - "catalog_message" for catalog browse enum: - cta_url - send_location - request_contact_info - address_message - flow - call_permission_request - catalog_message example: cta_url parameters: type: object description: Parameters object (structure varies by action name). properties: display_text: type: string description: Button label text (for cta_url) maxLength: 20 example: Visit Website url: type: string format: uri description: URL to open (for cta_url) example: https://example.com/product?id=123 country: type: string description: |- Country code (for address_message). Currently only "IN" (India) is supported. example: IN values: type: object description: Pre-filled address values (for address_message) properties: name: type: string example: John Doe phone_number: type: string example: '+919876543210' in_pin_code: type: string maxLength: 6 example: '400063' house_number: type: string example: '123' floor_number: type: string example: '5' tower_number: type: string example: A building_name: type: string example: Acme Apartments address: type: string example: MG Road landmark_area: type: string example: Near Station city: type: string example: Mumbai state: type: string example: Maharashtra saved_addresses: type: array description: >- Previously saved addresses for selection (for address_message) items: type: object required: - id - value properties: id: type: string example: addr_1 value: type: object description: Address details (same structure as values object) additionalProperties: true validation_errors: type: object description: Field validation errors to display (for address_message) additionalProperties: type: string example: in_pin_code: Invalid PIN code flow_message_version: type: string description: Flow message version (for flow). Must be "3". example: '3' flow_id: type: string description: WhatsApp Flow ID (for flow). Cannot use with flow_name. example: '123456789' flow_name: type: string description: Flow name (for flow). Cannot use with flow_id. example: Product Survey flow_cta: type: string description: Flow CTA button text (for flow) maxLength: 30 example: Take Survey mode: type: string enum: - draft - published description: Flow mode (for flow, defaults to published if omitted) flow_token: type: string description: Flow token for identification (for flow) example: AQAAAAACS5FpgQ_cAAAAAD0QI3s. flow_action: type: string enum: - navigate - data_exchange description: Flow action type (for flow, defaults to navigate if omitted) flow_action_payload: type: object description: Flow action payload (for flow) properties: screen: type: string description: First screen ID example: WELCOME_SCREEN data: type: object description: Initial data for first screen additionalProperties: true catalog_id: type: string description: Catalog ID (for product/product_list) product_retailer_id: type: string description: Product ID in the catalog (for product) sections: type: array description: >- Sections for multi-product messages (product_list). Up to 10 sections. Global limit: ≤ 30 products across all sections. items: type: object required: - title - product_items properties: title: type: string maxLength: 24 product_items: type: array items: type: object required: - product_retailer_id properties: product_retailer_id: type: string thumbnail_product_retailer_id: type: string description: Thumbnail product to highlight (for catalog_message) TemplateMessage: type: object required: - name - language properties: name: type: string description: Template name example: hello_world language: type: object required: - code properties: code: type: string description: Language code example: en_US components: type: array description: Template components with parameters items: type: object 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. ````