Skip to main content

Dynamic Application Configuration

A core feature of the WhatsApp Agent is its ability to be configured dynamically using simple YAML files. This allows you to define conversation entry points (Triggers), user interactions (Flows), and data integrations (CRM Mappings) without changing or redeploying the application's code.

The application reads its configuration from three key directories at startup: triggers/, flows/, and crm_mappings/.

Trigger Definitions (triggers/)​

The triggers/ directory is the starting point for all user interactions. Files in this directory define how the agent should respond when a user sends a message for the first time or wants to start a new conversation.

Structure of a Trigger Definition File​

Each YAML file in the triggers/ directory defines a single conversation entry point.

triggers/service_request.yaml
name: "service_request"
phrases:
  - "hi"
  - "hello"
  - "I need coupons"
initial_template: "welcome_service_request"
priority: 10
replies:
  - id: "start_flow_button"
    action: "start_flow"
    value: "order_medicines"
  - id: "Chat with Experts"
    action: "send_template"
    value: "chat_with_expert_holding_message"
    # This reply sends a template and also notifies the CRM that a lead was captured.
    notify_crm: true
  • name: A unique name for this trigger. This is used internally to track the user's journey.
  • phrases: A list of case-insensitive phrases that will activate this trigger. The system automatically normalizes user input (lowercase, removes punctuation) before matching.
  • initial_template: The name of the initial WhatsApp template message to send when this trigger is activated. This template should contain interactive buttons whose IDs match the id fields in the replies section below.
  • priority (Optional): A number that determines which trigger to use if a phrase is defined in multiple files. The trigger with the higher priority wins. Defaults to 0.
  • replies: A list of actions that can be taken when the user clicks a button on the initial_template.
    • id: The unique ID of the button in your WhatsApp template.
    • action: The action to perform. Can be start_flow or send_template.
    • value: The target of the action.
      • If action is start_flow, value is the name of the flow file in the flows/ directory (e.g., order_medicines).
      • If action is send_template, value is the name of another WhatsApp template to send.
    • notify_crm (Optional): If set to true, this action will also send a notification to the CRM, capturing the user as a lead. This is useful for tracking interest even if the user doesn't complete a full flow.

Flow Definitions (flows/)​

The flows/ directory contains YAML files that define the WhatsApp Flows you want to send to users. Each file in this directory represents a single flow.

The filename is important: it becomes the flow_type identifier used throughout the system. For example, a file named order_medicines.yaml corresponds to the order_medicines flow type.

Structure of a Flow Definition File​

Each flow definition file has a simple structure:

flows/order_medicines.yaml
flow_id: "YOUR_MEDICINE_FLOW_ID_FROM_META"
screen_id: "MEDICINE_ORDER"
header_text: "Order Your Medicines"
body_text: "Please tap below to fill in your details and upload a prescription."
footer_text: "Powered by WhatsApp Agent"
cta_text: "Order Now"

Each key defines a part of the interactive message that prompts the user to open the flow:

  • flow_id: The unique ID for your WhatsApp Flow. You get this from the Meta for Developers portal after publishing your flow.
  • screen_id: The identifier for the specific screen within your Flow that you want the user to see first. For a multi-step flow (e.g., Form -> Terms -> Review), this would be the ID of the initial form screen. The navigation to subsequent screens is handled within the Flow JSON itself, not in this configuration.
  • header_text: The bold title text at the top of the message bubble.
  • body_text: The main text content of the message, explaining what the flow is for.
  • footer_text: Smaller text at the bottom of the message bubble, often used for branding.
  • cta_text: The text on the clickable button that launches the Flow (e.g., "Open Form").

CRM Mappings (crm_mappings/)​

The crm_mappings/ directory contains YAML files that define how data from a submitted flow should be mapped to your CRM.

The filename of a mapping file must correspond to the filename of a flow definition or the reply id in case of triggers. For example, crm_mappings/order_medicines.yaml contains the mapping rules for the flow defined in flows/order_medicines.yaml and crm_mappings/chat_with_expert.yaml contains mapping rules for the reply id "Chat with Experts" defined in triggers/service_request.yaml.

Structure of a CRM Mapping File​

Note: The current CRM adapter is designed for Frappe-based CRMs (like ERPNext). The configuration below is specific to Frappe's API.

Each mapping file defines the target CRM object and how to populate its fields:

crm_mappings/order_medicines.yaml
doctype: "Lead"
static_fields:
  source: "WhatsApp"
  lead_status: "New"
field_map:
  full_name: "customer_name"
  address: "delivery_address"
  prescription_id: "uploaded_prescription_id"
  • doctype: The name of the target object, table, or document type in your CRM (e.g., "Lead", "Contact", "Ticket").
  • static_fields: A dictionary of key-value pairs that will be added to every CRM record created from this flow. This is useful for setting default values.
  • field_map: A dictionary that maps fields from the WhatsApp Flow's data to fields in the CRM. The structure is crm_field_name: flow_data_field_name.
    • Source Fields: The flow_data_field_name can be a key from your flow's data payload. Additionally, the system provides special properties from the user's session that you can map:
      • session_user_name: The user's WhatsApp profile name.
      • session_phone_number: The user's phone number.
    • File Uploads: If a source field corresponds to a file upload (e.g., a field in your flow with the value __FILE_UPLOAD__), the agent will automatically replace it with a comma-separated string of S3 URIs for the uploaded file(s). For example, s3://your-bucket/folder/file1.pdf,s3://your-bucket/folder/file2.jpg.