> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Whatsapp Flows

> Envie uma mensagem com um botão que abre um WhatsApp Flow

<Note>
  O WhatsApp Flow deve existir previamente no Jelou para o bot indicado. É referenciado pelo seu **slug** em `parameters.flow_name`. O `botId` e o número do destinatário (`userId`, sem o sinal `+`) vão ambos na rota. Disponível apenas para bots com provedor WhatsApp Cloud API, Gupshup CAPI ou Aldeamo.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.jelou.ai/v1/bots/BOT_ID/users/593987654321/flow_message \
    --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "Olá",
      "text": "Complete este fluxo para começar",
      "caption": "Jelou",
      "parameters": {
        "flow_name": "fluxo_de_boas_vindas",
        "flow_cta": "Iniciar Fluxo",
        "flow_action_payload": {
          "screen": "RECOMMEND"
        }
      }
    }'
  ```
</RequestExample>

## Boas Práticas

<Note>
  **Fluxos Complexos:** Use botões de fluxo para interações complexas de várias etapas que exigem entradas de formulário, seleções ou experiências guiadas. Os fluxos proporcionam uma experiência nativa do WhatsApp sem sair do chat.
</Note>

## Casos de Uso

* Formulários de cadastro ou pesquisas
* Processos de compra em várias etapas
* Configurações guiadas
* Experiências interativas complexas


## OpenAPI

````yaml POST /v1/bots/{botId}/users/{userId}/flow_message
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
paths:
  /v1/bots/{botId}/users/{userId}/flow_message:
    post:
      tags:
        - Messages
      summary: Send WhatsApp Flow
      description: >-
        Send a WhatsApp message with a button that opens a WhatsApp Flow. The
        Flow must already exist in Jelou for the target bot (referenced by its
        slug in `parameters.flow_name`). Only available for bots on WhatsApp
        Cloud API, Gupshup CAPI or Aldeamo providers.
      operationId: sendWhatsappFlowMessage
      parameters:
        - name: botId
          in: path
          required: true
          description: Identifier of the bot whose WhatsApp channel sends the message.
          schema:
            type: string
          example: BOT_ID
        - name: userId
          in: path
          required: true
          description: Recipient's phone number, without the + sign.
          schema:
            type: string
          example: '593987654321'
        - name: type
          in: query
          required: false
          description: Type of WhatsApp Flow to send. Defaults to the standard flow type.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowMessageRequest'
      responses:
        '200':
          description: Flow message sent
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    FlowMessageRequest:
      type: object
      required:
        - title
        - text
        - caption
        - parameters
      properties:
        title:
          type: string
          description: Header shown above the Flow button.
          example: Hello
        text:
          type: string
          description: Body text shown above the Flow button.
          example: Complete this flow to get started
        caption:
          type: string
          description: Footer text shown below the Flow button.
          example: Jelou
        parameters:
          $ref: '#/components/schemas/FlowParameters'
        payload:
          type: object
          additionalProperties: true
          description: Optional extra context cached and returned with the Flow reply.
    FlowParameters:
      type: object
      required:
        - flow_name
        - flow_cta
        - flow_action_payload
      properties:
        flow_name:
          type: string
          description: Slug (name) of the WhatsApp Flow created in Jelou for this bot.
          example: welcome_flow
        flow_cta:
          type: string
          maxLength: 30
          description: Text shown on the button that opens the Flow (max 30 characters).
          example: Open form
        flow_action_payload:
          type: object
          required:
            - screen
          description: Navigation payload sent to the Flow when it opens.
          properties:
            screen:
              type: string
              description: Id of the initial Flow screen to render.
              example: RECOMMEND
            data:
              type: object
              additionalProperties: true
              description: Optional data to prefill into the initial Flow screen.
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
  responses:
    BadRequest:
      description: Bad request - Invalid format or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret

````