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.

Guia6 min

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.
O fluxo pronto e publicado na NexTags: o contato recebe a versão publicada. Veja Rascunho, publicação e versões do fluxo.
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.

Passo a passo

Passo 1: Ache o ID do fluxo

Use Listar fluxos. A resposta é uma lista com o id e o name de cada fluxo:

Listar fluxos

curl "https://app.nextagsai.com.br/api/accounts/flows" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$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);

[
  {"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. 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

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$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.

Passo 3: Envie o fluxo

Use Enviar fluxo, com o ID do contato e o do fluxo no caminho. A chamada não tem corpo.

Enviar fluxo

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$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 e Etapa Condição.

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

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
      }
    ]
  }'

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);

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
$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.

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.

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.

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 e Registro de Erros: ler e resolver. 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.

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.

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.

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.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

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.

Obrigado! Sua resposta ajuda a melhorar a central.