WhatsApp Conversational Automation 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: Conversational Automation
  description: APIs for managing conversational automation settings and bot configurations
paths:
  /{Version}/{Phone-Number-ID}/conversational_automation:
    post:
      summary: Configure Conversational Automation
      description: 'Configure conversational automation settings for a WhatsApp Business Account phone number,

        including welcome messages, conversation prompts (ice breakers), and bot commands.


        **Use Cases:**

        - Set up automated welcome messages for new customer conversations

        - Configure conversation prompts to guide customer interactions

        - Define bot commands for common customer service scenarios

        - Update existing automation settings

        - Enable or disable specific automation features


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Validation:**

        - Command names must be unique within the same phone number

        - Prompts and command descriptions must comply with WhatsApp Business policies

        - Maximum limits are enforced for prompts and commands'
      operationId: configureConversationalAutomation
      tags:
      - Conversational Automation
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: 'Your WhatsApp Business phone number ID. This ID represents the phone number

          entity and can be obtained from your WhatsApp Business Account phone numbers list.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationalAutomationRequest'
            examples:
              enable_welcome_with_prompts:
                summary: Enable welcome message with conversation prompts
                value:
                  enable_welcome_message: true
                  prompts:
                  - How can I help you today?
                  - What product are you interested in?
                  commands: []
              setup_bot_commands:
                summary: Configure bot commands for customer service
                value:
                  enable_welcome_message: false
                  prompts: []
                  commands:
                  - command_name: help
                    command_description: Get help with your order
                  - command_name: status
                    command_description: Check your order status
                  - command_name: support
                    command_description: Contact customer support
              full_automation_setup:
                summary: Complete automation setup with all features
                value:
                  enable_welcome_message: true
                  prompts:
                  - Welcome! How can I assist you?
                  - Are you looking for product information?
                  - Do you need help with an existing order?
                  commands:
                  - command_name: catalog
                    command_description: View our product catalog
                  - command_name: hours
                    command_description: Check our business hours
                  - command_name: location
                    command_description: Find our store locations
              disable_automation:
                summary: Disable all automation features
                value:
                  enable_welcome_message: false
                  prompts: []
                  commands: []
      responses:
        '200':
          description: Successfully configured conversational automation settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationalAutomationResponse'
              examples:
                success_response:
                  summary: Successful configuration
                  value:
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_command_name:
                  summary: Invalid command name format
                  value:
                    error:
                      message: Invalid command name format. Command names must contain only alphanumeric characters and underscores
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                too_many_prompts:
                  summary: Exceeded maximum prompts limit
                  value:
                    error:
                      message: Too many prompts provided. Maximum allowed is 3
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                prompt_too_long:
                  summary: Prompt text exceeds character limit
                  value:
                    error:
                      message: Prompt text exceeds maximum length of 80 characters
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to manage conversational automation for this phone number
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                phone_not_verified:
                  summary: Phone number not verified
                  value:
                    error:
                      message: Phone number must be verified before configuring conversational automation
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                duplicate_command:
                  summary: Duplicate command names
                  value:
                    error:
                      message: 'Command names must be unique. Duplicate command name found: help'
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    BotCommand:
      type: object
      description: Bot command configuration for automated responses
      required:
      - command_name
      - command_description
      properties:
        command_name:
          type: string
          description: Name of the bot command (without leading slash)
          maxLength: 30
          pattern: ^[a-zA-Z0-9_]+$
          example: help
        command_description:
          type: string
          description: Description of what the command does
          maxLength: 256
          example: Get help with your order
    ConversationalAutomationResponse:
      type: object
      description: Response after successfully configuring conversational automation
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the automation configuration was successful
          example: true
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    ConversationalAutomationRequest:
      type: object
      description: Request payload for configuring conversational automation settings
      properties:
        enable_welcome_message:
          type: boolean
          description: Whether to enable welcome messages for new conversations
          default: false
          example: true
        prompts:
          type: array
          description: List of conversation prompts (ice breakers) to help guide customer interactions
          items:
            type: string
            maxLength: 80
            description: Individual conversation prompt text
            example: How can I help you today?
          maxItems: 3
          default: []
          example:
          - How can I help you today?
          - What product are you interested in?
          - Do you need support?
        commands:
          type: array
          description: List of bot commands for automated responses
          items:
            $ref: '#/components/schemas/BotCommand'
          maxItems: 30
          default: []
          example:
          - command_name: help
            command_description: Get help with your order
          - command_name: status
            command_description: Check your order status
  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
  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

        '