openapi: 3.1.0 info: title: WhatsApp Business Management API description: >- The WhatsApp Business Management API enables programmatic management of WhatsApp Business Accounts, phone numbers, message templates, analytics, user assignments, product catalogs, and webhook subscriptions through the Meta Graph API. version: '21.0' contact: name: Meta Platform Support url: https://developers.facebook.com/support/ termsOfService: https://www.whatsapp.com/legal/business-terms externalDocs: description: WhatsApp Business Management API Documentation url: https://developers.facebook.com/docs/whatsapp/business-management-api servers: - url: https://graph.facebook.com/v21.0 description: Meta Graph API Production Server tags: - name: Analytics description: Retrieve conversation and template analytics - name: Assigned Users description: Manage user access to a WABA - name: Business Accounts description: Manage WhatsApp Business Account information - name: Message Templates description: Create, update, and delete message templates - name: Phone Numbers description: List and manage phone numbers on a WABA - name: Product Catalogs description: Connect and manage product catalogs - name: Subscribed Apps description: Manage webhook subscriptions for a WABA security: - bearerAuth: [] paths: /{waba-id}: get: operationId: getWhatsAppBusinessAccount summary: WhatsApp Get WABA Info description: Retrieves information about a WhatsApp Business Account. tags: - Business Accounts parameters: - $ref: '#/components/parameters/WabaId' - name: fields in: query description: Comma-separated list of fields to return schema: type: string example: example_value responses: '200': description: WABA info retrieved content: application/json: schema: $ref: '#/components/schemas/WhatsAppBusinessAccount' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/phone_numbers: get: operationId: listPhoneNumbers summary: WhatsApp List Phone Numbers description: Lists all phone numbers associated with a WhatsApp Business Account. tags: - Phone Numbers parameters: - $ref: '#/components/parameters/WabaId' - name: fields in: query description: Comma-separated fields to return schema: type: string example: example_value - name: limit in: query description: Pagination limit schema: type: integer example: 42 - name: after in: query description: Cursor for forward pagination schema: type: string example: example_value - name: before in: query description: Cursor for backward pagination schema: type: string example: example_value responses: '200': description: Phone numbers retrieved content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PhoneNumber' paging: $ref: '#/components/schemas/CursorPaging' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/message_templates: get: operationId: listMessageTemplates summary: WhatsApp List Message Templates description: Lists all message templates for a WhatsApp Business Account. tags: - Message Templates parameters: - $ref: '#/components/parameters/WabaId' - name: fields in: query schema: type: string example: example_value - name: limit in: query schema: type: integer default: 25 example: 42 - name: after in: query schema: type: string example: example_value - name: before in: query schema: type: string example: example_value - name: name in: query description: Filter by template name schema: type: string example: Example Business - name: language in: query description: Filter by language code schema: type: string example: en_US - name: status in: query description: Filter by approval status schema: type: string enum: - APPROVED - PENDING - REJECTED - PAUSED - DISABLED example: APPROVED - name: category in: query description: Filter by template category schema: type: string enum: - AUTHENTICATION - MARKETING - UTILITY example: AUTHENTICATION responses: '200': description: Templates retrieved content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/MessageTemplate' paging: $ref: '#/components/schemas/CursorPaging' x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: createMessageTemplate summary: WhatsApp Create Message Template description: >- Creates a new message template for a WhatsApp Business Account. Templates must be approved by Meta before they can be used to send messages. tags: - Message Templates parameters: - $ref: '#/components/parameters/WabaId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTemplateRequest' responses: '200': description: Template created content: application/json: schema: type: object properties: id: type: string status: type: string category: type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: deleteMessageTemplate summary: WhatsApp Delete Message Template description: >- Deletes a message template. Deleting by name removes all language variants. Pass hsm_id to delete a specific language version. tags: - Message Templates parameters: - $ref: '#/components/parameters/WabaId' - name: name in: query required: true description: Template name to delete schema: type: string example: Example Business - name: hsm_id in: query description: Specific template ID to delete a single language variant schema: type: string example: wamid.abc123 responses: '200': description: Template deleted content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{message-template-id}: post: operationId: updateMessageTemplate summary: WhatsApp Update Message Template description: >- Updates an existing message template. Only APPROVED or PAUSED templates can be edited. Edits re-trigger the approval process. tags: - Message Templates parameters: - name: message-template-id in: path required: true schema: type: string example: wamid.abc123 requestBody: required: true content: application/json: schema: type: object properties: components: type: array items: $ref: '#/components/schemas/TemplateComponentDefinition' category: type: string enum: - AUTHENTICATION - MARKETING - UTILITY responses: '200': description: Template updated content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/conversation_analytics: get: operationId: getConversationAnalytics summary: WhatsApp Get Conversation Analytics description: Retrieves conversation analytics for a WhatsApp Business Account. tags: - Analytics parameters: - $ref: '#/components/parameters/WabaId' - name: start in: query required: true description: Start time (Unix timestamp or YYYY-MM-DD) schema: type: string example: example_value - name: end in: query required: true description: End time (Unix timestamp or YYYY-MM-DD) schema: type: string example: example_value - name: granularity in: query required: true schema: type: string enum: - HALF_HOUR - DAILY - MONTHLY example: HALF_HOUR - name: phone_numbers in: query description: Filter by phone number IDs schema: type: array items: type: string - name: metric_types in: query schema: type: array items: type: string enum: - CONVERSATION - COST - name: conversation_categories in: query schema: type: array items: type: string enum: - AUTHENTICATION - MARKETING - UTILITY - SERVICE - REFERRAL_CONVERSION - name: dimensions in: query schema: type: array items: type: string enum: - CONVERSATION_CATEGORY - CONVERSATION_TYPE - COUNTRY - PHONE responses: '200': description: Analytics retrieved content: application/json: schema: $ref: '#/components/schemas/ConversationAnalytics' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/template_analytics: get: operationId: getTemplateAnalytics summary: WhatsApp Get Template Analytics description: Retrieves analytics for specific message templates. tags: - Analytics parameters: - $ref: '#/components/parameters/WabaId' - name: start in: query required: true schema: type: string example: example_value - name: end in: query required: true schema: type: string example: example_value - name: granularity in: query required: true schema: type: string enum: - DAILY example: DAILY - name: template_ids in: query required: true description: Template IDs to analyze (max 10) schema: type: array maxItems: 10 items: type: string - name: metric_types in: query schema: type: array items: type: string enum: - SENT - DELIVERED - READ - CLICKED - COST responses: '200': description: Template analytics retrieved content: application/json: schema: $ref: '#/components/schemas/TemplateAnalytics' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/subscribed_apps: get: operationId: listSubscribedApps summary: WhatsApp List Webhook Subscriptions description: Lists all apps subscribed to webhook events for this WABA. tags: - Subscribed Apps parameters: - $ref: '#/components/parameters/WabaId' responses: '200': description: Subscriptions retrieved content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string link: type: string name: type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: subscribeApp summary: WhatsApp Subscribe App to Webhooks description: Subscribes the current app to receive webhook events for this WABA. tags: - Subscribed Apps parameters: - $ref: '#/components/parameters/WabaId' responses: '200': description: App subscribed content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: unsubscribeApp summary: WhatsApp Unsubscribe App from Webhooks description: Unsubscribes the current app from webhook events. tags: - Subscribed Apps parameters: - $ref: '#/components/parameters/WabaId' responses: '200': description: App unsubscribed content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/assigned_users: get: operationId: listAssignedUsers summary: WhatsApp List Assigned Users description: Lists all users assigned to a WhatsApp Business Account. tags: - Assigned Users parameters: - $ref: '#/components/parameters/WabaId' responses: '200': description: Users retrieved content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string name: type: string tasks: type: array items: type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: assignUser summary: WhatsApp Assign User to WABA description: Assigns a user with specific tasks to a WhatsApp Business Account. tags: - Assigned Users parameters: - $ref: '#/components/parameters/WabaId' requestBody: required: true content: application/json: schema: type: object required: - user - tasks properties: user: type: string description: User ID to assign tasks: type: array items: type: string enum: - MANAGE - DEVELOP - MANAGE_TEMPLATES - MANAGE_PHONE - VIEW_COST - MANAGE_EXTENSIONS responses: '200': description: User assigned content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: removeAssignedUser summary: WhatsApp Remove Assigned User description: Removes a user from a WhatsApp Business Account. tags: - Assigned Users parameters: - $ref: '#/components/parameters/WabaId' requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: string responses: '200': description: User removed content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /{waba-id}/product_catalogs: get: operationId: listProductCatalogs summary: WhatsApp List Product Catalogs description: Lists product catalogs connected to a WABA. tags: - Product Catalogs parameters: - $ref: '#/components/parameters/WabaId' responses: '200': description: Catalogs retrieved content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string name: type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: connectProductCatalog summary: WhatsApp Connect Product Catalog description: Connects a product catalog to a WABA. tags: - Product Catalogs parameters: - $ref: '#/components/parameters/WabaId' requestBody: required: true content: application/json: schema: type: object required: - catalog_id properties: catalog_id: type: string responses: '200': description: Catalog connected content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: disconnectProductCatalog summary: WhatsApp Disconnect Product Catalog description: Disconnects a product catalog from a WABA. tags: - Product Catalogs parameters: - $ref: '#/components/parameters/WabaId' requestBody: required: true content: application/json: schema: type: object required: - catalog_id properties: catalog_id: type: string responses: '200': description: Catalog disconnected content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: securitySchemes: bearerAuth: type: http scheme: bearer description: System User Token with whatsapp_business_management permission parameters: WabaId: name: waba-id in: path required: true description: WhatsApp Business Account ID schema: type: string schemas: WhatsAppBusinessAccount: type: object properties: id: type: string example: wamid.abc123 name: type: string example: Example Business currency: type: string example: example_value timezone_id: type: string example: wamid.abc123 country: type: string example: example_value status: type: string enum: - ACTIVE - INACTIVE example: ACTIVE business_verification_status: type: string example: sent message_template_namespace: type: string example: Example Business owner_business: type: object properties: id: type: string name: type: string primary_funding_id: type: string example: wamid.abc123 purchase_order_number: type: string example: example_value PhoneNumber: type: object properties: id: type: string example: wamid.abc123 display_phone_number: type: string example: '+15551234567' verified_name: type: string example: Example Business quality_rating: type: string enum: - GREEN - YELLOW - RED - UNKNOWN example: GREEN code_verification_status: type: string enum: - VERIFIED - NOT_VERIFIED - EXPIRED example: VERIFIED is_official_business_account: type: boolean example: true name_status: type: string example: Example Business platform_type: type: string enum: - CLOUD_API - ON_PREMISE - NOT_APPLICABLE example: CLOUD_API throughput: type: object properties: level: type: string enum: - STANDARD - HIGH account_mode: type: string enum: - LIVE - SANDBOX example: LIVE messaging_limit_tier: type: string enum: - TIER_1K - TIER_10K - TIER_100K - TIER_UNLIMITED example: TIER_1K MessageTemplate: type: object properties: id: type: string example: wamid.abc123 name: type: string example: Example Business status: type: string enum: - APPROVED - PENDING - REJECTED - PAUSED - DISABLED example: APPROVED category: type: string enum: - AUTHENTICATION - MARKETING - UTILITY example: AUTHENTICATION language: type: string example: en_US components: type: array items: $ref: '#/components/schemas/TemplateComponentDefinition' parameter_format: type: string enum: - POSITIONAL - NAMED example: POSITIONAL quality_score: type: object properties: score: type: string CreateTemplateRequest: type: object required: - name - language - category - components properties: name: type: string description: Template name (lowercase, underscores only, max 512 chars) maxLength: 512 pattern: '^[a-z][a-z0-9_]*$' example: Example Business language: type: string description: Language code example: en_US category: type: string enum: - AUTHENTICATION - MARKETING - UTILITY example: AUTHENTICATION components: type: array items: $ref: '#/components/schemas/TemplateComponentDefinition' parameter_format: type: string enum: - POSITIONAL - NAMED example: POSITIONAL TemplateComponentDefinition: type: object required: - type properties: type: type: string enum: - HEADER - BODY - FOOTER - BUTTONS example: HEADER format: type: string enum: - TEXT - IMAGE - VIDEO - DOCUMENT - LOCATION description: Header format type example: TEXT text: type: string description: Component text content example: Hello from WhatsApp! example: type: object description: Example values for variables buttons: type: array items: $ref: '#/components/schemas/TemplateButton' add_security_recommendation: type: boolean description: Authentication templates only example: true code_expiration_minutes: type: integer description: Authentication templates only (1-90) minimum: 1 maximum: 90 example: 42 TemplateButton: type: object required: - type - text properties: type: type: string enum: - QUICK_REPLY - URL - PHONE_NUMBER - COPY_CODE - FLOW - OTP - CATALOG - MPM example: QUICK_REPLY text: type: string example: Hello from WhatsApp! url: type: string format: uri example: https://example.com/image.jpg phone_number: type: string example: '+15551234567' example: type: string example: example_value flow_id: type: string example: wamid.abc123 flow_action: type: string example: example_value navigate_screen: type: string example: example_value ConversationAnalytics: type: object properties: conversation_analytics: type: object properties: data: type: array items: type: object properties: data_points: type: array items: type: object properties: start: type: integer end: type: integer conversation: type: integer cost: type: number TemplateAnalytics: type: object properties: template_analytics: type: object properties: data: type: array items: type: object properties: template_id: type: string data_points: type: array items: type: object properties: start: type: integer end: type: integer sent: type: integer delivered: type: integer read: type: integer clicked: type: integer cost: type: number CursorPaging: type: object properties: cursors: type: object properties: before: type: string after: type: string next: type: string format: uri example: example_value previous: type: string format: uri example: example_value SuccessResponse: type: object properties: success: type: boolean example: true