{ "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.\n\nThis API acts as a proxy layer between your application and WhatsApp, adding:\n- Simplified authentication with project-level API keys\n- Enhanced message metadata and tracking\n- Conversation management capabilities\n- Voice call integration\n- Extended contact and template management\n\n## Base URL\n\nAll API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0`\n\n## Authentication\n\nThe API supports authentication via **X-API-Key header** (recommended):\n\n```\nX-API-Key: your_project_api_key\n```\n\nAlternative: Bearer token authentication is also supported for backward compatibility:\n\n```\nAuthorization: Bearer your_access_token\n```\n\nNote: X-API-Key is the recommended authentication method for the Meta Proxy API.\n", "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" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Project API key for authentication. This is the recommended authentication method.\n\nGet your API key from the Kapso dashboard under Integrations > API keys.\n" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token authentication (alternative method).\n\nNote: X-API-Key authentication is recommended for the Meta Proxy API.\n" } }, "schemas": { "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" } } } } }, "MarketingPreferenceStoppedError": { "type": "object", "description": "Returned when the recipient asked WhatsApp to stop marketing messages from this number. The send is refused before reaching Meta and is not charged. Do not retry — use a utility or authentication template, or another number.", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable error message", "example": "Contact stopped marketing messages on this WhatsApp number" }, "code": { "type": "string", "enum": [ "marketing_preference_stopped" ] } } }, "PaginationCursor": { "type": "object", "properties": { "before": { "type": "string", "description": "Cursor for previous page (Base64 encoded)", "example": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" }, "after": { "type": "string", "description": "Cursor for next page (Base64 encoded)", "example": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } }, "Paging": { "type": "object", "properties": { "cursors": { "$ref": "#/components/schemas/PaginationCursor" } } }, "WhatsappContact": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Contact ID (UUID)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "wa_id": { "type": "string", "nullable": true, "description": "WhatsApp ID (phone number). Can be null when Meta only provides BSUID-based identity.", "example": "15551234567" }, "business_scoped_user_id": { "type": "string", "nullable": true, "description": "WhatsApp business-scoped user ID", "example": "US.13491208655302741918" }, "parent_business_scoped_user_id": { "type": "string", "nullable": true, "description": "Parent business-scoped user ID when provided by Meta", "example": "US.ENT.506847293015824" }, "username": { "type": "string", "nullable": true, "description": "WhatsApp username when available", "example": "@testusername" }, "profile_name": { "type": "string", "description": "WhatsApp profile name", "example": "John Doe" }, "display_name": { "type": "string", "description": "Custom display name", "example": "John (VIP Customer)" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "description": "Contact creation timestamp", "example": "2024-01-15 12:34:56 UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-01-15 12:34:56 UTC" } } }, "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).\nRecommended over `link` for better performance.", "example": "abc123def456" }, "link": { "type": "string", "format": "uri", "description": "Public URL to media file (hosted media).\nUsing uploaded media with `id` is recommended for better performance.", "example": "https://example.com/image.jpg" }, "caption": { "type": "string", "description": "Media caption text.\n- Images: max 1024 characters\n- Videos: max 1024 characters\n- Documents: max 1024 characters\n\nNot supported for stickers or audio.", "maxLength": 1024, "example": "Check out this photo!" }, "filename": { "type": "string", "description": "Filename with extension (for documents only).\nWhatsApp 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).\nUsing 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).\nVoice messages must be .ogg files encoded with OPUS codec.\nSet to `false` or omit for basic audio messages.\n\nVoice messages include: automatic download, profile picture, voice icon, and optional transcription.\nBasic 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 } } }, "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" } } }, "SupportedDocumentFormats": { "description": "Supported document formats for document messages.\n\n| Format | Extension | MIME Type | Max Size |\n|--------|-----------|-----------|----------|\n| Text | .txt | text/plain | 100 MB |\n| Microsoft Excel | .xls | application/vnd.ms-excel | 100 MB |\n| Microsoft Excel | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | 100 MB |\n| Microsoft Word | .doc | application/msword | 100 MB |\n| Microsoft Word | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | 100 MB |\n| Microsoft PowerPoint | .ppt | application/vnd.ms-powerpoint | 100 MB |\n| Microsoft PowerPoint | .pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation | 100 MB |\n| PDF | .pdf | application/pdf | 100 MB |", "type": "object" }, "SupportedImageFormats": { "description": "Supported image formats for image messages.\nImages must be 8-bit, RGB or RGBA.\n\n| Format | Extension | MIME Type | Max Size |\n|--------|-----------|-----------|----------|\n| JPEG | .jpeg, .jpg | image/jpeg | 5 MB |\n| PNG | .png | image/png | 5 MB |", "type": "object" }, "SupportedVideoFormats": { "description": "Supported video formats for video messages.\nOnly H.264 video codec and AAC audio codec supported.\nSingle audio stream or no audio stream only.\n\n| Format | Extension | MIME Type | Max Size |\n|--------|-----------|-----------|----------|\n| 3GPP | .3gp | video/3gpp | 16 MB |\n| MP4 | .mp4 | video/mp4 | 16 MB |", "type": "object" }, "SupportedAudioFormats": { "description": "Supported audio formats for audio messages.\nVoice messages (voice=true) require .ogg files with OPUS codec.\n\n| Format | Extension | MIME Type | Max Size |\n|--------|-----------|-----------|----------|\n| AAC | .aac | audio/aac | 16 MB |\n| AMR | .amr | audio/amr | 16 MB |\n| MP3 | .mp3 | audio/mpeg | 16 MB |\n| MP4 Audio | .m4a | audio/mp4 | 16 MB |\n| OGG Audio | .ogg | audio/ogg (OPUS codec only) | 16 MB |", "type": "object" }, "SupportedStickerFormats": { "description": "Supported sticker formats for sticker messages.\n\n| Type | Extension | MIME Type | Max Size |\n|------|-----------|-----------|----------|\n| Static | .webp | image/webp | 100 KB |\n| Animated | .webp | image/webp | 500 KB |", "type": "object" }, "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-23" }, "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.\nIf 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", "order_details", "order_status", "product", "product_list", "call_permission_request", "catalog_message" ], "description": "Interactive message type:\n- button: Reply buttons (up to 3)\n- list: List picker (up to 10 rows across sections)\n- flow: WhatsApp Flow integration\n- cta_url: Call-to-action URL button\n- carousel: Free-form media carousel with 2-10 cards\n- location_request_message: Request user's location\n- request_contact_info: Request user's phone number and contact info\n- address_message: Address collection (India only)\n- order_details: Order for the user to review and pay (Brazil Pix)\n- order_status: Status update for a previously sent order\n- product: Single product message\n- product_list: Multi-product message (up to 30 products)\n- call_permission_request: Request permission to call\n- catalog_message: Browse full catalog" }, "body": { "type": "object", "description": "Message body text.\nRequired 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.\n\nNOTE: The structure of the action object varies by type:\n- type=button: Requires `buttons` array\n- type=list: Requires `button` (string) and `sections` array\n- type=flow: Requires `name=\"flow\"` and `parameters` with flow config\n- type=cta_url: Requires `name=\"cta_url\"` and `parameters` with display_text and url\n- type=carousel: Requires `cards` array with 2-10 media cards. Top-level header/footer are not supported.\n- type=location_request_message: Requires `name=\"send_location\"`\n- type=request_contact_info: Requires `name=\"request_contact_info\"`\n- type=address_message: Requires `name=\"address_message\"` and `parameters` with country\n- type=order_details: Requires `name=\"review_and_pay\"` and a `parameters` object\n- type=order_status: Requires `name=\"review_order\"` and a `parameters` object", "properties": { "buttons": { "type": "array", "description": "Reply buttons (for type=button).\nMinimum 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": true } } } } } }, "button": { "type": "string", "description": "Button label for list picker (for type=list).\nWhen tapped, displays the list modal.", "maxLength": 20, "example": "View Options" }, "sections": { "type": "array", "description": "List sections (for type=list).\nMaximum 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\nwith image or video and all cards must use the same button structure:\neither one CTA URL button per card, or the same number of quick-reply\nbuttons 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.\n- \"cta_url\" for CTA URL buttons\n- \"send_location\" for location requests\n- \"request_contact_info\" for phone number/contact info requests\n- \"address_message\" for address collection\n- \"flow\" for WhatsApp Flows\n- \"call_permission_request\" for call permission request\n- \"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).\nCurrently 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": "👍" } } }, "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.\nWhen `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" } } }, "MarketingMessage": { "type": "object", "required": [ "messaging_product", "type", "template" ], "anyOf": [ { "required": [ "to" ] }, { "required": [ "recipient" ] } ], "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "description": "Always \"whatsapp\"", "example": "whatsapp" }, "recipient_type": { "type": "string", "enum": [ "individual" ], "default": "individual", "description": "Marketing messages are sent to individual recipients." }, "biz_opaque_callback_data": { "type": "string", "maxLength": 512, "description": "Arbitrary string for tracking (echoed in webhooks)" }, "to": { "type": "string", "description": "Recipient phone number. 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": { "type": "string", "enum": [ "template" ], "description": "Marketing messages must use a WhatsApp template.", "example": "template" }, "template": { "$ref": "#/components/schemas/TemplateMessage" } } }, "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\")" } } } } }, "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:\n- button_reply: Reply button was tapped\n- list_reply: List item was selected\n- 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": true } } }, "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" } } } } }, "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" } } } } } }, "WhatsappConversation": { "type": "object", "required": [ "id", "status", "last_active_at", "created_at", "updated_at", "whatsapp_config_id", "phone_number_id" ], "properties": { "id": { "type": "string", "description": "Conversation ID (UUID)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "phone_number": { "type": "string", "nullable": true, "description": "Contact's phone number (normalized). Can be null for BSUID-only identity.", "example": "15551234567" }, "business_scoped_user_id": { "type": "string", "nullable": true, "description": "WhatsApp business-scoped user ID", "example": "US.13491208655302741918" }, "parent_business_scoped_user_id": { "type": "string", "nullable": true, "description": "Parent business-scoped user ID when provided by Meta", "example": "US.ENT.506847293015824" }, "username": { "type": "string", "nullable": true, "description": "WhatsApp username when available", "example": "@testusername" }, "status": { "type": "string", "enum": [ "active", "ended" ], "description": "Conversation status", "example": "active" }, "last_active_at": { "type": "string", "format": "date-time", "description": "Last activity timestamp", "example": "2024-01-15 14:30:00 UTC" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2024-01-15 10:00:00 UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-01-15 14:30:00 UTC" }, "whatsapp_config_id": { "type": "string", "description": "WhatsApp configuration ID (UUID)", "example": "456e7890-a12b-34c5-d678-901234567890" }, "metadata": { "type": "object", "description": "Custom metadata", "nullable": true, "additionalProperties": true }, "phone_number_id": { "type": "string", "description": "WhatsApp Business Phone Number ID", "example": "110987654321" }, "kapso": { "type": "object", "description": "Kapso-specific conversation metadata", "properties": { "contact_name": { "type": "string", "nullable": true, "description": "Contact display name", "example": "John Doe" }, "messages_count": { "type": "integer", "description": "Total message count in conversation", "example": 15 }, "last_message_id": { "type": "string", "nullable": true, "description": "WhatsApp message ID of last message", "example": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==" }, "last_message_type": { "type": "string", "nullable": true, "description": "Type of last message", "example": "text" }, "last_message_timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of last message (ISO 8601)", "example": "2024-01-15 14:30:00 UTC" }, "last_message_text": { "type": "string", "nullable": true, "description": "Text content of last message (if text message)", "example": "Hello! I need help with my order" }, "last_inbound_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of last inbound message (ISO 8601)", "example": "2024-01-15 14:30:00 UTC" }, "last_outbound_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of last outbound message (ISO 8601)", "example": "2024-01-15 14:25:00 UTC" } } } } }, "WhatsappCall": { "type": "object", "required": [ "id", "project_id", "whatsapp_config_id", "phone_number_id" ], "properties": { "id": { "type": "string", "description": "Call ID (UUID)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "call_id": { "type": "string", "description": "WhatsApp call ID", "example": "call_abc123" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Call direction", "example": "inbound" }, "status": { "type": "string", "enum": [ "initiated", "ringing", "answered", "completed", "failed" ], "description": "Call status", "example": "completed" }, "duration_seconds": { "type": "integer", "nullable": true, "description": "Call duration in seconds", "example": 180 }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Call start time", "example": "2024-01-15 12:34:56 UTC" }, "ended_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Call end time", "example": "2024-01-15 12:37:56 UTC" }, "session_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Session start time", "example": "2024-01-15 12:34:58 UTC" }, "created_at": { "type": "string", "format": "date-time", "description": "Record creation timestamp", "example": "2024-01-15 12:34:56 UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "Record update timestamp", "example": "2024-01-15 12:37:56 UTC" }, "user_wa_id": { "type": "string", "nullable": true, "description": "User's WhatsApp ID (phone number) when available", "example": "15551234567" }, "business_scoped_user_id": { "type": "string", "nullable": true, "description": "User business-scoped user ID when available", "example": "US.13491208655302741918" }, "parent_business_scoped_user_id": { "type": "string", "nullable": true, "description": "User parent business-scoped user ID when available", "example": "US.ENT.506847293015824" }, "username": { "type": "string", "nullable": true, "description": "WhatsApp username when available", "example": "@testusername" }, "whatsapp_contact_id": { "type": "string", "nullable": true, "description": "Associated contact ID (UUID)", "example": "223e4567-e89b-12d3-a456-426614174001" }, "whatsapp_conversation_id": { "type": "string", "nullable": true, "description": "Associated conversation ID (UUID)", "example": "323e4567-e89b-12d3-a456-426614174002" }, "project_id": { "type": "string", "description": "Project ID (UUID)", "example": "423e4567-e89b-12d3-a456-426614174003" }, "whatsapp_config_id": { "type": "string", "description": "WhatsApp configuration ID (UUID)", "example": "523e4567-e89b-12d3-a456-426614174004" }, "config_display_name": { "type": "string", "nullable": true, "description": "Configuration display name", "example": "Support Line" }, "config_display_phone_number": { "type": "string", "nullable": true, "description": "Configuration display phone number", "example": "+1 (555) 123-4567" }, "phone_number_id": { "type": "string", "description": "WhatsApp Business Phone Number ID", "example": "110987654321" }, "whatsapp_contact": { "type": "object", "nullable": true, "description": "Associated contact (basic view)", "properties": { "id": { "type": "string" }, "wa_id": { "type": "string" }, "profile_name": { "type": "string" }, "display_name": { "type": "string" } } }, "whatsapp_conversation": { "type": "object", "nullable": true, "description": "Associated conversation (basic view)", "properties": { "id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "last_active_at": { "type": "string", "format": "date-time" } } } } }, "FlowSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED", "BLOCKED", "THROTTLED" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/FlowValidationError" } } } }, "FlowValidationError": { "type": "object", "properties": { "error": { "type": "string" }, "error_type": { "type": "string" }, "message": { "type": "string" }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } }, "FlowCreateRequest": { "type": "object", "required": [ "name", "categories" ], "properties": { "name": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER" ] } }, "clone_flow_id": { "type": "string" }, "endpoint_uri": { "type": "string", "format": "uri" }, "flow_json": { "type": "string" }, "publish": { "type": "boolean" } } }, "FlowCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "success": { "type": "boolean" }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/FlowValidationError" } } } }, "PhoneNumberSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Phone number ID" }, "verified_name": { "type": "string", "description": "Verified business name associated with the phone number" }, "display_phone_number": { "type": "string", "description": "Phone number in international format" }, "quality_rating": { "type": "string", "enum": [ "GREEN", "YELLOW", "RED", "NA", "UNKNOWN" ], "description": "Quality rating based on message delivery.\n- GREEN: High quality\n- YELLOW: Medium quality\n- RED: Low quality\n- NA: Not yet determined\n- UNKNOWN: Status unknown\n" }, "code_verification_status": { "type": "string", "description": "Verification status of the phone number" }, "is_official_business_account": { "type": "boolean", "description": "Whether this is an official business account" }, "name_status": { "type": "string", "description": "Status of the business name" }, "new_name_status": { "type": "string", "description": "Status of pending name change" }, "platform_type": { "type": "string", "description": "Platform type (CLOUD_API, etc.)" }, "throughput": { "type": "object", "description": "Messaging throughput limits" }, "account_mode": { "type": "string", "enum": [ "SANDBOX", "LIVE" ], "description": "Account mode" }, "certificate": { "type": "string", "description": "Certificate status" }, "messaging_limit_tier": { "type": "string", "description": "Current messaging limit tier" } } }, "BusinessVertical": { "type": "string", "enum": [ "ALCOHOL", "APPAREL", "AUTO", "BEAUTY", "EDU", "ENTERTAIN", "EVENT_PLAN", "FINANCE", "GOVT", "GROCERY", "HEALTH", "HOTEL", "NONPROFIT", "ONLINE_GAMBLING", "OTC_DRUGS", "OTHER", "PHYSICAL_GAMBLING", "PROF_SERVICES", "RESTAURANT", "RETAIL", "TRAVEL" ], "description": "Business category displayed in WhatsApp profile:\n- ALCOHOL: Alcoholic Beverages\n- APPAREL: Clothing and Apparel\n- AUTO: Automotive\n- BEAUTY: Beauty, Spa and Salon\n- EDU: Education\n- ENTERTAIN: Entertainment\n- EVENT_PLAN: Event Planning and Service\n- FINANCE: Finance and Banking\n- GOVT: Public Service\n- GROCERY: Food and Grocery\n- HEALTH: Medical and Health\n- HOTEL: Hotel and Lodging\n- NONPROFIT: Non-profit\n- ONLINE_GAMBLING: Online Gambling & Gaming\n- OTC_DRUGS: Over-the-Counter Drugs\n- OTHER: Other\n- PHYSICAL_GAMBLING: Non-Online Gambling & Gaming\n- PROF_SERVICES: Professional Services\n- RESTAURANT: Restaurant\n- RETAIL: Shopping and Retail\n- TRAVEL: Travel and Transportation\n" }, "BusinessProfileUpdate": { "type": "object", "required": [ "messaging_product" ], "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "description": "Always \"whatsapp\"", "example": "whatsapp" }, "about": { "type": "string", "minLength": 1, "maxLength": 139, "description": "Business About text (appears in profile beneath image and contact buttons).\n- Must be 1-139 characters\n- Rendered emojis supported (unicode values must be encoded)\n- Hyperlinks included but won't render as clickable\n- Markdown not supported\n", "example": "Welcome to our store! We're here to help you 24/7." }, "address": { "type": "string", "maxLength": 256, "description": "Business address (max 256 characters)", "example": "123 Main Street, San Francisco, CA 94102" }, "description": { "type": "string", "maxLength": 512, "description": "Business description (max 512 characters)", "example": "Leading provider of premium products and services since 2010. We pride ourselves on exceptional customer service and quality." }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "Contact email address (max 128 characters)", "example": "support@example.com" }, "profile_picture_handle": { "type": "string", "description": "Handle from resumable upload API for profile picture", "example": "h:resumable-upload-handle-abc123xyz789" }, "vertical": { "$ref": "#/components/schemas/BusinessVertical" }, "websites": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "uri", "maxLength": 256 }, "description": "URLs associated with business (max 2, 256 chars each, must include http:// or https://)", "example": [ "https://www.example.com", "https://www.instagram.com/example" ] } } }, "BusinessProfileUpdateResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the update succeeded", "example": true } } } } }, "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" } ], "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "Retrieve a paginated list of WhatsApp messages for a phone number.\n\nSupports filtering by conversation, direction, status, and time range.\nUses cursor-based pagination for efficient scrolling through large result sets.\n", "operationId": "listMessages", "parameters": [ { "name": "conversation_id", "in": "query", "description": "Filter by conversation ID", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "direction", "in": "query", "description": "Filter by message direction", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "example": "inbound" }, { "name": "status", "in": "query", "description": "Filter by message status", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed" ] }, "example": "delivered" }, { "name": "since", "in": "query", "description": "Filter messages created on or after this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 00:00:00 UTC" }, { "name": "until", "in": "query", "description": "Filter messages created on or before this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 23:59:59 UTC" }, { "name": "limit", "in": "query", "description": "Maximum number of results per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "before", "in": "query", "description": "Cursor for previous page (Base64 encoded)", "schema": { "type": "string" }, "example": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" }, { "name": "after", "in": "query", "description": "Cursor for next page (Base64 encoded)", "schema": { "type": "string" }, "example": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" }, { "name": "fields", "in": "query", "description": "Filter response fields. Use `kapso()` to include Kapso-specific extensions.\n\nExample: `fields=kapso(direction,status,processing_status)`\n", "schema": { "type": "string" }, "example": "kapso()" } ], "responses": { "200": { "description": "Successfully retrieved messages", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappMessageResponse" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "examples": { "inbound_text": { "summary": "Inbound text message", "description": "Basic text message from customer with core kapso fields", "value": { "data": [ { "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" } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } } }, "outbound_image": { "summary": "Outbound image with caption", "description": "Image message with media fields and type-specific data", "value": { "data": [ { "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 } } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } } }, "template_message": { "summary": "Template message", "description": "Outbound template with template-specific kapso data", "value": { "data": [ { "id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFDAA==", "timestamp": "1705328200", "type": "template", "to": "15551234567", "template": { "name": "order_confirmation", "language": { "code": "en_US" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "ORD-12345" } ] } ] }, "kapso": { "direction": "outbound", "status": "delivered", "processing_status": "completed", "phone_number": "+15551234567", "has_media": false, "whatsapp_conversation_id": "123e4567-e89b-12d3-a456-426614174000", "contact_name": "John Doe", "message_type_data": { "name": "order_confirmation", "language": { "code": "en_US" }, "params": [ "John", "ORD-12345" ] } } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } } }, "interactive_message": { "summary": "Interactive button message", "description": "Interactive message with type-specific data", "value": { "data": [ { "id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFEAA==", "timestamp": "1705328250", "type": "interactive", "to": "15551234567", "interactive": { "type": "button", "body": { "text": "Would you like to proceed with your order?" } }, "kapso": { "direction": "outbound", "status": "sent", "processing_status": "completed", "phone_number": "+15551234567", "has_media": false, "whatsapp_conversation_id": "123e4567-e89b-12d3-a456-426614174000", "contact_name": "John Doe", "message_type_data": { "type": "button", "body_text": "Would you like to proceed with your order?" } } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } } }, "location_message": { "summary": "Location share", "description": "Inbound location message with coordinates and details", "value": { "data": [ { "id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFFAA==", "timestamp": "1705328300", "type": "location", "from": "15551234567", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Warehouse Location", "address": "123 Main St, San Francisco, CA" }, "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", "message_type_data": { "latitude": 37.7749, "longitude": -122.4194, "name": "Warehouse Location", "address": "123 Main St, San Francisco, CA" } } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0=" } } } } } } } }, "400": { "description": "Bad request (invalid parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (invalid or missing API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Messages" ], "summary": "Send a message", "description": "Send a WhatsApp message to a recipient.\n\nUse `to` for phone numbers. Use `recipient` for a BSUID or parent BSUID.\nIf both are present, the phone number in `to` takes precedence.\n\nSupports all WhatsApp message types:\n- **text**: Plain text messages with optional URL preview\n- **image**: Images with optional caption\n- **video**: Videos with optional caption\n- **audio**: Audio files\n- **document**: Documents with optional caption and filename\n- **sticker**: Stickers\n- **location**: Location sharing\n- **contacts**: Contact cards\n- **interactive**: Interactive messages (buttons, lists, flows)\n- **template**: Message templates\n- **reaction**: Emoji reactions to messages\n", "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.\nIncludes 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.\nSupports 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.\nUse `parameter_name` field to specify which variable to fill.\n", "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.).\nOrder matters - first param fills {{1}}, second fills {{2}}.\n", "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).\nUse media ID from upload endpoint or public URL.\n", "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).\nFooters are static text defined in template.\n", "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.\nUse button component with sub_type URL and index.\n", "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.\nIndex determines button order (0-based).\n", "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.\nPass flow_token and flow_action_data as parameters.\n", "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-15" } } } ] } ] } } }, "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": true } }, { "type": "reply", "reply": { "id": "btn_no", "title": false } } ] } } } }, "interactive_cta_url": { "summary": "Interactive CTA URL button", "description": "Send a call-to-action button that opens a URL.\nUseful 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_order_details_pix": { "summary": "Interactive order details with dynamic Pix", "description": "Send an order for the user to review and pay with Pix.\nRequires a WhatsApp Business Account enabled for the Meta Brazil Payments API.", "value": { "messaging_product": "whatsapp", "to": "5511999999999", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Order details" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "pix-order-123", "type": "digital-goods", "payment_type": "br", "payment_settings": [ { "type": "pix_dynamic_code", "pix_dynamic_code": { "code": "00020101021226820014br.gov.bcb.pix", "merchant_name": "Kapso Merchant", "key": "12345678000199", "key_type": "CNPJ" } } ], "currency": "BRL", "total_amount": { "value": 1000, "offset": 100 }, "order": { "status": "pending", "tax": { "value": 0, "offset": 100 }, "items": [ { "retailer_id": "item-1", "name": "Subscription", "amount": { "value": 1000, "offset": 100 }, "quantity": 1 } ], "subtotal": { "value": 1000, "offset": 100 } } } } } } }, "interactive_order_status": { "summary": "Interactive order status update", "description": "Update a previously sent order using the same reference_id.", "value": { "messaging_product": "whatsapp", "to": "5511999999999", "type": "interactive", "interactive": { "type": "order_status", "body": { "text": "Payment confirmed" }, "action": { "name": "review_order", "parameters": { "reference_id": "pix-order-123", "order": { "status": "processing" }, "payment": { "status": "captured" } } } } } }, "interactive_carousel_url": { "summary": "Interactive carousel with URL buttons", "description": "Send a free-form media carousel with 2-10 cards. Each card includes\nan 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\nquick-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.\nMaximum 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.\nDisplays 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.\n\nIMPORTANT: Address messages are only available for businesses based in India\nand their India customers. The `country` parameter must be \"IN\".\n\nCan 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.\nUser 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.\nRequires 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-15" } } } } } } }, "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.\nSupports 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).\nH.264 video codec and AAC audio codec required.\nMaximum 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).\nStatic: 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.\n\nLIMITATION: Reaction messages only trigger a 'sent' status webhook.\nDelivered 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.\n\nWARNING: While the API supports up to 257 contacts per message, sending many contacts\nmay 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-23", "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": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MarketingPreferenceStoppedError" } ] }, "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.\nMessage is silently dropped.", "value": { "error": { "message": "Receiver Incapable", "type": "MessageError", "code": 1026, "error_subcode": 1026, "href": "https://developers.facebook.com/docs/whatsapp/api/errors/" } } }, "marketing_preference_stopped": { "summary": "Contact stopped marketing messages", "description": "The contact asked WhatsApp to stop marketing messages from\nthis number. Marketing template sends are refused before\nreaching Meta and are not charged. Do not retry — use a\nutility or authentication template, or another number.", "value": { "error": "Contact stopped marketing messages on this WhatsApp number", "code": "marketing_preference_stopped" } } } } } } } } }, "/{phone_number_id}/marketing_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 marketing message", "description": "Send a WhatsApp marketing template message.\n\nUse `to` for phone numbers. Use `recipient` for a BSUID or parent BSUID.\nIf both are present, the phone number in `to` takes precedence.\n", "operationId": "sendMarketingMessage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketingMessage" }, "examples": { "marketing_template_to_bsuid": { "summary": "Send marketing template to BSUID", "value": { "messaging_product": "whatsapp", "recipient_type": "individual", "recipient": "US.13491208655302741918", "type": "template", "template": { "name": "promo_template", "language": { "code": "en_US" } } } } } } } }, "responses": { "200": { "description": "Message accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" }, "examples": { "bsuid_success": { "summary": "Successful BSUID send", "value": { "messaging_product": "whatsapp", "contacts": [ { "input": "US.13491208655302741918", "user_id": "US.13491208655302741918" } ], "messages": [ { "id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdCMDEyOTcxQzFFQkFBAA==", "message_status": "accepted" } ] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MarketingPreferenceStoppedError" } ] }, "examples": { "marketing_preference_stopped": { "summary": "Contact stopped marketing messages", "description": "The contact asked WhatsApp to stop marketing messages from\nthis number. The send is refused before reaching Meta and\nis not charged. Do not retry — use a utility or\nauthentication template, or another number.", "value": { "error": "Contact stopped marketing messages on this WhatsApp number", "code": "marketing_preference_stopped" } } } } } } } } }, "/{phone_number_id}/username": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Usernames" ], "summary": "Get current username", "operationId": "getUsername", "responses": { "200": { "description": "Current username state", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Current business username. Omitted when none exists.", "example": "kapso_support" }, "status": { "type": "string", "enum": [ "approved", "reserved" ], "example": "reserved" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Usernames" ], "summary": "Claim or change username", "operationId": "setUsername", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Desired business username", "example": "kapso_support" }, "transfer_action": { "type": "string", "enum": [ "none", "force_transfer" ], "default": "none", "description": "Use `force_transfer` to move a username from another phone number in the same business portfolio." } } }, "examples": { "claim_username": { "summary": "Claim username", "value": { "username": "kapso_support", "transfer_action": "none" } } } } } }, "responses": { "200": { "description": "Username request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "reserved" ], "example": "reserved" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Usernames" ], "summary": "Delete username", "operationId": "deleteUsername", "responses": { "200": { "description": "Username deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/username_suggestions": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Usernames" ], "summary": "Get reserved username suggestions", "operationId": "getUsernameSuggestions", "responses": { "200": { "description": "Reserved username suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "username_suggestions": { "type": "array", "items": { "type": "string" }, "example": [ "kapso_support", "kapso_ai" ] } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{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.\n\nReturns the message with all its fields, including Kapso extensions like status, direction, and processing state.\n", "operationId": "getMessage", "parameters": [ { "name": "fields", "in": "query", "description": "Filter response fields. Use `kapso()` to include Kapso-specific extensions.\n\nExample: `fields=kapso(direction,status,processing_status)`\n", "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 } } } } } } } }, "/{phone_number_id}/conversations": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Retrieve a paginated list of WhatsApp conversations for a phone number.\n\nConversations are ordered by last activity (most recent first).\nSupports filtering by status, activity time range, and phone number.\n\n## Kapso Extensions\n\nThe response includes Kapso-specific conversation metadata:\n- Message counts (total and unread)\n- Associated contact information\n- Conversation status and timestamps\n", "operationId": "listConversations", "parameters": [ { "name": "status", "in": "query", "description": "Filter by conversation status", "schema": { "type": "string", "enum": [ "active", "ended" ] }, "example": "active" }, { "name": "assigned_user_id", "in": "query", "description": "Filter by active assignee user ID (must be a project member)", "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "unassigned", "in": "query", "description": "Filter conversations with no active assignment. Cannot be combined with `assigned_user_id`.", "schema": { "type": "boolean" }, "example": true }, { "name": "last_active_since", "in": "query", "description": "Filter conversations active on or after this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 00:00:00 UTC" }, { "name": "last_active_until", "in": "query", "description": "Filter conversations active on or before this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 23:59:59 UTC" }, { "name": "phone_number", "in": "query", "description": "Filter by contact phone number", "schema": { "type": "string" }, "example": "+15551234567" }, { "name": "limit", "in": "query", "description": "Maximum number of results per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "before", "in": "query", "description": "Cursor for previous page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for next page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Filter response fields. Use `kapso()` to include Kapso-specific extensions.", "schema": { "type": "string" }, "example": "kapso()" } ], "responses": { "200": { "description": "Successfully retrieved conversations", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappConversation" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "examples": { "success": { "summary": "List of conversations", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "phone_number": "15551234567", "status": "active", "last_active_at": "2024-01-15 14:30:00 UTC", "created_at": "2024-01-15 10:00:00 UTC", "updated_at": "2024-01-15 14:30:00 UTC", "whatsapp_config_id": "456e7890-a12b-34c5-d678-901234567890", "metadata": { "tags": [ "vip", "priority" ] }, "phone_number_id": "110987654321", "kapso": { "contact_name": "John Doe", "messages_count": 15, "last_message_id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==", "last_message_type": "text", "last_message_timestamp": "2024-01-15 14:30:00 UTC", "last_message_text": "Hello! I need help with my order", "last_inbound_at": "2024-01-15 14:30:00 UTC", "last_outbound_at": "2024-01-15 14:25:00 UTC" } }, { "id": "223e4567-e89b-12d3-a456-426614174001", "phone_number": "15559876543", "status": "ended", "last_active_at": "2024-01-14 12:00:00 UTC", "created_at": "2024-01-14 08:00:00 UTC", "updated_at": "2024-01-14 12:00:00 UTC", "whatsapp_config_id": "456e7890-a12b-34c5-d678-901234567890", "metadata": null, "phone_number_id": "110987654321", "kapso": { "contact_name": "Jane Smith", "messages_count": 8, "last_message_id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAB==", "last_message_type": "text", "last_message_timestamp": "2024-01-14 12:00:00 UTC", "last_message_text": "Thank you for your help!", "last_inbound_at": "2024-01-14 12:00:00 UTC", "last_outbound_at": "2024-01-14 11:58:00 UTC" } } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQxMjowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsibGFzdF9hY3RpdmVfYXQiLCJpZCJdfQ==" } } } } } } } }, "400": { "description": "Bad request (invalid parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (invalid or missing API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error (conflicting filters or invalid assignee)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/conversations/{conversation_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" }, { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "get": { "tags": [ "Conversations" ], "summary": "Get conversation details", "description": "Retrieve detailed information about a specific conversation.\n\n## Kapso Extensions\n\nThe response includes:\n- Full contact information\n- Message statistics\n- Conversation metadata\n", "operationId": "getConversation", "parameters": [ { "name": "fields", "in": "query", "description": "Filter response fields. Use `kapso()` to include Kapso-specific extensions.", "schema": { "type": "string" }, "example": "kapso()" } ], "responses": { "200": { "description": "Successfully retrieved conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConversation" }, "examples": { "success": { "summary": "Conversation details", "value": { "id": "123e4567-e89b-12d3-a456-426614174000", "phone_number": "15551234567", "status": "active", "last_active_at": "2024-01-15 14:30:00 UTC", "created_at": "2024-01-15 10:00:00 UTC", "updated_at": "2024-01-15 14:30:00 UTC", "whatsapp_config_id": "456e7890-a12b-34c5-d678-901234567890", "metadata": { "tags": [ "vip", "priority" ], "customer_tier": "premium" }, "phone_number_id": "110987654321", "kapso": { "contact_name": "John Doe", "messages_count": 15, "last_message_id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==", "last_message_type": "text", "last_message_timestamp": "2024-01-15 14:30:00 UTC", "last_message_text": "Hello! I need help with my order", "last_inbound_at": "2024-01-15 14:30:00 UTC", "last_outbound_at": "2024-01-15 14:25:00 UTC" } } } } } } }, "401": { "description": "Unauthorized (invalid or missing API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/contacts": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Retrieve a paginated list of WhatsApp contacts for your project.\n\nSupports filtering by WhatsApp ID, customer association, and more.\n", "operationId": "listContacts", "parameters": [ { "name": "wa_id", "in": "query", "description": "Filter by WhatsApp ID (phone number)", "schema": { "type": "string" }, "example": "15551234567" }, { "name": "customer_id", "in": "query", "description": "Filter by associated customer ID", "schema": { "type": "string" }, "example": "cust_abc123" }, { "name": "has_customer", "in": "query", "description": "Filter by customer association (true/false)", "schema": { "type": "boolean" }, "example": true }, { "name": "limit", "in": "query", "description": "Maximum number of results per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for previous page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for next page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Filter response fields. Use `kapso()` to include Kapso-specific extensions.", "schema": { "type": "string" }, "example": "kapso()" } ], "responses": { "200": { "description": "Successfully retrieved contacts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappContact" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "examples": { "success": { "summary": "List of contacts", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP Customer)", "metadata": { "customer_tier": "premium", "tags": [ "vip", "high-value" ] }, "created_at": "2024-01-10 08:00:00 UTC", "updated_at": "2024-01-15 12:34:56 UTC" }, { "id": "223e4567-e89b-12d3-a456-426614174001", "wa_id": "15559876543", "profile_name": "Jane Smith", "display_name": null, "metadata": null, "created_at": "2024-01-12 10:00:00 UTC", "updated_at": "2024-01-12 10:00:00 UTC" } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xMlQxMDowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/contacts/{wa_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" }, { "name": "wa_id", "in": "path", "required": true, "description": "WhatsApp ID (phone number)", "schema": { "type": "string" }, "example": "15551234567" } ], "get": { "tags": [ "Contacts" ], "summary": "Get contact details", "description": "Retrieve detailed information about a specific contact.", "operationId": "getContact", "parameters": [ { "name": "fields", "in": "query", "description": "Filter response fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContact" }, "examples": { "success": { "summary": "Contact details", "value": { "id": "123e4567-e89b-12d3-a456-426614174000", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP Customer)", "metadata": { "customer_tier": "premium", "tags": [ "vip", "high-value" ], "last_order_date": "2024-01-10" }, "created_at": "2024-01-10 08:00:00 UTC", "updated_at": "2024-01-15 12:34:56 UTC" } } } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/calls": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Calls" ], "summary": "List calls", "description": "Retrieve a paginated list of WhatsApp voice calls.\n\n**Kapso Extension**: This endpoint returns call records stored in Kapso's database, not Meta's API.\n\nSupports filtering by direction, status, and time range. Uses cursor-based pagination.\n", "operationId": "listCalls", "parameters": [ { "name": "direction", "in": "query", "description": "Filter by call direction", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "example": "inbound" }, { "name": "status", "in": "query", "description": "Filter by call status", "schema": { "type": "string", "enum": [ "initiated", "ringing", "answered", "completed", "failed" ] }, "example": "completed" }, { "name": "since", "in": "query", "description": "Filter calls started on or after this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 00:00:00 UTC" }, { "name": "until", "in": "query", "description": "Filter calls started on or before this time (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-15 23:59:59 UTC" }, { "name": "limit", "in": "query", "description": "Maximum number of results per page (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Cursor for previous page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Cursor for next page (Base64 encoded)", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Filter response fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappCall" } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "examples": { "success": { "summary": "List of calls", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "call_id": "call_abc123", "direction": "inbound", "status": "completed", "duration_seconds": 180, "started_at": "2024-01-15 12:34:56 UTC", "ended_at": "2024-01-15 12:37:56 UTC", "session_started_at": "2024-01-15 12:34:58 UTC", "created_at": "2024-01-15 12:34:56 UTC", "updated_at": "2024-01-15 12:37:56 UTC", "user_wa_id": "15551234567", "whatsapp_contact_id": "223e4567-e89b-12d3-a456-426614174001", "whatsapp_conversation_id": "323e4567-e89b-12d3-a456-426614174002", "project_id": "423e4567-e89b-12d3-a456-426614174003", "whatsapp_config_id": "523e4567-e89b-12d3-a456-426614174004", "config_display_name": "Support Line", "config_display_phone_number": "+1 (555) 123-4567", "phone_number_id": "110987654321", "whatsapp_contact": { "id": "223e4567-e89b-12d3-a456-426614174001", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP Customer)" }, "whatsapp_conversation": { "id": "323e4567-e89b-12d3-a456-426614174002", "phone_number": "15551234567", "status": "active", "last_active_at": "2024-01-15 14:30:00 UTC" } }, { "id": "724e4567-e89b-12d3-a456-426614174006", "call_id": "call_def456", "direction": "outbound", "status": "failed", "duration_seconds": null, "started_at": "2024-01-15 10:20:15 UTC", "ended_at": null, "session_started_at": null, "created_at": "2024-01-15 10:20:15 UTC", "updated_at": "2024-01-15 10:20:30 UTC", "user_wa_id": "15559876543", "whatsapp_contact_id": "824e4567-e89b-12d3-a456-426614174007", "whatsapp_conversation_id": null, "project_id": "423e4567-e89b-12d3-a456-426614174003", "whatsapp_config_id": "523e4567-e89b-12d3-a456-426614174004", "config_display_name": "Support Line", "config_display_phone_number": "+1 (555) 123-4567", "phone_number_id": "110987654321", "whatsapp_contact": { "id": "824e4567-e89b-12d3-a456-426614174007", "wa_id": "15559876543", "profile_name": "Jane Smith", "display_name": null }, "whatsapp_conversation": null } ], "paging": { "cursors": { "after": "eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMDoyMDoxNS4wMDAwMDBaIiwiNzI0ZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA2Il0sImNvbHVtbnMiOlsiY2FsbF90aW1lc3RhbXAiLCJpZCJdfQ==" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Calls" ], "summary": "Perform call action", "description": "Perform various call actions via the WhatsApp Calling API.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\nSupports the following actions:\n- **connect**: Initiate an outbound call to a WhatsApp user\n- **pre_accept**: Pre-establish WebRTC connection before accepting call\n- **accept**: Accept an inbound call from a WhatsApp user\n- **reject**: Reject an inbound call\n- **terminate**: End an active call\n", "operationId": "performCallAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messaging_product", "action" ], "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "example": "whatsapp" }, "to": { "type": "string", "description": "Recipient WhatsApp ID (required for connect action)", "example": "15551234567" }, "call_id": { "type": "string", "description": "Call ID (required for pre_accept, accept, reject, terminate)", "example": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh" }, "action": { "type": "string", "enum": [ "connect", "pre_accept", "accept", "reject", "terminate" ], "description": "The action to perform", "example": "accept" }, "session": { "type": "object", "description": "WebRTC session description (required for connect, pre_accept, accept)", "properties": { "sdp_type": { "type": "string", "enum": [ "offer", "answer" ], "description": "SDP type - \"offer\" for connect, \"answer\" for pre_accept/accept", "example": "answer" }, "sdp": { "type": "string", "description": "Session Description Protocol (SDP) compliant with RFC 8866", "example": "v=0\\r\\no=- 7669997803033704573 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\n..." } } }, "biz_opaque_callback_data": { "type": "string", "description": "Arbitrary tracking string (max 512 chars, optional for connect/accept)", "maxLength": 512, "example": "tracking_id_12345" } } }, "examples": { "initiate_call": { "summary": "Initiate outbound call (connect)", "value": { "messaging_product": "whatsapp", "to": "15551234567", "action": "connect", "session": { "sdp_type": "offer", "sdp": "v=0\r\no=- 6314352886888624490 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\na=msid-semantic: WMS ccd3f422-8d7d-49c9-936c-a152979ee4fa\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:/PSS\r\na=ice-pwd:buBIz+JlbmakiCT7JdJIq/j0\r\na=ice-options:trickle\r\na=fingerprint:sha-256 43:08:34:16:67:E3:D9:A2:F5:AA:6A:AE:03:97:C8:D5:B8:F2:4B:40:79:C8:1A:44:53:69:4B:9C:89:88:D7:22\r\na=setup:active\r\na=mid:0\r\na=sendrecv\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\n" }, "biz_opaque_callback_data": "call_session_abc123" } }, "pre_accept_call": { "summary": "Pre-accept call (establish connection early)", "value": { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "pre_accept", "session": { "sdp_type": "answer", "sdp": "v=0\r\no=- 7669997803033704573 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\na=msid-semantic: WMS 3c28addc-03b7-4170-b5cd-535bfe767e75\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:6O0H\r\na=ice-pwd:TYCbtfOrBMPpfxFRgSbYnuTI\r\na=setup:active\r\na=mid:0\r\na=sendrecv\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\n" } } }, "accept_call": { "summary": "Accept inbound call", "value": { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "accept", "session": { "sdp_type": "answer", "sdp": "v=0\r\no=- 7669997803033704573 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\na=msid-semantic: WMS 3c28addc-03b7-4170-b5cd-535bfe767e75\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 110 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:6O0H\r\na=ice-pwd:TYCbtfOrBMPpfxFRgSbYnuTI\r\na=setup:active\r\na=mid:0\r\na=sendrecv\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\n" }, "biz_opaque_callback_data": "session_tracking_xyz" } }, "reject_call": { "summary": "Reject inbound call", "value": { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "reject" } }, "terminate_call": { "summary": "Terminate active call", "value": { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "terminate" } } } } } }, "responses": { "200": { "description": "Action performed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "example": "whatsapp" }, "success": { "type": "boolean", "example": true }, "calls": { "type": "array", "description": "Returned for connect action", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "wacid.ABGGFjFVU2AfAgo6V" } } } } } }, "examples": { "connect_success": { "summary": "Initiate call success", "value": { "messaging_product": "whatsapp", "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh" } ] } }, "action_success": { "summary": "Other actions success", "value": { "messaging_product": "whatsapp", "success": true } } } } } }, "400": { "description": "Bad request (invalid action or parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/media": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "post": { "tags": [ "Media" ], "summary": "Upload media", "description": "Upload media files to WhatsApp. The media ID returned can be used when sending messages.\n\n**Supported formats and size limits:**\n\n**Images** (jpeg, png)\n- Max size: 5MB\n\n**Videos** (mp4, 3gp)\n- Max size: 16MB\n\n**Audio** (aac, mp3, ogg, opus)\n- Max size: 16MB\n\n**Documents** (pdf, doc, docx, ppt, pptx, xls, xlsx)\n- Max size: 100MB\n\n**Stickers** (webp)\n- Static: max 100KB\n- Animated: max 500KB\n", "operationId": "uploadMedia", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "messaging_product" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Media file to upload" }, "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "description": "Always \"whatsapp\"" } } }, "examples": { "upload_image": { "summary": "Upload JPEG image", "value": { "messaging_product": "whatsapp", "file": "@/path/to/image.jpg" } }, "upload_video": { "summary": "Upload MP4 video", "value": { "messaging_product": "whatsapp", "file": "@/path/to/video.mp4" } }, "upload_audio": { "summary": "Upload OGG audio", "value": { "messaging_product": "whatsapp", "file": "@/path/to/audio.ogg" } }, "upload_document": { "summary": "Upload PDF document", "value": { "messaging_product": "whatsapp", "file": "@/path/to/document.pdf" } }, "upload_sticker": { "summary": "Upload WEBP sticker", "value": { "messaging_product": "whatsapp", "file": "@/path/to/sticker.webp" } } } } } }, "responses": { "200": { "description": "Media uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Media ID to use when sending messages", "example": "4490709327384033" } } }, "example": { "id": "4490709327384033" } } } }, "400": { "description": "Bad request (invalid file format or size exceeds limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{media_id}": { "parameters": [ { "name": "media_id", "in": "path", "required": true, "description": "Media ID returned from upload", "schema": { "type": "string" }, "example": "2621233374848975" } ], "get": { "tags": [ "Media" ], "summary": "Get media URL", "description": "Retrieve the download URL for a media file.\n\n**Important:** The returned URL is temporary and expires after 5 minutes.\n", "operationId": "getMediaUrl", "parameters": [ { "name": "phone_number_id", "in": "query", "required": true, "description": "Phone number ID that owns this media", "schema": { "type": "string" }, "example": "110987654321" } ], "responses": { "200": { "description": "Media URL retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "example": "whatsapp" }, "id": { "type": "string", "description": "Media ID", "example": "2621233374848975" }, "url": { "type": "string", "format": "uri", "description": "Temporary download URL (valid for 5 minutes)", "example": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=..." }, "mime_type": { "type": "string", "description": "MIME type", "example": "image/jpeg" }, "sha256": { "type": "string", "description": "File hash", "example": "81d3bd8a8db4868c9520ed47186e8b7c5789e61ff79f7f834be6950b808a90d3" }, "file_size": { "type": "string", "description": "File size in bytes (returned as string)", "example": "303833" }, "download_url": { "type": "string", "format": "uri", "description": "Kapso-hosted authenticated download URL. Valid for 4 minutes.\nUse this URL to download the media file without needing to pass auth headers — authentication is embedded in the token.\n", "example": "https://api.kapso.ai/meta/whatsapp/media_download?token=..." }, "download_url_expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 expiry timestamp for `download_url`.", "example": "2026-03-13 12:34:56 UTC" } } }, "example": { "messaging_product": "whatsapp", "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=2621233374848975&ext=1234567890&hash=...", "mime_type": "image/jpeg", "sha256": "81d3bd8a8db4868c9520ed47186e8b7c5789e61ff79f7f834be6950b808a90d3", "file_size": "303833", "id": "2621233374848975", "download_url": "https://api.kapso.ai/meta/whatsapp/media_download?token=eyJfcmFpbHMiOnsibWVzc2FnZSI6...", "download_url_expires_at": "2026-03-13 12:34:56 UTC" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Media" ], "summary": "Delete media", "description": "Delete a media file from WhatsApp.\n\nYou can optionally provide `phone_number_id` query parameter to verify the media belongs to that phone number before deletion.\n", "operationId": "deleteMedia", "parameters": [ { "name": "phone_number_id", "in": "query", "required": false, "description": "Optional - verify media belongs to this phone number", "schema": { "type": "string" }, "example": "110987654321" } ], "responses": { "200": { "description": "Media deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Media not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/media_download": { "servers": [ { "url": "https://api.kapso.ai/meta/whatsapp", "description": "Kapso Media Download (no version prefix)" } ], "get": { "tags": [ "Media" ], "summary": "Download media file", "description": "Download a media file using a short-lived authenticated token.\n\nTokens are returned in the `download_url` field of the [Get media URL](#operation/getMediaUrl) response.\nThey expire 4 minutes after issue.\n\nNo `X-API-Key` header is needed — authentication is embedded in the token.\n", "operationId": "downloadMedia", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Signed token from `download_url`", "schema": { "type": "string" }, "example": "eyJfcmFpbHMiOnsibWVzc2FnZSI6..." } ], "responses": { "200": { "description": "Media file bytes", "headers": { "Content-Type": { "description": "MIME type of the media file", "schema": { "type": "string", "example": "image/jpeg" } }, "Content-Disposition": { "description": "Inline disposition with media ID as filename", "schema": { "type": "string", "example": "inline; filename=\"2621233374848975\"" } }, "Cache-Control": { "description": "Cache directive (tokens are short-lived)", "schema": { "type": "string", "example": "private, max-age=240" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Token missing, invalid, expired, or media not found" }, "502": { "description": "Media download from WhatsApp failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Media download failed" } } } } } } } } }, "/{business_account_id}/message_templates": { "parameters": [ { "name": "business_account_id", "in": "path", "required": true, "description": "WhatsApp Business Account ID", "schema": { "type": "string" }, "example": "123456789012345" } ], "get": { "tags": [ "Templates" ], "summary": "List message templates", "description": "Retrieve a list of approved message templates for this phone number.\n\nTemplates must be approved by WhatsApp before they can be used.\n", "operationId": "listTemplates", "parameters": [ { "name": "name", "in": "query", "description": "Filter by template name", "schema": { "type": "string" }, "example": "order_confirmation" }, { "name": "status", "in": "query", "description": "Filter by template status", "schema": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ] }, "example": "APPROVED" }, { "name": "category", "in": "query", "description": "Filter by template category", "schema": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ] } }, { "name": "language", "in": "query", "description": "Filter by language code", "schema": { "type": "string" }, "example": "en_US" }, { "name": "limit", "in": "query", "description": "Maximum number of results (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successfully retrieved templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID", "example": "1192339204654487" }, "name": { "type": "string", "example": "order_confirmation" }, "language": { "type": "string", "example": "en_US" }, "status": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ], "example": "APPROVED" }, "category": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ], "example": "UTILITY" }, "previous_category": { "type": "string", "description": "Previous category if changed", "example": "ACCOUNT_UPDATE" }, "components": { "type": "array", "description": "Template components (header, body, footer, buttons)" } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "example": { "data": [ { "id": "1192339204654487", "name": "hello_world", "previous_category": "ACCOUNT_UPDATE", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Hello World" }, { "type": "BODY", "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform's Cloud API. Thank you for taking the time to test with us." }, { "type": "FOOTER", "text": "WhatsApp Business API Team" } ], "language": "en_US", "status": "APPROVED", "category": "MARKETING" }, { "id": "920070352646140", "name": "seasonal_promotion", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Fall Sale" }, { "type": "BODY", "text": "Hi {{1}}, our Fall Sale is on! Use promo code {{2}} Get an extra 25% off every order above $350!", "example": { "body_text": [ [ "Mark", "FALL25" ] ] } }, { "type": "FOOTER", "text": "Not interested in any of our sales? Tap Stop Promotions" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Stop promotions" } ] } ], "language": "en_US", "status": "APPROVED", "category": "MARKETING" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MjQZD" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Templates" ], "summary": "Create or update message template", "description": "Create a new WhatsApp message template, or update an existing one.\n\n- Omit `hsm_id` to create a new template.\n- Include `hsm_id` as a query parameter to update an existing template.\n\nTemplates must be approved by WhatsApp before they can be used. After creation,\ntemplates enter a PENDING state until reviewed.\n\n**Side effect**: Enqueues a template sync job on success to update Kapso's\nlocal template cache.\n", "operationId": "createOrUpdateTemplate", "parameters": [ { "name": "hsm_id", "in": "query", "required": false, "description": "Template ID to update.\n\n- Omit for template creation.\n- Required when updating an existing template.\n", "schema": { "type": "string" }, "example": "1627019861106475" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for template creation or update.\n\n- For create requests, `name`, `language`, `category`, and `components`\n are required.\n- For update requests, include `hsm_id` in the query string and provide\n the fields you want to change.\n", "properties": { "name": { "type": "string", "description": "Template name (lowercase, underscore-separated)", "example": "order_confirmation" }, "language": { "type": "string", "description": "Language code (e.g., en, en_US)", "example": "en_US" }, "category": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ], "description": "Template category", "example": "UTILITY" }, "parameter_format": { "type": "string", "enum": [ "NAMED", "POSITIONAL" ], "description": "Format for template parameters (defaults to POSITIONAL if omitted).\n\n**NAMED**: Parameters use unique names wrapped in double curly brackets (e.g., {{first_name}}, {{order_number}}). Values can appear in any order in send payloads.\n\n**POSITIONAL**: Parameters use ordered array indices starting from 1 (e.g., {{1}}, {{2}}). Values must appear in order in send payloads.\n", "example": "NAMED" }, "components": { "type": "array", "description": "Template components. Supported types:\n\n**HEADER** - Optional component at top. Formats: TEXT (1 param), IMAGE, VIDEO, DOCUMENT, LOCATION\n\n**BODY** - Required text component. Supports multiple parameters (positional or named)\n\n**FOOTER** - Optional text-only component. No parameters supported\n\n**BUTTONS** - Optional interactive components. Types: QUICK_REPLY (10 max), PHONE_NUMBER (1 max), URL (2 max), COPY_CODE (1 max), OTP, CATALOG, MPM, FLOW\n", "items": { "type": "object" } } } }, "examples": { "body_named_params": { "summary": "Simple body with named parameters (simplest)", "value": { "name": "order_confirmation_simple", "language": "en_US", "category": "UTILITY", "parameter_format": "NAMED", "components": [ { "type": "BODY", "text": "Thank you, {{customer_name}}! Your order number is {{order_number}}.", "example": { "body_text_named_params": [ { "param_name": "customer_name", "example": "Pablo" }, { "param_name": "order_number", "example": "860198-230332" } ] } } ] } }, "body_positional_params": { "summary": "Body with positional parameters", "value": { "name": "delivery_notification", "language": "en_US", "category": "UTILITY", "parameter_format": "POSITIONAL", "components": [ { "type": "BODY", "text": "Good news {{1}}! Your order #{{2}} has been delivered.", "example": { "body_text": [ [ "Mark", "566701" ] ] } } ] } }, "text_header_body_footer_buttons": { "summary": "Text header + body + footer + quick reply buttons", "value": { "name": "seasonal_promotion", "language": "en_US", "category": "MARKETING", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Our {{1}} is on!", "example": { "header_text": [ "Summer Sale" ] } }, { "type": "BODY", "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.", "example": { "body_text": [ [ "the end of August", "25OFF", "25%" ] ] } }, { "type": "FOOTER", "text": "Use the buttons below to manage your marketing subscriptions" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Unsubscribe from Promos" }, { "type": "QUICK_REPLY", "text": "Unsubscribe from All" } ] } ] } }, "document_header": { "summary": "Document header with action buttons", "value": { "name": "order_confirmation_receipt", "language": "en_US", "category": "UTILITY", "components": [ { "type": "HEADER", "format": "DOCUMENT", "example": { "header_handle": [ "4::YXBwbGljYXRpb24vcGRm:ARZVv4zuogJMxmAdS3_6T4o..." ] } }, { "type": "BODY", "text": "Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt. If you have any questions, please use the buttons below to contact support.", "example": { "body_text": [ [ "Pablo", "860198-230332" ] ] } }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", "text": "Call", "phone_number": "15550051310" }, { "type": "URL", "text": "Contact Support", "url": "https://www.luckyshrub.com/support" } ] } ] } }, "location_header": { "summary": "Location header for delivery/pickup", "value": { "name": "order_delivery_update", "language": "en_US", "category": "UTILITY", "components": [ { "type": "HEADER", "format": "LOCATION" }, { "type": "BODY", "text": "Good news {{1}}! Your order #{{2}} is on its way to the location above. Thank you for your order!", "example": { "body_text": [ [ "Mark", "566701" ] ] } }, { "type": "FOOTER", "text": "To stop receiving delivery updates, tap the button below." }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Stop Delivery Updates" } ] } ] } }, "image_header": { "summary": "Image header with media", "value": { "name": "limited_time_offer", "language": "en_US", "category": "MARKETING", "components": [ { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": [ "4::aW1hZ2UvanBlZw==:ARa1ZDhwbLZM3EENeeg" ] } }, { "type": "BODY", "text": "Hi {{1}}! For a limited time only you can get our {{2}} for as low as {{3}}.", "example": { "body_text": [ [ "Mark", "Tuscan Getaway package", "800" ] ] } }, { "type": "FOOTER", "text": "Offer valid until May 31, 2023" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", "text": "Call", "phone_number": "15550051310" }, { "type": "URL", "text": "Shop Now", "url": "https://www.examplesite.com/shop" } ] } ] } }, "url_button_with_param": { "summary": "URL button with dynamic parameter", "value": { "name": "promo_with_dynamic_link", "language": "en_US", "category": "MARKETING", "components": [ { "type": "BODY", "text": "Special offer just for you! Tap below to view your personalized deals." }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "View Offers", "url": "https://www.examplesite.com/shop?promo={{1}}", "example": [ "summer2023" ] } ] } ] } }, "authentication_otp_copy_code": { "summary": "Authentication - COPY_CODE (manual entry)", "value": { "name": "auth_otp_copy_code", "language": "en_US", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "add_security_recommendation": true }, { "type": "FOOTER", "code_expiration_minutes": 10 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE" } ] } ] } }, "authentication_otp_one_tap": { "summary": "Authentication - ONE_TAP (Android autofill)", "value": { "name": "auth_otp_one_tap", "language": "en_US", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "add_security_recommendation": true }, { "type": "FOOTER", "code_expiration_minutes": 10 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "ONE_TAP", "supported_apps": [ { "package_name": "com.example.myapp", "signature_hash": "K8a%2FAINcGX7" } ] } ] } ] } }, "authentication_otp_zero_tap": { "summary": "Authentication - ZERO_TAP (no button, auto-read)", "value": { "name": "auth_otp_zero_tap", "language": "en_US", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "add_security_recommendation": false }, { "type": "FOOTER", "code_expiration_minutes": 5 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "ZERO_TAP" } ] } ] } }, "catalog_button": { "summary": "Catalog button for product browsing", "value": { "name": "catalog_promotion", "language": "en_US", "category": "MARKETING", "components": [ { "type": "BODY", "text": "Now shop for your favourite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs!", "example": { "body_text": [ [ "100", "400" ] ] } }, { "type": "FOOTER", "text": "Best grocery deals on WhatsApp!" }, { "type": "BUTTONS", "buttons": [ { "type": "CATALOG", "text": "View catalog" } ] } ] } }, "mpm_button": { "summary": "Multi-product message button", "value": { "name": "abandoned_cart_mpm", "language": "en_US", "category": "MARKETING", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Forget something {{1}}?", "example": { "header_text": [ "Pablo" ] } }, { "type": "BODY", "text": "Looks like you left some items in your cart! Use code {{1}} and you can get 10% off of all of them!", "example": { "body_text": [ [ "10OFF" ] ] } }, { "type": "BUTTONS", "buttons": [ { "type": "MPM", "text": "View items" } ] } ] } }, "video_header": { "summary": "Video header with media", "value": { "name": "product_demo_video", "language": "en_US", "category": "MARKETING", "components": [ { "type": "HEADER", "format": "VIDEO", "example": { "header_handle": [ "4::dmlkZW8vbXA0:ARa8f2Xh9K3pLmNqR1sT..." ] } }, { "type": "BODY", "text": "Check out our new product in action! Watch the video above to see how it works." }, { "type": "FOOTER", "text": "Available now" } ] } }, "text_header_named_params": { "summary": "Text header with named parameters", "value": { "name": "event_reminder", "language": "en_US", "category": "UTILITY", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Reminder: {{event_name}} starts {{start_time}}", "example": { "header_text_named_params": [ { "param_name": "event_name", "example": "Summer Webinar" }, { "param_name": "start_time", "example": "tomorrow at 3 PM" } ] } }, { "type": "BODY", "text": "Don't forget to join us for {{event_name}}. We'll be covering exciting updates!", "example": { "body_text_named_params": [ { "param_name": "event_name", "example": "Summer Webinar" } ] } } ] } }, "copy_code_button": { "summary": "Copy code button for promo codes", "value": { "name": "promo_code_offer", "language": "en_US", "category": "MARKETING", "components": [ { "type": "BODY", "text": "Special discount just for you! Use code below to get 20% off your next purchase." }, { "type": "BUTTONS", "buttons": [ { "type": "COPY_CODE", "example": "SAVE20" } ] } ] } }, "flow_button_basic": { "summary": "Flow button for interactive experiences", "value": { "name": "feedback_survey_flow", "language": "en_US", "category": "UTILITY", "components": [ { "type": "BODY", "text": "We'd love to hear your feedback! Tap below to share your thoughts in a quick survey." }, { "type": "BUTTONS", "buttons": [ { "type": "FLOW", "text": "Take Survey", "flow_id": "123456789012345", "flow_action": "navigate", "navigate_screen": "WELCOME_SCREEN" } ] } ] } }, "template_update": { "summary": "Update an existing template by hsm_id", "value": { "category": "MARKETING", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Updated Header" }, { "type": "BODY", "text": "Updated body text" } ] } } } } } }, "responses": { "200": { "description": "Template created or updated successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID", "example": "1627019861106475" }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ], "description": "Template status", "example": "PENDING" }, "category": { "type": "string", "description": "Template category", "example": "UTILITY" } } }, { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } ] }, "examples": { "created": { "summary": "Template created", "value": { "id": "1627019861106475", "status": "PENDING", "category": "UTILITY" } }, "updated": { "summary": "Template updated", "value": { "success": true } } } } } }, "400": { "description": "Bad request (invalid template format or missing/invalid hsm_id for updates)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "hsm_id is required" } } } ] }, "examples": { "invalid_template": { "summary": "Invalid template format", "value": { "error": { "message": "Invalid template format", "type": "OAuthException", "code": 400 } } }, "missing_hsm_id": { "summary": "Missing hsm_id on update", "value": { "error": "hsm_id is required" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found (update only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete message template", "description": "Delete a WhatsApp message template.\n\n**Specify either `name` or `hsm_id` to identify the template to delete.**\n", "operationId": "deleteTemplate", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Template name to delete (use this OR hsm_id)", "schema": { "type": "string" }, "example": "order_confirmation" }, { "name": "hsm_id", "in": "query", "required": false, "description": "Template ID to delete (use this OR name)", "schema": { "type": "string" }, "example": "1627019861106475" } ], "responses": { "200": { "description": "Template deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{business_account_id}/message_templates/{template_id}": { "parameters": [ { "name": "business_account_id", "in": "path", "required": true, "description": "WhatsApp Business Account ID", "schema": { "type": "string" }, "example": "123456789012345" }, { "name": "template_id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string" }, "example": "1259544702043867" } ], "get": { "tags": [ "Templates" ], "summary": "Get message template by ID", "description": "Retrieve a single WhatsApp message template by its ID.\n\nUse this endpoint to fetch full details of a specific template when you already know its ID. For listing templates or searching by name, use the list endpoint instead.\n", "operationId": "getTemplate", "parameters": [ { "name": "fields", "in": "query", "description": "Comma-separated list of fields to retrieve", "schema": { "type": "string" }, "example": "id,name,status,language,components" } ], "responses": { "200": { "description": "Successfully retrieved template", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID", "example": "1259544702043867" }, "name": { "type": "string", "example": "order_confirmation" }, "language": { "type": "string", "example": "en_US" }, "status": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ], "example": "APPROVED" }, "category": { "type": "string", "enum": [ "AUTHENTICATION", "MARKETING", "UTILITY" ], "example": "UTILITY" }, "previous_category": { "type": "string", "description": "Previous category if changed", "example": "ACCOUNT_UPDATE" }, "components": { "type": "array", "description": "Template components (header, body, footer, buttons)", "items": { "type": "object" } } } }, "example": { "id": "1259544702043867", "name": "order_confirmation", "language": "en_US", "status": "APPROVED", "category": "UTILITY", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Order Update" }, { "type": "BODY", "text": "Your order {{1}} has been confirmed and will arrive by {{2}}.", "example": { "body_text": [ [ "#12345", "Friday" ] ] } }, { "type": "FOOTER", "text": "Thanks for shopping with us!" } ] } } } }, "400": { "description": "Bad request (invalid template_id format)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid template_id" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/whatsapp_business_profile": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Business Profile" ], "summary": "Get business profile", "description": "Retrieve the WhatsApp Business profile information. WhatsApp users can view your business profile by clicking your business's name or number in a WhatsApp message thread.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "getBusinessProfile", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of fields to retrieve", "schema": { "type": "string" }, "example": "about,address,description,email,profile_picture_url,websites,vertical" } ], "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "about": { "type": "string", "description": "The business's About text (1-139 characters). Appears in profile beneath profile image and phone number.", "minLength": 1, "maxLength": 139 }, "address": { "type": "string", "description": "Address of the business", "maxLength": 256 }, "description": { "type": "string", "description": "Description of the business", "maxLength": 512 }, "email": { "type": "string", "format": "email", "description": "Contact email address of the business", "maxLength": 128 }, "messaging_product": { "type": "string", "description": "Messaging service (always \"whatsapp\")", "enum": [ "whatsapp" ] }, "profile_picture_url": { "type": "string", "format": "uri", "description": "URL of the profile picture (read-only)", "readOnly": true }, "websites": { "type": "array", "description": "URLs associated with the business (max 2 websites, 256 chars each)", "maxItems": 2, "items": { "type": "string", "format": "uri", "maxLength": 256 } }, "vertical": { "type": "string", "description": "Business industry category", "enum": [ "ALCOHOL", "APPAREL", "AUTO", "BEAUTY", "EDU", "ENTERTAIN", "EVENT_PLAN", "FINANCE", "GROCERY", "GOVT", "HOTEL", "HEALTH", "NONPROFIT", "ONLINE_GAMBLING", "OTC_DRUGS", "OTHER", "PHYSICAL_GAMBLING", "PROF_SERVICES", "RESTAURANT", "RETAIL", "TRAVEL" ] } } } } } }, "example": { "data": [ { "about": "Premium coffee roasters since 2010", "address": "123 Main St, San Francisco, CA 94102", "description": "Specialty coffee beans sourced directly from sustainable farms", "email": "hello@premiumcoffee.com", "messaging_product": "whatsapp", "profile_picture_url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=...", "websites": [ "https://premiumcoffee.com", "https://instagram.com/premiumcoffee" ], "vertical": "RETAIL" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Business Profile" ], "summary": "Update business profile", "description": "Update WhatsApp business profile information.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API /PHONE_NUMBER_ID/whatsapp_business_profile.\n\nUse this endpoint to update:\n- About text (1-139 characters, appears below profile image)\n- Business address and description\n- Contact email\n- Profile picture (via handle from resumable upload)\n- Business category (vertical)\n- Website links (max 2)\n\n**Restrictions**:\n- About text: 1-139 chars, rendered emojis supported, hyperlinks won't be clickable, no markdown\n- Address: max 256 characters\n- Description: max 512 characters\n- Email: max 128 characters, valid email format\n- Websites: max 2 URLs, max 256 chars each, must include http:// or https://\n\n**Note**: Sandbox configurations are blocked (returns 403).\n", "operationId": "updateBusinessProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfileUpdate" }, "examples": { "basic_about": { "summary": "Update About text", "value": { "messaging_product": "whatsapp", "about": "Welcome to our store! We're here to help you 24/7 with all your shopping needs." } }, "complete_profile": { "summary": "Update all profile fields", "value": { "messaging_product": "whatsapp", "about": "Your trusted partner for quality products and services.", "address": "123 Main Street, San Francisco, CA 94102", "description": "Leading provider of premium products and services since 2010. We pride ourselves on exceptional customer service and quality.", "email": "support@example.com", "vertical": "RETAIL", "websites": [ "https://www.example.com", "https://www.instagram.com/example" ] } }, "with_profile_picture": { "summary": "Update profile with picture", "description": "Profile picture handle from resumable upload API", "value": { "messaging_product": "whatsapp", "about": "Premium spa and beauty services", "vertical": "BEAUTY", "profile_picture_handle": "h:resumable-upload-handle-abc123xyz789" } }, "restaurant": { "summary": "Restaurant profile", "value": { "messaging_product": "whatsapp", "about": "Authentic Italian cuisine in the heart of SF", "address": "456 Market Street, San Francisco, CA 94103", "description": "Family-owned Italian restaurant serving traditional recipes passed down through generations. Reservations recommended.", "email": "reservations@restaurant.com", "vertical": "RESTAURANT", "websites": [ "https://www.restaurant.com" ] } } } } } }, "responses": { "200": { "description": "Business profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfileUpdateResponse" }, "examples": { "success": { "summary": "Successful update", "value": { "success": true } } } } } }, "400": { "description": "Bad request (validation errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_about_length": { "summary": "About text too long", "value": { "error": { "message": "About text must be between 1 and 139 characters", "type": "OAuthException", "code": 400 } } }, "invalid_email": { "summary": "Invalid email format", "value": { "error": { "message": "Invalid email address format", "type": "OAuthException", "code": 400 } } }, "too_many_websites": { "summary": "Too many URLs", "value": { "error": { "message": "Maximum of 2 websites allowed", "type": "OAuthException", "code": 400 } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (sandbox configs blocked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sandbox_blocked": { "summary": "Sandbox configuration rejected", "value": { "error": { "message": "Sandbox WhatsApp configurations cannot update business profile", "type": "OAuthException", "code": 403 } } } } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/call_permissions": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Calls" ], "summary": "Get call permission state", "description": "Get the call permission state for a business phone number with a specific WhatsApp user.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\nReturns the current permission status and available actions with their limits. Permission can be:\n- **no_permission**: No calling permission granted\n- **temporary**: Temporary permission with expiration time\n\nActions include:\n- **send_call_permission_request**: Send permission request message\n- **start_call**: Initiate a call\n\nEach action has time-based limits (e.g., max 2 permission requests per 24 hours).\n", "operationId": "getCallPermissions", "parameters": [ { "name": "user_wa_id", "in": "query", "required": true, "description": "WhatsApp ID of the user (phone number)", "schema": { "type": "string" }, "example": "15551234567" } ], "responses": { "200": { "description": "Permissions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "messaging_product", "permission", "actions" ], "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ], "example": "whatsapp" }, "permission": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "no_permission", "temporary" ], "description": "Current permission status", "example": "temporary" }, "expiration_time": { "type": "integer", "description": "Unix timestamp when permission expires (only for temporary status)", "example": 1745343479 } } }, "actions": { "type": "array", "description": "Available actions with their limits", "items": { "type": "object", "properties": { "action_name": { "type": "string", "enum": [ "send_call_permission_request", "start_call" ], "description": "The action that can be performed", "example": "send_call_permission_request" }, "can_perform_action": { "type": "boolean", "description": "Whether the action can be performed now", "example": true }, "limits": { "type": "array", "description": "Time-based restrictions for this action", "items": { "type": "object", "properties": { "time_period": { "type": "string", "description": "Time span in ISO 8601 format (e.g., PT24H for 24 hours, P7D for 7 days)", "example": "PT24H" }, "max_allowed": { "type": "integer", "description": "Maximum actions allowed in this time period", "example": 1 }, "current_usage": { "type": "integer", "description": "Current number of actions taken in this period", "example": 0 }, "limit_expiration_time": { "type": "integer", "description": "Unix timestamp when limit resets (only present when limit is reached)", "example": 1745622600 } } } } } } } } }, "examples": { "temporary_permission": { "summary": "Temporary permission granted", "value": { "messaging_product": "whatsapp", "permission": { "status": "temporary", "expiration_time": 1745343479 }, "actions": [ { "action_name": "send_call_permission_request", "can_perform_action": true, "limits": [ { "time_period": "PT24H", "max_allowed": 1, "current_usage": 0 }, { "time_period": "P7D", "max_allowed": 2, "current_usage": 1 } ] }, { "action_name": "start_call", "can_perform_action": false, "limits": [ { "time_period": "PT24H", "max_allowed": 5, "current_usage": 5, "limit_expiration_time": 1745622600 } ] } ] } }, "no_permission": { "summary": "No permission granted", "value": { "messaging_product": "whatsapp", "permission": { "status": "no_permission" }, "actions": [ { "action_name": "send_call_permission_request", "can_perform_action": true, "limits": [ { "time_period": "PT24H", "max_allowed": 1, "current_usage": 0 } ] }, { "action_name": "start_call", "can_perform_action": false, "limits": [] } ] } } } } } }, "400": { "description": "Bad request (invalid parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached (max 5 requests per second)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/block_users": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" }, "example": "110987654321" } ], "get": { "tags": [ "Block Users" ], "summary": "List blocked users", "description": "Retrieve the list of users blocked for a given phone number.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "listBlockedUsers", "responses": { "200": { "description": "Blocked users retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string", "description": "WhatsApp ID (phone number) of the blocked user", "example": "15551234567" } } } } } }, "examples": { "success": { "summary": "List of blocked users", "value": { "data": [ { "user": "15551234567" }, { "user": "15559876543" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Block Users" ], "summary": "Block users", "description": "Block one or more users for a given phone number.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "blockUsers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "block_users" ], "properties": { "block_users": { "type": "array", "items": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "WhatsApp ID (phone number) of the user to block", "example": "15551234567" } } } } } }, "example": { "block_users": [ { "user": "15551234567" }, { "user": "15559876543" } ] } } } }, "responses": { "200": { "description": "Users blocked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Block Users" ], "summary": "Unblock users", "description": "Unblock one or more previously blocked users for a given phone number.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "unblockUsers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "block_users" ], "properties": { "block_users": { "type": "array", "items": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "WhatsApp ID (phone number) of the user to unblock", "example": "15551234567" } } } } } }, "example": { "block_users": [ { "user": "15551234567" } ] } } } }, "responses": { "200": { "description": "Users unblocked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{business_account_id}/flows": { "parameters": [ { "name": "business_account_id", "in": "path", "required": true, "description": "WhatsApp Business Account ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Flows" ], "summary": "List flows", "description": "List all WhatsApp Flows for a business account.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "listFlows", "responses": { "200": { "description": "Flows retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED", "BLOCKED", "THROTTLED" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PROPERTY" }, "error_type": { "type": "string", "example": "JSON_SCHEMA_ERROR" }, "message": { "type": "string", "example": "The property \"initial-text\" cannot be specified at \"$root/screens/0/layout/children/2/children/0\"." }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } } } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "example": { "data": [ { "id": "flow-1", "name": "my first flow", "status": "DRAFT", "categories": [ "SIGN_UP" ], "validation_errors": [] }, { "id": "flow-2", "name": "my second flow", "status": "PUBLISHED", "categories": [ "SURVEY" ], "validation_errors": [] } ], "paging": { "cursors": { "before": "QVFIUnpKT...", "after": "QVFIUnZAWV..." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Create flow", "description": "Create a new WhatsApp Flow.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "createFlow", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "categories" ], "properties": { "name": { "type": "string", "description": "Flow name" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER" ] }, "description": "Flow categories" }, "clone_flow_id": { "type": "string", "description": "ID of flow to clone" }, "endpoint_uri": { "type": "string", "format": "uri", "description": "Endpoint URI for the flow" }, "flow_json": { "type": "string", "description": "Flow's JSON encoded as string. If provided with publish=true, creates and publishes flow in one request." }, "publish": { "type": "boolean", "description": "Indicates whether Flow should also get published. Only works if flow_json is provided with valid Flow JSON." } } }, "example": { "name": "appointment_booking", "categories": [ "APPOINTMENT_BOOKING" ] } } } }, "responses": { "200": { "description": "Flow created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Flow ID" }, "success": { "type": "boolean" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" }, "error_type": { "type": "string" }, "message": { "type": "string" }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}/flows": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Flows" ], "summary": "List flows (phone number scoped)", "description": "List all WhatsApp Flows for a phone number.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\n**Note**: Requires WhatsappConfig with matching phone_number_id.\n", "operationId": "listFlowsByPhoneNumber", "responses": { "200": { "description": "Flows retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED", "BLOCKED", "THROTTLED" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PROPERTY" }, "error_type": { "type": "string", "example": "JSON_SCHEMA_ERROR" }, "message": { "type": "string", "example": "The property \"initial-text\" cannot be specified at \"$root/screens/0/layout/children/2/children/0\"." }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } } } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "example": { "data": [ { "id": "flow-1", "name": "my first flow", "status": "DRAFT", "categories": [ "SIGN_UP" ], "validation_errors": [] }, { "id": "flow-2", "name": "my second flow", "status": "PUBLISHED", "categories": [ "SURVEY" ], "validation_errors": [] } ], "paging": { "cursors": { "before": "QVFIUnpKT...", "after": "QVFIUnZAWV..." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Create flow (phone number scoped)", "description": "Create a new WhatsApp Flow for a phone number.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\n**Note**: Requires WhatsappConfig with matching phone_number_id.\n", "operationId": "createFlowByPhoneNumber", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "categories" ], "properties": { "name": { "type": "string", "description": "Flow name" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER" ] }, "description": "Flow categories" }, "clone_flow_id": { "type": "string", "description": "ID of flow to clone" }, "endpoint_uri": { "type": "string", "format": "uri", "description": "Endpoint URI for the flow" }, "flow_json": { "type": "string", "description": "Flow's JSON encoded as string. If provided with publish=true, creates and publishes flow in one request." }, "publish": { "type": "boolean", "description": "Indicates whether Flow should also get published. Only works if flow_json is provided with valid Flow JSON." } } }, "example": { "name": "appointment_booking", "categories": [ "APPOINTMENT_BOOKING" ] } } } }, "responses": { "200": { "description": "Flow created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Flow ID" }, "success": { "type": "boolean" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string" }, "error_type": { "type": "string" }, "message": { "type": "string" }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{flow_id}/assets": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Flows" ], "summary": "Get flow assets", "description": "Get flow JSON assets and URLs.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "getFlowAssets", "responses": { "200": { "description": "Flow assets retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Asset name (always \"flow.json\")", "example": "flow.json" }, "asset_type": { "type": "string", "description": "Asset type (always \"FLOW_JSON\")", "example": "FLOW_JSON" }, "download_url": { "type": "string", "format": "uri", "description": "URL to download the flow JSON file", "example": "https://scontent.xx.fbcdn.net/m1/v/t0.57323-24/An_Hq0jnfJ..." } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Upload flow JSON", "description": "Upload or update flow JSON definition. The file must be attached as multipart/form-data.\n\nReturns validation errors in the Flow JSON, if any.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "uploadFlowAssets", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "name", "asset_type" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Flow JSON file (max 10 MB)" }, "name": { "type": "string", "description": "Asset name (must be \"flow.json\")", "example": "flow.json" }, "asset_type": { "type": "string", "description": "Asset type (must be \"FLOW_JSON\")", "example": "FLOW_JSON" } } } } } }, "responses": { "200": { "description": "Flow assets uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PROPERTY" }, "error_type": { "type": "string", "example": "JSON_SCHEMA_ERROR" }, "message": { "type": "string" }, "line_start": { "type": "integer" }, "line_end": { "type": "integer" }, "column_start": { "type": "integer" }, "column_end": { "type": "integer" } } } } } }, "example": { "success": true, "validation_errors": [] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{flow_id}": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Flows" ], "summary": "Get flow details", "description": "Retrieve detailed information about a specific flow.\n\nBy default returns: id, name, status, categories, validation_errors.\n\nUse `fields` parameter to request additional information like preview URLs, health status, metrics, etc.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "getFlow", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of fields to retrieve.\n\nAvailable fields: id, name, status, categories, validation_errors, json_version, data_api_version, endpoint_uri, preview, whatsapp_business_account, application, health_status\n\nPreview can be invalidated: `preview.invalidate(true)`\n\nMetrics: `metric.name(ENDPOINT_REQUEST_COUNT).granularity(DAY).since(2024-01-28).until(2024-01-30)`\n", "schema": { "type": "string" }, "example": "id,name,categories,preview,status,validation_errors" }, { "name": "phone_number_id", "in": "query", "required": false, "description": "Required when accessing flow by ID (unless business_account_id provided)", "schema": { "type": "string" } }, { "name": "business_account_id", "in": "query", "required": false, "description": "Required when accessing flow by ID (unless phone_number_id provided)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Flow details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED", "BLOCKED", "THROTTLED" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "validation_errors": { "type": "array", "items": { "type": "object" } }, "json_version": { "type": "string" }, "data_api_version": { "type": "string" }, "endpoint_uri": { "type": "string", "format": "uri" }, "preview": { "type": "object", "properties": { "preview_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, "health_status": { "type": "object", "description": "Health status of flow and related entities" } } }, "example": { "id": "flow-1", "name": "appointment_booking", "status": "DRAFT", "categories": [ "APPOINTMENT_BOOKING" ], "validation_errors": [], "json_version": "3.0", "data_api_version": "3.0", "endpoint_uri": "https://example.com" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Update flow metadata", "description": "Update flow name, categories, endpoint_uri, or application_id.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "updateFlowMetadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Flow name" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER" ] }, "description": "Flow categories (at least one required if provided)" }, "endpoint_uri": { "type": "string", "format": "uri", "description": "URL of the WhatsApp Flow Endpoint (for Flow JSON 3.0+)" }, "application_id": { "type": "string", "description": "ID of the Meta application connected to the Flow" } } }, "example": { "name": "Updated Flow Name", "categories": [ "APPOINTMENT_BOOKING", "CUSTOMER_SUPPORT" ] } } } }, "responses": { "200": { "description": "Flow metadata updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/flows/{flow_id}": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "delete": { "tags": [ "Flows" ], "summary": "Delete flow", "description": "Delete a draft flow. This action is not reversible.\n\n**Only DRAFT flows can be deleted.** Published flows cannot be deleted but can be deprecated.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\n**Note**: This endpoint uses the `/flows/` prefix. It is an alias provided for better developer experience.\n", "operationId": "deleteFlow", "responses": { "200": { "description": "Flow deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request (e.g., trying to delete non-draft flow)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{flow_id}/publish": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "post": { "tags": [ "Flows" ], "summary": "Publish flow", "description": "Publish a flow. This action is not reversible.\n\nOnce published, the flow and its assets become immutable.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "publishFlow", "responses": { "200": { "description": "Flow published successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{flow_id}/deprecate": { "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "post": { "tags": [ "Flows" ], "summary": "Deprecate flow", "description": "Deprecate a published flow.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "deprecateFlow", "responses": { "200": { "description": "Flow deprecated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{business_account_id}/phone_numbers": { "parameters": [ { "name": "business_account_id", "in": "path", "required": true, "description": "WhatsApp Business Account ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Phone Numbers" ], "summary": "List phone numbers", "description": "List all phone numbers associated with a business account.\n\nReturns basic phone number information including verification status and quality rating.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "listPhoneNumbers", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of fields to retrieve.\n\nAvailable fields: id, verified_name, display_phone_number, quality_rating, code_verification_status, is_official_business_account, name_status, new_name_status, platform_type, throughput, account_mode, certificate, messaging_limit_tier\n", "schema": { "type": "string" }, "example": "id,verified_name,display_phone_number,quality_rating" } ], "responses": { "200": { "description": "Phone numbers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Phone number ID" }, "verified_name": { "type": "string", "description": "Verified business name associated with the phone number" }, "display_phone_number": { "type": "string", "description": "Phone number in international format" }, "quality_rating": { "type": "string", "enum": [ "GREEN", "YELLOW", "RED", "NA", "UNKNOWN" ], "description": "Quality rating based on message delivery.\n- GREEN: High quality\n- YELLOW: Medium quality\n- RED: Low quality\n- NA: Not yet determined\n- UNKNOWN: Status unknown\n" }, "code_verification_status": { "type": "string", "description": "Verification status of the phone number" }, "is_official_business_account": { "type": "boolean", "description": "Whether this is an official business account" }, "name_status": { "type": "string", "description": "Status of the business name" }, "new_name_status": { "type": "string", "description": "Status of pending name change" }, "platform_type": { "type": "string", "description": "Platform type (CLOUD_API, etc.)" }, "throughput": { "type": "object", "description": "Messaging throughput limits" }, "account_mode": { "type": "string", "enum": [ "SANDBOX", "LIVE" ], "description": "Account mode" }, "certificate": { "type": "string", "description": "Certificate status" }, "messaging_limit_tier": { "type": "string", "description": "Current messaging limit tier" } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "example": { "data": [ { "id": "1906385232743451", "verified_name": "Jasper's Market", "display_phone_number": "+1 631-555-5555", "quality_rating": "GREEN" }, { "id": "1913623884432103", "verified_name": "Jasper's Ice Cream", "display_phone_number": "+1 631-555-5556", "quality_rating": "NA" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{phone_number_id}": { "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "description": "WhatsApp Business Phone Number ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Phone Numbers" ], "summary": "Get phone number details", "description": "Retrieve detailed information about a specific phone number.\n\nBy default returns basic information. Use `fields` parameter to request additional data like throughput limits, account mode, certificate status, etc.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n", "operationId": "getPhoneNumber", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of fields to retrieve.\n\nAvailable fields: id, verified_name, display_phone_number, quality_rating, code_verification_status, is_official_business_account, name_status, new_name_status, platform_type, throughput, account_mode, certificate, messaging_limit_tier\n\nExample: `fields=id,verified_name,display_phone_number,quality_rating,throughput,messaging_limit_tier`\n", "schema": { "type": "string" }, "example": "id,verified_name,display_phone_number,quality_rating" } ], "responses": { "200": { "description": "Phone number details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Phone number ID" }, "verified_name": { "type": "string", "description": "Verified business name associated with the phone number" }, "display_phone_number": { "type": "string", "description": "Phone number in international format" }, "quality_rating": { "type": "string", "enum": [ "GREEN", "YELLOW", "RED", "NA", "UNKNOWN" ], "description": "Quality rating based on message delivery.\n- GREEN: High quality\n- YELLOW: Medium quality\n- RED: Low quality\n- NA: Not yet determined\n- UNKNOWN: Status unknown\n" }, "code_verification_status": { "type": "string", "description": "Verification status of the phone number" }, "is_official_business_account": { "type": "boolean", "description": "Whether this is an official business account" }, "name_status": { "type": "string", "description": "Status of the business name" }, "new_name_status": { "type": "string", "description": "Status of pending name change" }, "platform_type": { "type": "string", "description": "Platform type (CLOUD_API, etc.)" }, "throughput": { "type": "object", "description": "Messaging throughput limits", "properties": { "level": { "type": "string", "description": "Current throughput level" } } }, "account_mode": { "type": "string", "enum": [ "SANDBOX", "LIVE" ], "description": "Account mode (SANDBOX for testing, LIVE for production)" }, "certificate": { "type": "string", "description": "Certificate status" }, "messaging_limit_tier": { "type": "string", "description": "Current messaging limit tier (TIER_50, TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED)" } } }, "example": { "id": "1906385232743451", "verified_name": "Jasper's Market", "display_phone_number": "+1 631-555-5555", "quality_rating": "GREEN" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Phone Numbers" ], "summary": "Update phone number settings", "description": "Update phone number settings. Common use case is updating the two-step verification PIN.\n\n**Proxy endpoint**: Proxies directly to Meta Graph API.\n\n**Note**: Two-step verification is required for WhatsApp Business API. The PIN must be 6 digits.\n", "operationId": "updatePhoneNumber", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pin": { "type": "string", "pattern": "^\\d{6}$", "description": "6-digit PIN for two-step verification", "example": "123456" } }, "example": { "pin": "123456" } } } } }, "responses": { "200": { "description": "Phone number settings updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request (e.g., invalid PIN format)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }