Fluxos de mensagens: API de integração

Use a API para colocar um cliente em um fluxo de mensagens ou encerrar um fluxo em andamento a partir de outro sistema. As mensagens são enviadas pelo WhatsApp conectado à conta e seguem os prazos, dias e horários configurados no editor visual.

1. Crie uma chave de integração

As chaves ficam nas configurações de fluxos. Uma chave aparece apenas uma vez no momento da criação e as chaves revogadas deixam de funcionar imediatamente.

Configurações > Fluxos de mensagens > Chaves de integração

1. Crie uma chave com um nome fácil de reconhecer.
2. Copie a chave no momento da criação.
3. Guarde a chave no servidor que vai chamar a API.
4. Revogue e crie outra chave quando ela não for mais usada.

2. Autentique as chamadas

Envie a chave no cabeçalho de cada requisição feita pelo seu servidor.

Authorization: Bearer flw_...
Content-Type: application/json

3. Iniciar um fluxo

Informe o identificador do fluxo e o telefone do cliente em formato internacional. Se o cadastro ainda não existir, ele é criado com o nome enviado. Variáveis personalizadas são opcionais e usam o texto alternativo definido em cada uso da variável quando não forem informadas.

POST https://faci.to/api/public/flows/start

{
  "flow_id": "0f4d8c6f-0000-4000-9000-000000000000",
  "phone": "+5548999999999",
  "name": "Maria Souza",
  "variables": {
    "pedidos": "12",
    "plano": "Premium"
  }
}
200 OK

{
  "run_id": "f7a9e4d1-0000-4000-9000-000000000000",
  "status": "started"
}

4. Encerrar um fluxo

O encerramento procura uma execução ativa do mesmo fluxo para o telefone informado. Quando o fluxo tem mensagem de encerramento antecipado, ela é enviada antes de finalizar.

POST https://faci.to/api/public/flows/stop

{
  "flow_id": "0f4d8c6f-0000-4000-9000-000000000000",
  "phone": "+5548999999999"
}

Variáveis disponíveis

  • Fixas: contato, primeiro nome, empresa, atendente e setor, seguindo os mesmos marcadores usados nos atalhos de mensagem.
  • Personalizadas: qualquer variável declarada no fluxo, como {{pedidos}} ou {{plano}}.
  • Texto alternativo: obrigatório e escrito junto da variável, como {{contato.nome|cliente}}. Vale só para aquele uso e entra quando o valor real não existe.

Regras de execução

  • O mesmo cliente não entra duas vezes no mesmo fluxo ao mesmo tempo.
  • Responder durante o fluxo não interrompe a sequência.
  • Alterações futuras no fluxo não mudam execuções que já começaram.
  • Se o prazo cair fora dos dias e horários permitidos, o envio aguarda a próxima abertura.
  • A espera pode ser configurada em segundos, minutos, horas ou dias, inclusive como primeira etapa do fluxo.

Erros comuns

401 invalid_api_key       Chave ausente, revogada ou inválida
404 flow_not_found        Fluxo não encontrado para a conta
409 already_active        Cliente já está nesse fluxo
422 invalid_payload       Campos obrigatórios ausentes ou inválidos
422 person_without_phone  Cliente sem telefone válido
424 whatsapp_not_connected WhatsApp da conta indisponível