Pular para o conteúdo principal

API do Fluxos do WhatsApp

https://whatsapp.turn.io/v1/flows

Os Fluxos do WhatsApp são ferramentas interativas de coleta de dados que podem ser usadas para coletar informações de clientes diretamente no WhatsApp. Este endpoint permite que você crie Fluxos do WhatsApp programaticamente para sua Conta Comercial do WhatsApp.

cuidado

Os Fluxos do WhatsApp são um recurso fornecido pela Meta. Para informações detalhadas sobre especificações de fluxo, tipos de tela e componentes, consulte a documentação oficial dos Fluxos do WhatsApp.

Pré-requisitos​

Feature Flag​

Todos os endpoints de Fluxos do WhatsApp requerem que o recurso whatsapp_flows_api esteja habilitado para o seu número. Entre em contato com seu gerente de conta para habilitar este recurso.

Autenticação​

Todos os endpoints usam autenticação Bearer token. Inclua seu token Turn.io no cabeçalho HTTP Authorization:

-H "Authorization: Bearer <token>"

O número do WhatsApp é determinado a partir do token de autenticação.

Criando um Fluxo​

Para criar um Fluxo do WhatsApp, forneça um objeto JSON com a definição do fluxo. O fluxo será criado sob sua Conta Comercial do WhatsApp (WABA).

POST https://whatsapp.turn.io/v1/flows

Corpo da Requisição​

ParâmetroTipoObrigatórioPadrãoDescrição
namestringSimO nome do fluxo. Este será visível no seu Gerenciador de Negócios do WhatsApp.
flow_jsonobject ou stringSimA definição do fluxo como um objeto JSON ou JSON em formato de string. Deve estar em conformidade com a especificação JSON de Fluxo do WhatsApp v7.2+.
categoriesarray de stringsNão["OTHER"]As categorias para classificar seu fluxo. Opções válidas: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER.
publishbooleanNãofalseSe deve publicar o fluxo imediatamente após a criação. Se false, o fluxo será criado em modo rascunho.

Exemplo de Requisição​

$ curl -X POST https://whatsapp.turn.io/v1/flows \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pesquisa de Satisfação",
    "flow_json": {
      "version": "7.2",
      "screens": [
        {
          "id": "SURVEY_START",
          "title": "Satisfação do Cliente",
          "terminal": true,
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              {
                "type": "TextHeading",
                "text": "Qual é o seu nível de satisfação com nosso serviço?"
              },
              {
                "type": "RadioButtonsGroup",
                "name": "satisfaction",
                "label": "Por favor, selecione seu nível de satisfação",
                "data-source": [
                  { "id": "very_satisfied", "title": "Muito Satisfeito" },
                  { "id": "satisfied", "title": "Satisfeito" },
                  { "id": "neutral", "title": "Neutro" },
                  { "id": "dissatisfied", "title": "Insatisfeito" }
                ],
                "required": true
              },
              {
                "type": "Footer",
                "label": "Enviar",
                "on-click-action": {
                  "name": "complete",
                  "payload": {}
                }
              }
            ]
          }
        }
      ]
    },
    "categories": ["SURVEY"],
    "publish": false
  }'

Resposta​

201 Created

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 201
  },
  "id": "1234567890123456",
  "validation_errors": []
}
ParâmetroTipoDescrição
metaobjectObjeto de metadados padrão contendo informações de versão e status da API.
idstringO identificador único do fluxo recém-criado, fornecido pela Meta.
validation_errorsarrayArray de erros de validação retornados pela API da Meta, se houver.

Usando o ID do Fluxo​

info

O ID do seu fluxo e as telas disponíveis são fornecidos pelo Gerenciador de Negócios do Facebook.

Uma vez que você tenha o id do fluxo, você pode usá-lo para enviar mensagens interativas com fluxos para seus clientes:

$ curl -X POST https://whatsapp.turn.io/v1/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "27123456789",
    "type": "interactive",
    "interactive": {
      "type": "flow",
      "header": {
        "type": "text",
        "text": "Pesquisa de Satisfação"
      },
      "body": {
        "text": "Adoraríamos ouvir seu feedback! Por favor, reserve um momento para completar nossa pesquisa."
      },
      "footer": {
        "text": "Seu feedback nos ajuda a melhorar"
      },
      "action": {
        "name": "flow",
        "parameters": {
          "flow_id": "1234567890123456",
          "flow_cta": "Iniciar Pesquisa",
          "flow_action": "navigate",
          "flow_action_payload": {
            "screen": "SURVEY_START"
          },
          "flow_message_version": "3",
          "mode": "published"
        }
      }
    }
  }'

Parâmetros Principais:

  • flow_id: O ID retornado ao criar seu fluxo (o flow_json já está armazenado no sistema da Meta)
  • flow_cta: O texto do botão de chamada para ação (ex.: "Iniciar Pesquisa")
  • flow_action: Geralmente "navigate" para abrir o fluxo em uma tela específica
  • flow_action_payload.screen: O ID da tela do seu flow_json para abrir
  • mode: Pode ser "published" (para fluxos ao vivo) ou "draft" (para testes)

Para mais detalhes, consulte a documentação da API de Mensagens.

Atualizando Metadados do Fluxo​

Atualize os metadados de um fluxo, como nome, categorias, URI do endpoint e ID do aplicativo, sem alterar o JSON do fluxo.

POST https://whatsapp.turn.io/v1/flows/:flow_id

Corpo da Requisição​

Todos os parâmetros são opcionais. Inclua apenas os campos que você deseja atualizar.

ParâmetroTipoDescrição
namestringO novo nome para o fluxo.
categoriesarray de stringsNovas categorias para o seu fluxo. Opções válidas: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER.
endpoint_uristringURL do Endpoint do Fluxo do WA (para versão 3.0+ do JSON de Fluxo com troca de dados).
application_idstringID do aplicativo Meta para conectar ao Fluxo (obrigatório para fluxos com endpoints).

Exemplo de Requisição​

$ curl -X POST https://whatsapp.turn.io/v1/flows/1234567890123456 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Formulário de Feedback do Cliente",
    "categories": ["CUSTOMER_SUPPORT", "SURVEY"]
  }'

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "success": true
}

Atualizando o JSON do Fluxo​

Atualize o JSON de um fluxo enviando um novo arquivo flow.json. A Meta validará o JSON e retornará quaisquer erros de validação.

POST https://whatsapp.turn.io/v1/flows/:flow_id/assets

Requisição​

A requisição deve ser enviada como multipart/form-data:

ParâmetroTipoObrigatórioDescrição
filearquivoSimO arquivo JSON do fluxo. Tamanho máximo: 10 MB.
info

Os parâmetros name e asset_type são automaticamente definidos como flow.json e FLOW_JSON respectivamente.

Exemplo de Requisição​

$ curl -X POST https://whatsapp.turn.io/v1/flows/1234567890123456/assets \
  -H "Authorization: Bearer <token>" \
  -F "file=@flow.json"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "success": true,
  "validation_errors": []
}

Se o JSON do fluxo contiver erros de validação, a Meta ainda aceitará o upload mas retornará informações detalhadas sobre os erros:

{
  "success": true,
  "validation_errors": [
    {
      "error": "INVALID_PROPERTY_VALUE",
      "error_type": "FLOW_JSON_ERROR",
      "message": "Invalid value found for property 'type'.",
      "line_start": 10,
      "line_end": 10,
      "column_start": 21,
      "column_end": 34,
      "pointers": [
        {
          "line_start": 10,
          "line_end": 10,
          "column_start": 21,
          "column_end": 34,
          "path": "screens[0].layout.children[0].type"
        }
      ]
    }
  ]
}

Publicando um Fluxo​

Publique um fluxo em rascunho para disponibilizá-lo para mensagens de produção.

POST https://whatsapp.turn.io/v1/flows/:flow_id/publish

Exemplo de Requisição​

$ curl -X POST https://whatsapp.turn.io/v1/flows/1234567890123456/publish \
  -H "Authorization: Bearer <token>"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "success": true
}

Notas Importantes​

  • Apenas fluxos com status DRAFT podem ser publicados
  • Uma vez publicados, os fluxos não podem ser editados ou deletados (apenas depreciados)
  • Fluxos publicados podem ser usados imediatamente em mensagens de produção
  • Certifique-se de ter testado completamente seu fluxo em modo rascunho antes de publicar

Deletando um Fluxo​

Delete um fluxo que esteja no status DRAFT.

DELETE https://whatsapp.turn.io/v1/flows/:flow_id
cuidado

Apenas fluxos no status DRAFT podem ser deletados. Para remover um fluxo publicado, use o endpoint de depreciar.

Exemplo de Requisição​

$ curl -X DELETE https://whatsapp.turn.io/v1/flows/1234567890123456 \
  -H "Authorization: Bearer <token>"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "success": true
}

Depreciando um Fluxo​

Deprecie um fluxo publicado. Fluxos depreciados permanecem visíveis no histórico de fluxos, mas não podem mais ser usados para enviar mensagens aos clientes.

POST https://whatsapp.turn.io/v1/flows/:flow_id/deprecate

Exemplo de Requisição​

$ curl -X POST https://whatsapp.turn.io/v1/flows/1234567890123456/deprecate \
  -H "Authorization: Bearer <token>"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "success": true
}

Listando Fluxos​

Recupere uma lista de todos os Fluxos do WhatsApp da sua Conta Comercial do WhatsApp.

GET https://whatsapp.turn.io/v1/flows

Exemplo de Requisição​

$ curl -X GET https://whatsapp.turn.io/v1/flows \
  -H "Authorization: Bearer <token>"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "data": [
    {
      "id": "1234567890123456",
      "name": "Pesquisa de Satisfação",
      "status": "PUBLISHED",
      "categories": ["SURVEY"],
      "validation_errors": []
    },
    {
      "id": "6543210987654321",
      "name": "Fluxo de Cadastro",
      "status": "DRAFT",
      "categories": ["SIGN_UP"],
      "validation_errors": []
    }
  ]
}

Valores de Status do Fluxo​

StatusDescrição
DRAFTFluxo está em modo rascunho e pode ser editado ou deletado
PUBLISHEDFluxo está publicado e pode ser usado para enviar mensagens
DEPRECATEDFluxo foi depreciado e não pode mais ser usado
THROTTLEDFluxo está limitado devido a problemas de saúde do endpoint (limitado a 10 mensagens/hora)
BLOCKEDFluxo foi bloqueado devido a problemas contínuos de saúde do endpoint

Listando Ativos do Fluxo​

Recupere os ativos de um fluxo, incluindo o ativo FLOW_JSON contendo a definição do fluxo.

GET https://whatsapp.turn.io/v1/flows/:flow_id/assets

Exemplo de Requisição​

$ curl -X GET https://whatsapp.turn.io/v1/flows/1234567890123456/assets \
  -H "Authorization: Bearer <token>"

Resposta​

200 OK

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 200
  },
  "data": [
    {
      "name": "flow.json",
      "asset_type": "FLOW_JSON",
      "download_url": "https://scontent.xx.fbcdn.net/m1/v/..."
    }
  ]
}

A download_url é uma URL temporária para baixar o conteúdo do ativo:

$ curl -X GET "https://scontent.xx.fbcdn.net/m1/v/..." -o flow.json

Respostas de Erro​

Todos os endpoints podem retornar os seguintes erros comuns:

403 Forbidden - Recurso Não Habilitado​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 403
  },
  "error": {
    "code": "feature_not_enabled",
    "message": "The whatsapp_flows_api feature is not enabled for this number",
    "type": "FeatureNotEnabled"
  }
}

403 Forbidden - Não Suportado para Tipo de Número​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 403
  },
  "error": {
    "code": "not_supported",
    "message": "This operation is not supported for the given number type",
    "type": "NotSupported"
  }
}

400 Bad Request - ID do Fluxo Ausente​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 400
  },
  "error": {
    "code": "missing_parameters",
    "message": "Missing required parameter: flow_id",
    "type": "BadRequest"
  }
}

400 Bad Request - Fluxo Não Encontrado​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 400
  },
  "errors": [
    {
      "title": "Flow not found",
      "details": "The specified flow ID does not exist or is not accessible"
    }
  ]
}

400 Bad Request - WABA Não Encontrada​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 400
  },
  "errors": [
    {
      "title": "WABA not found",
      "details": "This number is not associated with a WhatsApp Business Account"
    }
  ]
}

400 Bad Request - Status de Fluxo Inválido​

Retornado ao tentar publicar, deletar ou depreciar um fluxo em um status inválido:

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 400
  },
  "error": {
    "code": 100,
    "message": "Flow is not in DRAFT status",
    "error_user_title": "Invalid Flow Status",
    "error_user_msg": "Only flows in DRAFT status can be published",
    "type": "OAuthException"
  }
}

400 Bad Request - Erros de Validação​

{
  "meta": {
    "version": "v1",
    "api_status": "stable",
    "http_code": 400
  },
  "error": {
    "code": 100,
    "message": "Flow has validation errors",
    "error_user_title": "Validation Failed",
    "error_user_msg": "Please fix all validation errors before publishing",
    "type": "OAuthException"
  }
}

Especificação JSON do Fluxo​

O parâmetro flow_json deve estar em conformidade com a especificação JSON de Fluxo do WhatsApp:

  • Versão: Deve ser 7.2 ou superior
  • Telas: Um array de objetos de tela que definem a interface do usuário do fluxo
  • Modelo de Dados: Modelo de dados opcional para gerenciar o estado do fluxo
  • Roteamento: Lógica de navegação entre telas
info

Para aceitar um payload no WhatsApp, você precisa definir data na definição do fluxo do WhatsApp, assim como init-value para cada campo de entrada.

Para detalhes completos sobre a especificação JSON de Fluxo, incluindo layouts de tela disponíveis, tipos de componentes, tipos de ação e regras de validação, consulte a Referência JSON dos Fluxos do WhatsApp.

Melhores Práticas​

info

O Turn não suporta atualmente Fluxos do WhatsApp com endpoints (ou seja, sem troca de dados enquanto o usuário está navegando pelo formulário).

nota

O Turn garante apenas o funcionamento dos Fluxos do WhatsApp para os seguintes dispositivos conforme políticas da Meta:

  • Android rodando OS 6.0 ou mais recente
  • iPhone rodando iOS 12 ou mais recente
  1. Teste no Modo Rascunho: Crie fluxos com publish: false inicialmente para testá-los antes de publicar.
  2. Valide o JSON do Fluxo: Certifique-se de que seu JSON de fluxo é válido antes de fazer a chamada da API para evitar erros.
  3. Use Categorias Apropriadas: Selecione a categoria que melhor corresponde ao propósito do seu fluxo para uma melhor organização.
  4. Mantenha Simples: Comece com fluxos simples e adicione complexidade gradualmente conforme necessário.
  5. Tratamento de Erros: O JSON do fluxo pode conter erros de validação retornados pela API da Meta. Revise as mensagens de erro cuidadosamente para corrigir problemas.

Recursos Adicionais​