Flow Templates

Flow templates integrate with WhatsApp Flows to provide interactive, multi-step experiences within WhatsApp. When the user taps the flow button, an in-app form or workflow opens directly within the WhatsApp chat, enabling use cases like appointment booking, lead generation, surveys, and customer feedback.

Prerequisites

Before creating flow templates, you must:

Create a WhatsApp Flow using Meta Business Suite or the WhatsApp Flows API. Follow the guide: Create a WhatsApp Flow.
Publish the flow -- a flow must be in the Published state before it can be used in an approved template. Draft flows can only be used for testing. See: Publishing and sending your flow.
Copy the flow ID -- after publishing, copy the flow ID from the WhatsApp Flows page in Bird. This ID is used as the id property in the flow action block.

Once a flow has been published it can no longer be modified. Make sure to test your flow thoroughly in Draft state before publishing.

Block Structure

A flow template uses a single whatsapp-flow block:

Component	Required	Description
Header	No	Text, image, or file header
Body text	Yes	Main message text (max 1024 characters)
Footer text	No	Text below the body (max 60 characters)
Flow action	Yes	Button that launches the WhatsApp Flow

Header

Flow templates support three optional header types:

Text header:

Przykład kodu

{
  "type": "text",
  "text": {
    "text": "Book Your Appointment"
  }
}

Image header:

Przykład kodu

{
  "type": "image",
  "image": {
    "mediaUrl": "https://example.com/images/booking.jpg"
  }
}

File/video header:

Przykład kodu

{
  "type": "file",
  "file": {
    "mediaUrl": "https://example.com/videos/intro.mp4",
    "contentType": "video/mp4"
  }
}

If you need to host media, use the Media Library API to upload files and get a mediaUrl. See Image Template Blocks -- Uploading media for the full upload flow.

Body

The body is mandatory and should explain what the flow does and encourage the user to tap the button.

Przykład kodu

{
  "type": "text",
  "text": {
    "text": "Ready to schedule your next appointment? Tap below to pick a date and time that works for you."
  }
}

Footer

Optional text footer, max 60 characters.

Przykład kodu

{
  "type": "text",
  "text": {
    "text": "Available Monday through Friday"
  }
}

Flow Action

The flow action creates a button that opens a WhatsApp Flow when tapped. It supports two action types: navigate and data_exchange.

Navigate action

Opens the flow and navigates directly to a specific screen. You can optionally pass initial data to the screen.

Przykład kodu

{
  "type": "whatsapp-flow-action",
  "whatsappFlowAction": {
    "id": "flow_abc123",
    "label": "Book now",
    "actionType": "navigate",
    "token": "optional_flow_token",
    "actionPayload": {
      "screen": "APPOINTMENT_SCREEN",
      "data": {
        "department": "sales"
      }
    }
  }
}

Property	Required	Description
id	Yes	The WhatsApp Flow ID (see Prerequisites)
label	Yes	Button text displayed to the user
actionType	Yes	Must be navigate
token	No	Optional token for flow session tracking
actionPayload.screen	Yes	The screen to navigate to when the flow opens
actionPayload.data	No	Initial data to pass to the screen

Data exchange action

Opens the flow and triggers a data exchange with your endpoint to determine the initial screen and data.

Przykład kodu

{
  "type": "whatsapp-flow-action",
  "whatsappFlowAction": {
    "id": "flow_abc123",
    "label": "Get started",
    "actionType": "data_exchange",
    "token": "optional_flow_token"
  }
}

Property	Required	Description
id	Yes	The WhatsApp Flow ID (see Prerequisites)
label	Yes	Button text displayed to the user
actionType	Yes	Must be data_exchange
token	No	Optional token for flow session tracking

Complete Example -- Event Registration

Przykład kodu

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "event_registration"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "customerName",
      "description": "Customer's first name",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["Alex"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "whatsapp-flow",
          "whatsappFlow": {
            "header": {
              "type": "text",
              "text": {
                "text": "Exclusive Launch Event"
              }
            },
            "body": {
              "type": "text",
              "text": {
                "text": "Hi {{customerName}}, you're invited to our exclusive product launch event! Register now to secure your spot and get early access to our newest collection."
              }
            },
            "footer": {
              "type": "text",
              "text": {
                "text": "Limited spots available"
              }
            },
            "action": {
              "type": "whatsapp-flow-action",
              "whatsappFlowAction": {
                "id": "1234567890",
                "label": "Register now",
                "actionType": "navigate",
                "actionPayload": {
                  "screen": "REGISTRATION_FORM",
                  "data": null
                }
              }
            }
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Complete Example -- Survey with Data Exchange

Przykład kodu

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "customer_survey"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "whatsapp-flow",
          "whatsappFlow": {
            "body": {
              "type": "text",
              "text": {
                "text": "We'd love your feedback! Take our quick 2-minute survey to help us improve our service."
              }
            },
            "action": {
              "type": "whatsapp-flow-action",
              "whatsappFlowAction": {
                "id": "9876543210",
                "label": "Start survey",
                "actionType": "data_exchange",
                "token": "survey_session_token"
              }
            }
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Text Template Blocks -- Standard text templates
Carousel Template Blocks -- Scrollable card-based templates
Creating WhatsApp Message Templates -- Full template creation workflow