# Enviar um fluxo para um contato

> Envie um fluxo pronto a um contato a partir do seu sistema, com o ID do contato e o do fluxo, e respeite a janela de 24 horas do WhatsApp.

Endereço: https://docs.nextags.com.br/guias/enviar-fluxo/
Tipo: Guia

Atualizado em: 26/10/2026

Enviar um fluxo é o jeito mais completo de falar com o contato pela API: o fluxo pode ter texto, botões, mídia, perguntas, ações e, no WhatsApp, um Modelo de Mensagem. O seu sistema manda só o ID do contato e o do fluxo, e a NexTags faz o resto. Use para confirmar pedidos, dar boas-vindas, lembrar de um horário ou retomar uma conversa.

**Antes de começar**

- A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).
- O fluxo pronto e publicado na NexTags: o contato recebe a versão publicada. Veja [Rascunho, publicação e versões do fluxo](https://help.nextags.com.br/tutoriais/fluxos/publicar-e-rascunho/).
- Para o WhatsApp, fora da janela de 24 horas: um fluxo que comece com um Modelo de Mensagem aprovado. Veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/).

## Passo a passo

### Passo 1: Ache o ID do fluxo

Use [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/). A resposta é uma lista com o `id` e o `name` de cada fluxo:

**Listar fluxos**

```bash
curl "https://app.nextagsai.com.br/api/accounts/flows" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/flows', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/accounts/flows",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/flows');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

```json
[
  {"id": 1000001, "name": "Pedido confirmado"},
  {"id": 1000002, "name": "Boas-vindas"}
]
```

O ID também aparece na tela: no endereço do editor do fluxo (`flow?id=1000001`) e no **Obter Link** do menu ⋮ do fluxo. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). Guarde o ID no seu sistema: ele não muda quando o nome do fluxo muda.

### Passo 2: Ache o ID do contato

Procure o contato pelo telefone (ou pelo e-mail, com `field_id=email`) e pegue o `id` em `data`:

**Procurar pelo telefone**

```bash
curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: 'phone',
  value: '5511988776655',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "phone",
        "value": "5511988776655",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'phone',
    'value' => '5511988776655',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

Se o contato não existe, crie antes. Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/).

### Passo 3: Envie o fluxo

Use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/), com o ID do contato e o do fluxo no caminho. A chamada não tem corpo.

**Enviar fluxo**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/1000001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send/1000001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

O contrato não descreve a resposta. Confira o código HTTP e, no primeiro teste, a conversa do contato na **Caixa de Entrada**.

> **Um fluxo só, dentro e fora da janela:**
> Comece o fluxo com uma etapa **Condição** que use **Interagiu nas últimas 24h**: quem interagiu recebe a mensagem livre; quem não interagiu recebe o Modelo de Mensagem. Assim o seu sistema envia sempre o mesmo fluxo. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e [Etapa Condição](https://help.nextags.com.br/tutoriais/fluxos/condicoes/).

### Passo 4: Envie o fluxo junto com outras ações

Para pôr uma etiqueta ou preencher um campo e enviar o fluxo na mesma chamada, use [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/) com a ação `send_flow`. Ponha antes do `send_flow` as ações de que o fluxo precisa, como o campo que aparece na mensagem, e confira o resultado no primeiro teste.

**Etiqueta e fluxo numa chamada**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "action": "set_field_value",
        "field_name": "cidade",
        "value": "São Paulo"
      },
      {
        "action": "add_tag",
        "tag_name": "cliente-vip"
      },
      {
        "action": "send_flow",
        "flow_id": 1000001
      }
    ]
  }'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    actions: [
      {
        action: 'set_field_value',
        field_name: 'cidade',
        value: 'São Paulo',
      },
      {
        action: 'add_tag',
        tag_name: 'cliente-vip',
      },
      {
        action: 'send_flow',
        flow_id: 1000001,
      },
    ],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send_content",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "actions": [
            {
                "action": "set_field_value",
                "field_name": "cidade",
                "value": "São Paulo",
            },
            {
                "action": "add_tag",
                "tag_name": "cliente-vip",
            },
            {
                "action": "send_flow",
                "flow_id": 1000001,
            },
        ],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send_content');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'actions' => [
            [
                'action' => 'set_field_value',
                'field_name' => 'cidade',
                'value' => 'São Paulo',
            ],
            [
                'action' => 'add_tag',
                'tag_name' => 'cliente-vip',
            ],
            [
                'action' => 'send_flow',
                'flow_id' => 1000001,
            ],
        ],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

As oito ações estão em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).

## Pronto: como conferir

- Na **Caixa de Entrada**, a conversa do contato mostra as mensagens do fluxo.
- No painel do contato, o histórico mostra o fluxo executado. Veja [Ver os fluxos e ações executados](https://help.nextags.com.br/tutoriais/caixa-de-entrada/acoes-executadas/).

## Se não funcionou

### 401 com "No valid API key provided."

A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).

### O contato não recebeu nada no WhatsApp

O contato pode estar fora da janela de 24 horas, com um fluxo que começa por uma mensagem livre. Comece o fluxo com um Modelo de Mensagem aprovado ou com a condição **Interagiu nas últimas 24h**, e confira o que falhou no **Registro de Erros**. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/). No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela **Caixa de Entrada**. Veja [Mensagens fora da janela no Instagram e no Messenger](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).

### O contato recebeu uma versão antiga do fluxo

O fluxo tem mudanças em rascunho. Clique em **Publicar** no editor e envie de novo. Veja [Rascunho, publicação e versões do fluxo](https://help.nextags.com.br/tutoriais/fluxos/publicar-e-rascunho/).

### O fluxo não chega a contatos de um canal

Confira o canal das etapas do fluxo. Na **Caixa de Entrada**, o **Enviar Fluxo** só oferece fluxos do canal do contato ou para todos os canais: use etapas **Todos os canais** quando o mesmo fluxo vai para canais diferentes. Veja [Etapa Enviar Mensagem e o canal da mensagem](https://help.nextags.com.br/tutoriais/fluxos/etapa-enviar-mensagem/).

### 400 ou 404 com o ID do contato ou do fluxo

O ID está errado ou é de outra conta. Liste os fluxos de novo e procure o contato pelo telefone. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Leia https://docs.nextags.com.br/guias/enviar-fluxo.md.

Quando [o evento no seu sistema, por exemplo: um pedido é pago], quero enviar o fluxo [nome do fluxo] da NexTags para o cliente. Escreva, em [linguagem], o código que procura o contato pelo telefone, envia o fluxo pelo ID e registra no meu sistema que o envio foi feito, para não enviar duas vezes. A chave vem da variável de ambiente NEXTAGS_API_KEY.
```