> For the complete documentation index, see [llms.txt](https://docs.otima.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otima.io/whatsapp/recursos-de-api/flows.md).

# Flows

Os Flows são um recurso avançado da API do WhatsApp que permitem criar experiências interativas e estruturadas diretamente dentro da conversa com o usuário.

Diferente de mensagens tradicionais (texto ou botões simples), os Flows funcionam como **fluxos guiados**, permitindo coletar dados, conduzir o usuário por etapas e executar ações com base nas respostas — tudo sem sair do WhatsApp.

#### Por que usar Flows?

Flows foram projetados para transformar conversas em **experiências completas**, permitindo que sua aplicação:

* Colete informações de forma estruturada
* Crie formulários interativos dentro do chat
* Automatize jornadas de atendimento
* Reduza a necessidade de redirecionamento para sites externos

Na prática, é como ter um formulário ou sistema dentro do próprio WhatsApp.

<figure><img src="https://3723060873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fech0v4OAuw7OeuwoISIc%2Fuploads%2FGik9P1D3Yb769XE3mEqJ%2Fimage.png?alt=media&amp;token=9ef92321-4036-4d82-ba6c-f573810aea88" alt=""><figcaption></figcaption></figure>

#### Como funciona um Flow

Um Flow é composto por uma sequência de telas (steps), onde cada tela pode:

* Exibir informações
* Solicitar dados do usuário
* Direcionar para a próxima etapa

O fluxo segue até uma tela final (terminal), onde os dados são enviados para sua aplicação.

<figure><img src="https://3723060873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fech0v4OAuw7OeuwoISIc%2Fuploads%2Fen8nQF9Fea1KX8DTqVQm%2Fimage.png?alt=media&amp;token=b69d8020-9077-42d4-8963-17d28b3617b5" alt=""><figcaption></figcaption></figure>

#### Tipos de Flows

**Flows Estáticos**

* Estrutura fixa
* Sem integração com backend externo
* Ideal para fluxos simples

**Flows Dinâmicos e Endpoint**

Flows dinâmicos exigem um **endpoint configurado**, que será responsável por:

* Receber dados das interações
* Processar regras de negócio
* Definir a próxima tela do fluxo
* Retornar dados dinâmicos

### 1. Criar um WhatsApp Flow <a href="#user-content-1-criar-um-whatsapp-flow" id="user-content-1-criar-um-whatsapp-flow"></a>

Cria a estrutura do Flow no WhatsApp Business (Meta), realiza o upload das telas (`json`) e cadastra o registro na plataforma.

* **Método**: `POST`
* **Endpoint**: `https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows`

#### Parâmetros do Body: <a href="#user-content-parametros-do-body" id="user-content-parametros-do-body"></a>

| Campo          | Tipo    | Obrigatório | Descrição                                                                                                           |
| -------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`         | string  | **Sim**     | Nome do Flow (visível no painel da Meta).                                                                           |
| `waba_id`      | string  | **Sim**     | ID da WABA (WhatsApp Business Account) ou UUID interno.                                                             |
| `categories`   | array   | Não         | Categorias do Flow. Padrão: `["OTHER"]`. Opções: `["CUSTOMER_SUPPORT"]`, `["SIGN_UP"]`, `["LEAD_GENERATION"]`, etc. |
| `json`         | object  | **Sim**     | Schema das telas e lógica do Flow conforme padrão Meta.                                                             |
| `publish`      | boolean | Não         | Se `true`, realiza a publicação imediata do Flow na Meta após o upload.                                             |
| `endpoint_uri` | string  | Não         | URL HTTPS para troca dinâmica de dados via Webhook (se houver).                                                     |

#### Exemplo de Requisição (cURL): <a href="#user-content-exemplo-de-requisicao-curl" id="user-content-exemplo-de-requisicao-curl"></a>

```http
curl --location 'https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {SEU_TOKEN_API}' \
--header 'x-workspace-uuid: {UUID_DO_WORKSPACE}' \
--data '{
    "name": "Pesquisa de Satisfação",
    "waba_id": "100234567890123",
    "categories": [
        "OTHER"
    ],
    "endpoint_uri": "https://exemplewebhook.com/api/v1/whatsapp/flows/callback",
    "publish": true,
    "json": {
        "version": "7.2",
        "data_api_version": "3.0",
        "routing_model": {},
        "screens": [
            {
                "id": "QUESTION_1",
                "title": "Avaliação de Atendimento",
                "layout": {
                    "type": "SingleColumnLayout",
                    "children": [
                        {
                            "type": "Form",
                            "name": "flow_form",
                            "children": [
                                {
                                    "type": "TextHeading",
                                    "text": "Como você avalia nosso atendimento?"
                                },
                                {
                                    "type": "RadioButtonsGroup",
                                    "name": "rating",
                                    "label": "Selecione uma nota",
                                    "required": true,
                                    "data-source": [
                                        { "id": "5", "title": "⭐ ⭐ ⭐ ⭐ ⭐ Excelente" },
                                        { "id": "4", "title": "⭐ ⭐ ⭐ ⭐ Bom" },
                                        { "id": "3", "title": "⭐ ⭐ ⭐ Regular" },
                                        { "id": "2", "title": "⭐ ⭐ Ruim" },
                                        { "id": "1", "title": "⭐ Péssimo" }
                                    ]
                                },
                                {
                                    "type": "Footer",
                                    "label": "Enviar Resposta",
                                    "on-click-action": {
                                        "name": "data_exchange",
                                        "payload": {
                                            "rating": "${form.rating}"
                                        }
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}'

```

#### Exemplo de Resposta (`201 Created`): <a href="#user-content-exemplo-de-resposta-201-created" id="user-content-exemplo-de-resposta-201-created"></a>

```json
{
  "data": {
    "id": "1474114767752219",
    "uuid": "9b8f4a12-1234-4abc-9def-123456789abc",
    "wa_id": "1474114767752219",
    "waba_id": "100234567890123",
    "waba_name": "Minha Empresa WABA",
    "name": "Pesquisa de Satisfação",
    "status": "DRAFT",
    "categories": [
      "OTHER"
    ],
    "validation_errors": [],
    "json_version": "7.2",
    "data_api_version": "3.0",
    "endpoint_uri": null,
    "preview_url": "https://facebook.com/platform/whatsapp/flow/preview/1474114767752219",
    "application_id": null,
    "json": {
      "version": "7.2",
      "data_api_version": "3.0",
      "routing_model": {},
      "screens": [...]
    },
    "is_published": false,
    "is_draft": true,
    "is_deprecated": false,
    "created_at": "2026-07-31T22:40:00.000000Z",
    "updated_at": "2026-07-31T22:40:00.000000Z"
  }
}

```

***

### 2. Editar WhatsApp Flow

Atualiza um Flow em rascunho.

* **Método**: `PUT`
* **Endpoint**:

```http
https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}
```

Envie `Authorization: Bearer {token}` e `x-workspace-uuid: {workspace_uuid}`.

Somente Flows com status `DRAFT` podem ser editados. `name`, `waba_id` e `business_id` são imutáveis. Não altere esses campos.

#### Campos editáveis

| Campo              | Tipo                  | Obrigatório | Descrição                                                  |
| ------------------ | --------------------- | ----------- | ---------------------------------------------------------- |
| `categories`       | array                 | Não         | Categorias do Flow.                                        |
| `endpoint_uri`     | string ou `null`      | Não         | URL HTTPS do endpoint dinâmico. Use `null` para removê-la. |
| `screens`          | array                 | Não         | Telas atualizadas do Flow.                                 |
| `flow_json`        | objeto                | Não         | Schema completo do Flow.                                   |
| `json`             | objeto ou string JSON | Não         | Schema do Flow como objeto ou JSON serializado.            |
| `publish`          | boolean               | Não         | Publica o Flow após a atualização.                         |
| `workspace_uuid`   | string                | Não         | Workspace de destino em contexto administrativo.           |
| `is_administrator` | boolean               | Não         | Indica contexto administrativo.                            |

#### Exemplo de requisição (cURL)

```bash
curl --location --request PUT 'https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {token}' \
  --header 'x-workspace-uuid: {workspace_uuid}' \
  --data '{
    "categories": ["OTHER"],
    "endpoint_uri": null,
    "screens": [
      {
        "id": "START",
        "title": "Início"
      }
    ]
  }'
```

#### Exemplo de resposta (`200 OK`)

```json
{
  "data": {
    "id": "{id}",
    "status": "DRAFT",
    "categories": ["OTHER"],
    "endpoint_uri": null
  }
}
```

***

### 3. Remover WhatsApp Flow

Remove permanentemente um Flow em rascunho.

* **Método**: `DELETE`
* **Endpoint**:

```http
https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}
```

Use esta operação somente em Flows `DRAFT`. A remoção é irreversível.

Envie `Authorization: Bearer {token}` e `x-workspace-uuid: {workspace_uuid}`.

#### Exemplo de requisição (cURL)

```bash
curl --location --request DELETE 'https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {token}' \
  --header 'x-workspace-uuid: {workspace_uuid}'
```

#### Exemplo de resposta de sucesso

```json
{
  "success": true,
  "message": "Flow removido com sucesso."
}
```

***

### 4. Publicar WhatsApp Flow

Publica um Flow `DRAFT` após a validação da Meta.

* **Método**: `POST`
* **Endpoint**:

```http
https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}/publish
```

Teste o Flow antes de publicá-lo. Depois da publicação, não é possível editar sua estrutura ou nome.

Envie `Authorization: Bearer {token}` e `x-workspace-uuid: {workspace_uuid}`.

#### Exemplo de requisição (cURL)

```bash
curl --location --request POST 'https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows/{id}/publish' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {token}' \
  --header 'x-workspace-uuid: {workspace_uuid}'
```

#### Exemplo de resposta (`200 OK`)

```json
{
  "data": {
    "id": "{id}",
    "status": "PUBLISHED",
    "is_published": true
  }
}
```

***

### 5. Listar WhatsApp Flows <a href="#user-content-2-listar-whatsapp-flows" id="user-content-2-listar-whatsapp-flows"></a>

Retorna uma lista paginada dos Flows cadastrados no Workspace.

* **Método**: `GET`
* **Endpoint**: `https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows`

#### Parâmetros Query (Opcionais): <a href="#user-content-parametros-query-opcionais" id="user-content-parametros-query-opcionais"></a>

| Parâmetro  | Tipo    | Descrição                                              |
| ---------- | ------- | ------------------------------------------------------ |
| `waba_id`  | string  | Filtra os flows por uma WABA específica.               |
| `status`   | string  | Filtra por status: `DRAFT`, `PUBLISHED`, `DEPRECATED`. |
| `search`   | string  | Busca textual pelo nome do Flow.                       |
| `per_page` | integer | Quantidade por página (padrão: 50).                    |
| `page`     | integer | Número da página (padrão: 1).                          |

#### Exemplo de Requisição (cURL): <a href="#user-content-exemplo-de-requisicao-curl-1" id="user-content-exemplo-de-requisicao-curl-1"></a>

```http
curl --location 'https://sync-core-api.otima.io/whatsapp/provider/whatsapp-flows?status=DRAFT&per_page=10' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {SEU_TOKEN_API}' \
--header 'x-workspace-uuid: {UUID_DO_WORKSPACE}'
```

#### Exemplo de Resposta (`200 OK`): <a href="#user-content-exemplo-de-resposta-200-ok" id="user-content-exemplo-de-resposta-200-ok"></a>

{% code overflow="wrap" %}

```json
{
  "data": [
    {
      "id": "1474114767752219",
      "uuid": "9b8f4a12-1234-4abc-9def-123456789abc",
      "wa_id": "1474114767752219",
      "waba_id": "100234567890123",
      "waba_name": "Minha Empresa WABA",
      "name": "Pesquisa de Satisfação",
      "status": "DRAFT",
      "categories": [
        "OTHER"
      ],
      "validation_errors": [],
      "json_version": "7.2",
      "data_api_version": "3.0",
      "endpoint_uri": null,
      "preview_url": "https://facebook.com/platform/whatsapp/flow/preview/1474114767752219",
      "application_id": null,
      "is_published": false,
      "is_draft": true,
      "is_deprecated": false,
      "created_at": "2026-07-31T22:40:00.000000Z",
      "updated_at": "2026-07-31T22:40:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

```

{% endcode %}

#### Envios de Flows <a href="#envios-de-templates" id="envios-de-templates"></a>

URL Base de envio de flows:

```http
POST https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/send-message
```

### Estrutura para o Envio (payload) <a href="#estrutura-para-o-envio" id="estrutura-para-o-envio"></a>

#### Exemplo 1 — Flow NPS

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "flow": {
      "flow_id": "1652337649290145",
      "flow_token": "nps-20260409-001"
    }
  }
}
```

#### Exemplo 2 — Flow CSAT

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "flow": {
      "flow_id": "2325296217958791",
      "flow_token": "csat-20260409-001"
    }
  }
}
```

#### Exemplo 3 — Flow com contexto (recomendado)

Use um `flow_token` mais inteligente pra rastrear:

```json
{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "flow": {
      "flow_id": "1652337649290145",
      "flow_token": "user_5543999056041_order_98765"
    }
  }
}
```

***

#### Envio de Flow via Template (Botão)

#### Exemplo 4 — Template com botão que abre Flow

```json
{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "template_nps_flow",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "João"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_id": "1652337649290145",
              "flow_token": "nps-template-001"
            }
          }
        ]
      }
    ]
  }
}
```

***

#### Exemplo 5 — Template CSAT com botão

```json
{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "template_csat",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_id": "2325296217958791",
              "flow_token": "csat-template-001"
            }
          }
        ]
      }
    ]
  }
}
```

***

#### Parâmetros importantes

| Campo       | Obrigatório | Descrição                       |
| ----------- | ----------- | ------------------------------- |
| to          | ✅           | Número do destinatário          |
| type        | ✅           | `interactive` ou `template`     |
| flow\_id    | ✅           | ID do Flow na Meta              |
| flow\_token | ✅           | Identificador único da execução |

***

***

### 6. Criptografia e chave pública no WhatsApp Flows (`whatsapp_business_encryption`)

Flows com **`data_exchange`** trocam dados com um backend externo via **`endpoint_uri`**.

Nessa modalidade, a Meta exige criptografia de ponta a ponta. Cadastre uma chave pública RSA de 2048 bits para o número do WhatsApp Business. A Meta usa essa chave para criptografar o envelope da sessão antes de enviá-lo ao seu servidor.

#### 1. Cadastrar ou atualizar a chave pública

Cadastre ou atualize a chave pública RSA de 2048 bits do número na Meta.

* **Método:** `POST` ou `PUT`
* **Endpoint:**

{% code overflow="wrap" %}

```http
https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/whatsapp_business_encryption
```

{% endcode %}

* **Alias:**

{% code overflow="wrap" %}

```http
https://sync-core-api.otima.io/whatsapp/provider/{NUMERO_AQUI}/public-key
```

{% endcode %}

* **Autenticação:** Bearer Token

**Parâmetros de path**

<table><thead><tr><th>Parâmetro</th><th>Tipo</th><th align="center">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><pre><code>NUMERO_AQUI
</code></pre></td><td><code>string</code></td><td align="center"><strong>Sim</strong></td><td>Exemplo: <code>551147999999</code>.</td></tr></tbody></table>

**Parâmetros do corpo**

<table><thead><tr><th width="211.9896240234375">Campo</th><th>Tipo</th><th width="156.375" align="center">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>business_public_key</code></td><td><code>string</code></td><td align="center"><strong>Sim</strong></td><td>Chave pública RSA de 2048 bits no formato PEM. Também aceita <code>public_key</code> ou <code>key</code>.</td></tr></tbody></table>

#### **Gerar o par de chaves RSA**

Execute estes comandos no backend. Mantenha `private.pem` em segredo. Ela descriptografa os callbacks recebidos.

```bash
# Gera a chave privada.
openssl genrsa -out private.pem 2048

# Extrai a chave pública PEM para business_public_key.
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```

**Exemplo de requisição**

```bash
curl -X POST "https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/whatsapp_business_encryption" \
  -H "Authorization: Bearer {SEU_TOKEN_API}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2or263hkSyUy1RNhUeu5\nRfhO1LaIIL2WcSFEHVMjrJK/tmOCA1tHZ85jtaX/yq3zLygPH9tZWAMXYLMQvj16\nqXT8MpoeuL4D8jPKC1BKvASVI5vDzcwT0XqrtgMjibTy5cL2JJJCysW2PDft+Zia\nRRAISZzIIWliTg19+2TfaC8BLKFMj8ObFdgbX38/VOQ68KaMdZPlLw7hVcTyN7po\niQ070rx9CmxsiPepHyjLB7uU8LYvfs9Vs1E1YTwXqf/ryn/a2ISHC/UslnxnCWzv\n82WQdm1K+LJXkPfhGn8amP5cDVN+HAxNXiE33JQ0WYqjkRx/kh+25JcMSWN7YcWu\nlQIDAQAB\n-----END PUBLIC KEY-----"
  }'
```

**Exemplo de resposta (`200 OK`)**

```json
{
  "success": true,
  "message": "Chave pública enviada e registrada com sucesso na Meta.",
  "data": {
    "phone_number_id": "551199999999",
    "meta_response": {
      "success": true
    }
  }
}
```

#### 2. Consultar a configuração de criptografia

Consulte a chave pública atualmente registrada para o número.

* **Método:** `GET`
* **Endpoint:**

{% code overflow="wrap" %}

```http
https://sync-core-api.otima.io/whatsapp/provider/{NUMERO_AQUI}/whatsapp_business_encryption
```

{% endcode %}

* **Alias:**

{% code overflow="wrap" %}

```http
https://sync-core-api.otima.io/whatsapp/provider/{NUMERO_AQUI}/public-key
```

{% endcode %}

* **Autenticação:** Bearer Token

**Exemplo de requisição**

```bash
curl -X GET "https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/whatsapp_business_encryption" \
  -H "Authorization: Bearer {SEU_TOKEN_API}" \
  -H "Content-Type: application/json"
```

**Exemplo de resposta (`200 OK`)**

```json
{
  "business_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2or263hkSyUy1RNhUeu5...\n-----END PUBLIC KEY-----"
}
```

#### 3. Processar callbacks criptografados

Quando uma pessoa interage com um Flow dinâmico, o processo ocorre assim:

1. A Meta usa **`business_public_key`** para criptografar a chave AES e o payload.
2. A Meta envia um `POST` em JSON para o `endpoint_uri` do Flow.
3. Seu servidor usa `private.pem` e `RSA-OAEP` com SHA-256. Ele obtém a chave AES e descriptografa `encrypted_flow_data` com `AES-GCM-128`.
4. Seu servidor inverte os bits do vetor de inicialização (`IV XOR 0xFF`). Em seguida, criptografa a resposta e a retorna em Base64.

Retorne `HTTP 200 OK` com `Content-Type: text/plain`. Use um schema Meta v3.0 compatível: `ping`, `data_exchange`, `extension_message_response` ou `error_message`.

***

#### cURL exemplo de envio de Mensagem (`send-message`) usando `data_exchange` <a href="#user-content--curl-completo-de-envio-de-mensagem-send-message" id="user-content--curl-completo-de-envio-de-mensagem-send-message"></a>

Para disparar uma mensagem interativa de **WhatsApp Flow** que utiliza o **callback** **criptografado** (`data_exchange`), a requisição HTTP `POST` para o endpoint de mensagens segue a estrutura oficial abaixo.

```http
curl -X POST "https://send-message.otima.io/v1/whatsapp/551149999999" \
  -H "Authorization: Bearer {SEU_TOKEN_API}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "interactive",
    "interactive": {
      "type": "flow",
      "header": {
        "type": "text",
        "text": "Atendimento e Agendamento"
      },
      "body": {
        "text": "Clique no botão abaixo para abrir o formulário interativo."
      },
      "footer": {
        "text": "Ótima Digital"
      },
      "action": {
        "name": "flow",
        "parameters": {
          "flow_message_version": "3",
          "flow_token": "token_sessao_cliente_99823",
          "flow_id": "1474114767752219",
          "flow_cta": "Iniciar Formulário",
          "flow_action": "data_exchange",
          "flow_action_payload": {
            "screen": "START_SCREEN",
            "data": {
              "cliente_id": "CLI-88192",
              "origem": "campanha_whatsapp"
            }
          }
        }
      }
    }
  }'

```

***

#### Detalhamento dos Campos Específicos para a Criptografia & Callback <a href="#user-content-detalhamento-dos-campos-especificos-para-a-criptografia-callback" id="user-content-detalhamento-dos-campos-especificos-para-a-criptografia-callback"></a>

<table><thead><tr><th>Parâmetro</th><th width="173.5728759765625">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><strong><code>flow_action</code></strong></td><td><code>string</code></td><td><strong>Obrigatório para Criptografia.</strong> Defina como <strong><code>"data_exchange"</code></strong>. Isso instrui o aplicativo do WhatsApp a consultar a <code>public_key</code> cadastrada no número, criptografar a requisição via AES-GCM + RSA e chamar o seu <code>endpoint_uri</code> ao abrir a tela.</td></tr><tr><td><strong><code>flow_token</code></strong></td><td><code>string</code></td><td><strong>Obrigatório.</strong> Identificador único da sessão/atendimento gerado pela sua aplicação (ex: <code>token_sessao_cliente_99823</code>). Ele será repassado pela Meta no callback criptografado para você identificar qual usuário está respondendo.</td></tr><tr><td><strong><code>flow_id</code></strong></td><td><code>string</code></td><td><strong>Obrigatório.</strong> O ID do Flow retornado ao criar o container no <code>POST /workspace-flows</code>.</td></tr><tr><td><strong><code>flow_cta</code></strong></td><td><code>string</code></td><td>Texto exibido no botão da mensagem no WhatsApp (ex: <code>"Iniciar Formulário"</code> ou <code>"Abrir Cadastro"</code>).</td></tr><tr><td><strong><code>flow_action_payload</code></strong></td><td><code>object</code></td><td><em>(Opcional)</em> Objeto de dados iniciais enviados para carregar a primeira tela (<code>START_SCREEN</code>).</td></tr></tbody></table>

#### O que acontece no celular do usuário quando ele recebe essa mensagem? <a href="#user-content-o-que-acontece-no-celular-do-usuario-quando-ele-recebe-essa-mensagem" id="user-content-o-que-acontece-no-celular-do-usuario-quando-ele-recebe-essa-mensagem"></a>

1. O usuário vê o card interativo com o título *"Atendimento e Agendamento"* e o botão *"Iniciar Formulário"*.
2. Ao clicar no botão, o app do WhatsApp consulta a **`public_key`** (cadastrada no `POST /whatsapp_business_encryption`).
3. O WhatsApp criptografa os dados da sessão com a chave pública e dispara o `POST` para a sua URL de callback (`endpoint_uri`).
4. O seu servidor descriptografa os dados utilizando a **Chave Privada (`private.pem`)**, processa as informações e responde `HTTP 200 OK text/plain` com o JSON criptografado.

***

{% hint style="danger" %}

#### Problemas comuns

**Flow não abre**

* `flow_id` inválido
* Flow ainda em **DRAFT**

**Não chega webhook**

* Tela final não tem `"terminal": true`

**Erro no envio**

* Payload inválido
* Template não aprovado
  {% endhint %}

***

{% hint style="success" %}

#### Boas práticas <a href="#boas-praticas" id="boas-praticas"></a>

* Gere `flow_token` único por envio
* Inclua contexto (user\_id, pedido, etc)
* Logue envio + webhook
* Nunca reutilize `flow_token`
  {% endhint %}