> ## 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

> Envía un mensaje con un botón que abre un WhatsApp Flow

<Note>
  El WhatsApp Flow debe existir previamente en Jelou para el bot indicado. Se referencia por su **slug** en `parameters.flow_name`. El `botId` y el número del destinatario (`userId`, sin el signo `+`) van ambos en la ruta. Disponible solo para bots con proveedor WhatsApp Cloud API, Gupshup CAPI o 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": "Hola",
      "text": "Completa este flujo para comenzar",
      "caption": "Jelou",
      "parameters": {
        "flow_name": "flujo_de_bienvenida",
        "flow_cta": "Iniciar Flujo",
        "flow_action_payload": {
          "screen": "RECOMMEND"
        }
      }
    }'
  ```
</RequestExample>

## Mejores Prácticas

<Note>
  **Flujos Complejos:** Usa botones de flujo para interacciones complejas de múltiples pasos que requieren entradas de formulario, selecciones o experiencias guiadas. Los flujos proporcionan una experiencia nativa de WhatsApp sin salir del chat.
</Note>

## Casos de Uso

* Formularios de registro o encuestas
* Procesos de compra multi-paso
* Configuraciones guiadas
* Experiencias interactivas complejas


## 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

````