WhatsApp Marketing Messages API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: Marketing Messages
  description: Send marketing template messages to WhatsApp users using pre-approved templates.
paths:
  /{Version}/{Phone-Number-ID}/marketing_messages:
    post:
      tags:
      - Marketing Messages
      summary: Send Marketing Template Message
      description: Send marketing template messages using pre-approved templates. Supports optional product policy controls and message activity sharing settings.
      operationId: sendMarketingMessage
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        description: WhatsApp API version (e.g., v20.0)
        schema:
          type: string
          example: v20.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: WhatsApp Business Phone Number ID
        schema:
          type: string
          example: '102290129340398'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketingMessageRequestPayload'
            examples:
              Simple Template Message:
                summary: Basic marketing template message
                value:
                  messaging_product: whatsapp
                  recipient_type: individual
                  to: '16315552222'
                  type: template
                  template:
                    name: hello_world
                    language:
                      code: en
              Template with Product Policy:
                summary: Template message with optional product policy
                value:
                  messaging_product: whatsapp
                  recipient_type: individual
                  to: '16315552222'
                  type: template
                  template:
                    name: welcome_offer
                    language:
                      code: en_US
                  product_policy: CLOUD_API_FALLBACK
                  message_activity_sharing: true
              Parameterized Template:
                summary: Template message with parameters
                value:
                  messaging_product: whatsapp
                  recipient_type: individual
                  to: '16315552222'
                  type: template
                  template:
                    name: promotional_offer
                    language:
                      code: en
                    components:
                    - type: body
                      parameters:
                      - type: text
                        text: John Doe
                      - type: currency
                        currency:
                          fallback_value: $25.00
                          code: USD
                          amount_1000: 25000
                  product_policy: STRICT
                  message_activity_sharing: false
      responses:
        '200':
          description: Marketing message sent successfully
          headers:
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/Access-Control-Allow-Origin'
            Alt-Svc:
              $ref: '#/components/headers/Alt-Svc'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Connection:
              $ref: '#/components/headers/Connection'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Date:
              $ref: '#/components/headers/Date'
            Expires:
              $ref: '#/components/headers/Expires'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Strict-Transport-Security:
              $ref: '#/components/headers/Strict-Transport-Security'
            Vary:
              $ref: '#/components/headers/Vary'
            X-FB-Connection-Quality:
              $ref: '#/components/headers/X-FB-Connection-Quality'
            X-FB-Debug:
              $ref: '#/components/headers/X-FB-Debug'
            facebook-api-version:
              $ref: '#/components/headers/facebook-api-version'
            x-business-use-case-usage:
              $ref: '#/components/headers/x-business-use-case-usage'
            x-fb-request-id:
              $ref: '#/components/headers/x-fb-request-id'
            x-fb-rev:
              $ref: '#/components/headers/x-fb-rev'
            x-fb-trace-id:
              $ref: '#/components/headers/x-fb-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketingMessageResponsePayload'
              examples:
                Successful Response:
                  summary: Successful marketing message response
                  value:
                    contacts:
                    - input: '16315552222'
                      wa_id: '16315552222'
                    messages:
                    - id: wamid.gBGGSFcCNEOPAgkO_KJ55r4w_ww
                    messaging_product: whatsapp
                    success: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
      - bearerAuth: []
components:
  schemas:
    TemplateComponent:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: Describes the component type.
          enum:
          - header
          - body
          - button
        sub_type:
          type: string
          description: Required when `type=button`. Not used for other types. Type of button to create.
          enum:
          - quick_reply
          - url
          - catalog
        parameters:
          type: array
          description: Array of parameter objects with the content of the message.
        index:
          type: string
          description: Required when `type=button`. Not used for other types. Position index of the button (0-9).
          pattern: ^[2-6, 11-14]$
          example: '0'
      discriminator:
        propertyName: type
        mapping:
          header: '#/components/schemas/HeaderComponent'
          body: '#/components/schemas/BodyComponent'
          button: '#/components/schemas/ButtonComponent'
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    TemplateObject:
      type: object
      required:
      - name
      - language
      properties:
        name:
          type: string
          description: Name of the template.
          example: TEMPLATE_NAME
        language:
          $ref: '#/components/schemas/LanguageObject'
          description: Contains a `language` object. Specifies the language the template may be rendered in
        components:
          type: array
          description: Array of `components` objects containing the parameters of the message.
          items:
            $ref: '#/components/schemas/TemplateComponent'
          example:
          - type: header
            parameters:
            - type: image
              image:
                link: http(s)://example.com/image.jpg
          - type: body
            parameters:
            - type: text
              text: Hello {{1}}! Your order of {{2}} is confirmed for {{3}}.
          - type: button
            sub_type: quick_reply
            index: '0'
            parameters:
            - type: payload
              payload: ORDER_DETAILS_CLICKED
    MarketingMessageRequestPayload:
      type: object
      additionalProperties: false
      properties:
        messaging_product:
          type: string
          description: Messaging service used. Must be "whatsapp"
          enum:
          - whatsapp
          example: whatsapp
        recipient_type:
          type: string
          description: Type of recipient. Must be "individual"
          enum:
          - individual
          example: individual
        to:
          type: string
          description: WhatsApp ID or phone number of the message recipient
          example: '16315552222'
        type:
          type: string
          description: Type of message. Must be "template" for marketing messages
          enum:
          - template
          const: template
        template:
          $ref: '#/components/schemas/TemplateObject'
        product_policy:
          type: string
          description: Optional product policy setting
          enum:
          - CLOUD_API_FALLBACK
          - STRICT
          example: CLOUD_API_FALLBACK
        message_activity_sharing:
          type: boolean
          description: Optional flag to control message activity sharing
          example: true
      required:
      - messaging_product
      - recipient_type
      - to
      - type
      - template
    ErrorObject:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the error
        type:
          type: string
          description: Error type classification
        code:
          type: integer
          description: Numeric error code
      required:
      - message
      - type
      - code
    MarketingMessageResponsePayload:
      type: object
      properties:
        contacts:
          type: array
          items:
            type: object
            properties:
              input:
                type: string
                example: '16315552222'
              wa_id:
                type: string
                example: '16315552222'
          example:
          - input: '16315552222'
            wa_id: '16315552222'
        messages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: wamid.gBGGSFcCNEOPAgkO_KJ55r4w_ww
              message_status:
                $ref: '#/components/schemas/MessageStatus'
          example:
          - id: wamid.gBGGSFcCNEOPAgkO_KJ55r4w_ww
            message_status: accepted
        messaging_product:
          type: string
          example: whatsapp
    LanguageObject:
      type: object
      required:
      - policy
      - code
      properties:
        policy:
          type: string
          description: The language policy the message should follow.
          enum:
          - deterministic
          example: deterministic
        code:
          type: string
          description: The code of the language or locale to use (e.g., `"en"`, `"en_US"`).
          example: en_US
    MessageStatus:
      type: string
      enum:
      - accepted
      - held_for_quality_assessment
      - paused
      description: 'The status of a WhatsApp message:

        - `accepted`: The message has been accepted by WhatsApp and is being processed

        - `held_for_quality_assessment`: The message is being held for quality assessment before delivery

        - `paused`: The message delivery has been paused

        '
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  headers:
    Content-Length:
      schema:
        type: string
        example: '25'
      description: Size of the response body in bytes
    x-fb-request-id:
      schema:
        type: string
        example: AGaOBl2yM-g8gdON-dhzl5y
      description: Unique identifier for the request for debugging purposes
    Expires:
      schema:
        type: string
        example: Sat, 01 Jan 2000 00:00:00 GMT
      description: Expiration date for cached responses
    Access-Control-Allow-Origin:
      schema:
        type: string
        example: '*'
      description: CORS policy allowing access from any origin
    x-fb-trace-id:
      schema:
        type: string
        example: E7riEe9OW2e
      description: Facebook trace identifier for request tracking
    Vary:
      schema:
        type: string
        example: Accept-Encoding
      description: Headers that affect caching and content negotiation
    x-business-use-case-usage:
      schema:
        type: string
        example: '{"102290129340398":[{"type":"whatsapp_business_management","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0},{"type":"whatsapp","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0}]}'
      description: Business use case usage metrics and rate limiting information
    X-FB-Debug:
      schema:
        type: string
        example: 52zkUgodnaVRhbBE+3RiGz6TnmjmDEGunwYd+vKSc4synE+Xii//dy6twB/7yKgOJiMUuV0OF248UAZ1qL3v0A==
      description: Facebook debug information for troubleshooting
    Connection:
      schema:
        type: string
        example: keep-alive
      description: Connection management directive
    facebook-api-version:
      schema:
        type: string
        example: v22.0
      description: Facebook Graph API version used for the request
    Strict-Transport-Security:
      schema:
        type: string
        example: max-age=15552000; preload
      description: HSTS header enforcing HTTPS connections
    X-FB-Connection-Quality:
      schema:
        type: string
        example: EXCELLENT; q=0.9, rtt=7, rtx=0, c=10, mss=1380, tbw=372, tp=-1, tpl=-1, uplat=527, ullat=0
      description: Facebook connection quality metrics
    Pragma:
      schema:
        type: string
        example: no-cache
      description: Legacy cache control directive
    Alt-Svc:
      schema:
        type: string
        example: h3=":443"; ma=86400
      description: Alternative service advertisement for HTTP/3
    Cache-Control:
      schema:
        type: string
        example: private, no-cache, no-store, must-revalidate
      description: Cache control directives for the response
    Date:
      schema:
        type: string
        example: Fri, 24 Jan 2025 00:48:41 GMT
      description: Date and time when the response was generated
    x-fb-rev:
      schema:
        type: string
        example: '1019544279'
      description: Facebook internal revision number
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidAccessToken:
              summary: Invalid OAuth access token
              value:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
            MissingAccessToken:
              summary: Missing access token
              value:
                error:
                  message: An access token is required to request this resource
                  type: OAuthException
                  code: 104
    BadRequest:
      description: Bad Request - Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidTemplateParameters:
              summary: Invalid template name or parameters
              value:
                error:
                  message: Invalid template name or parameters
                  type: OAuthException
                  code: 100
            MalformedRequest:
              summary: Malformed request body
              value:
                error:
                  message: Invalid JSON in request body
                  type: OAuthException
                  code: 100
            MissingFeatureSetting:
              summary: One feature setting must be specified
              value:
                error:
                  message: One feature setting must be specified
                  type: OAuthException
                  code: 100
    Forbidden:
      description: Forbidden - Template not approved or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            TemplateNotApproved:
              summary: Template not approved for marketing use
              value:
                error:
                  message: Template not approved for marketing use
                  type: OAuthException
                  code: 200
            InsufficientPermissions:
              summary: Insufficient permissions for this operation
              value:
                error:
                  message: This operation requires additional permissions
                  type: OAuthException
                  code: 200
            FeatureNotSupported:
              summary: Feature not supported
              value:
                error:
                  message: Not supported
                  type: OAuthException
                  code: 10
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '