API atual/Referência completa/WhatsApp: Flows da Meta

IA para Flows

Gera um rascunho de Flow a partir de uma descrição e deixa o assistente escolher qual Flow enviar.

Duas rotas usam a IA da loja: uma ajuda a desenhar um Flow, a outra escolhe entre os Flows publicados o que serve para uma mensagem. Ambas exigem IA configurada na loja.

Gerar um Flow com IA

Descreve em texto o que você quer e recebe um rascunho de flow_json, ou perguntas para esclarecer o pedido. Nada é gravado: copie o resultado para POST /meta-flows.

POST/api/v1/admin/whatsapp/meta-flows/generateAdmin

Gera um rascunho de Flow a partir de uma descrição

Corpo da requisição

promptstringobrigatório

O que o Flow deve fazer. Obrigatório.

historyarray

Rodadas anteriores como lista de textos (suas respostas às perguntas devolvidas), para dar contexto.

Exemplo de requisição (Gerar com IA)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Um formulário para o cliente pedir que a loja ligue de volta, com nome e telefone."
  }'

Resposta (Gerar com IA)

200Rascunho gerado

json

{
  "flow_json": {
    "version": "6.2",
    "screens": [
      {
        "id": "CONTACT",
        "title": "Contato",
        "terminal": true,
        "success": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            {
              "type": "TextHeading",
              "text": "Fale com a gente"
            },
            {
              "type": "Form",
              "name": "form",
              "children": [
                {
                  "type": "TextInput",
                  "name": "nome",
                  "label": "Seu nome",
                  "input-type": "text",
                  "required": true
                },
                {
                  "type": "Footer",
                  "label": "Enviar",
                  "on-click-action": {
                    "name": "complete",
                    "payload": {
                      "nome": "${form.nome}"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "name": "Contato rápido",
  "flow_key": "contato-rapido",
  "when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "warnings": null
}

200Pedido de esclarecimento

json

{
  "questions": [
    "Qual horário de atendimento deve aparecer?"
  ],
  "warnings": null
}

Campos da resposta

flow_jsonobject

Rascunho do Flow. Ausente quando a IA devolve perguntas.

namestring

Nome sugerido.

flow_keystring

Chave sugerida.

when_to_usestring

Texto sugerido para ai_when_to_use.

questionsarray

Perguntas para você responder e reenviar em history. Ausente quando há rascunho.

warningsarray

Problemas de validação do rascunho; null quando é válido ou não há rascunho.

Erros (Gerar com IA)

Status	Quando	Corpo
400	Corpo que não é JSON ou `prompt` vazio.	`{"error":"prompt é obrigatório"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A loja não tem IA configurada, ou a IA falhou.	`{"error":"whatsapp: provider de IA não configurado"}`

Decidir qual Flow enviar

Dada uma mensagem de cliente, o assistente escolhe qual dos Flows já publicados da loja serve (ou nenhum). Sem phone, é só um teste: devolve a escolha. Com phone, envia o Flow escolhido.

POST/api/v1/admin/whatsapp/meta-flows/decideAdmin

Escolhe (e opcionalmente envia) o Flow certo para uma mensagem

Corpo da requisição

textstringobrigatório

Mensagem do cliente. Obrigatória.

phonestring

Telefone para enviar o Flow escolhido. Omitido, só decide.

Exemplo de requisição (Decidir qual Flow enviar)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/decide" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "queria que alguém me ligasse"
  }'

Resposta (Decidir qual Flow enviar)

200Só decidiu

json

{
  "flow_key": "contato-rapido",
  "decided": true,
  "sent": false
}

200Nenhum Flow serve

json

{
  "flow_key": "",
  "decided": false,
  "sent": false
}

Campos da resposta

flow_keystring

flow_key do Flow escolhido. Texto vazio quando nenhum serve.

decidedboolean

true quando algum Flow foi escolhido.

sentboolean

true quando o Flow foi enviado ao phone.

Erros (Decidir qual Flow enviar)

Status	Quando	Corpo
400	Corpo que não é JSON ou `text` vazio.	`{"error":"text é obrigatório"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A loja não tem IA configurada, o Flow escolhido não está publicado, ou o envio falhou.	`{"error":"whatsapp: provider de IA não configurado"}`

Veja também

API atual/Referência completa/WhatsApp: Flows da Meta

IA para Flows

Gera um rascunho de Flow a partir de uma descrição e deixa o assistente escolher qual Flow enviar.

Duas rotas usam a IA da loja: uma ajuda a desenhar um Flow, a outra escolhe entre os Flows publicados o que serve para uma mensagem. Ambas exigem IA configurada na loja.

Gerar um Flow com IA

Descreve em texto o que você quer e recebe um rascunho de flow_json, ou perguntas para esclarecer o pedido. Nada é gravado: copie o resultado para POST /meta-flows.

POST/api/v1/admin/whatsapp/meta-flows/generateAdmin

Gera um rascunho de Flow a partir de uma descrição

Corpo da requisição

promptstringobrigatório

O que o Flow deve fazer. Obrigatório.

historyarray

Rodadas anteriores como lista de textos (suas respostas às perguntas devolvidas), para dar contexto.

Exemplo de requisição (Gerar com IA)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Um formulário para o cliente pedir que a loja ligue de volta, com nome e telefone."
  }'

Resposta (Gerar com IA)

200Rascunho gerado

json

{
  "flow_json": {
    "version": "6.2",
    "screens": [
      {
        "id": "CONTACT",
        "title": "Contato",
        "terminal": true,
        "success": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            {
              "type": "TextHeading",
              "text": "Fale com a gente"
            },
            {
              "type": "Form",
              "name": "form",
              "children": [
                {
                  "type": "TextInput",
                  "name": "nome",
                  "label": "Seu nome",
                  "input-type": "text",
                  "required": true
                },
                {
                  "type": "Footer",
                  "label": "Enviar",
                  "on-click-action": {
                    "name": "complete",
                    "payload": {
                      "nome": "${form.nome}"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "name": "Contato rápido",
  "flow_key": "contato-rapido",
  "when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "warnings": null
}

200Pedido de esclarecimento

json

{
  "questions": [
    "Qual horário de atendimento deve aparecer?"
  ],
  "warnings": null
}

Campos da resposta

flow_jsonobject

Rascunho do Flow. Ausente quando a IA devolve perguntas.

namestring

Nome sugerido.

flow_keystring

Chave sugerida.

when_to_usestring

Texto sugerido para ai_when_to_use.

questionsarray

Perguntas para você responder e reenviar em history. Ausente quando há rascunho.

warningsarray

Problemas de validação do rascunho; null quando é válido ou não há rascunho.

Erros (Gerar com IA)

Status	Quando	Corpo
400	Corpo que não é JSON ou `prompt` vazio.	`{"error":"prompt é obrigatório"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A loja não tem IA configurada, ou a IA falhou.	`{"error":"whatsapp: provider de IA não configurado"}`

Decidir qual Flow enviar

Dada uma mensagem de cliente, o assistente escolhe qual dos Flows já publicados da loja serve (ou nenhum). Sem phone, é só um teste: devolve a escolha. Com phone, envia o Flow escolhido.

POST/api/v1/admin/whatsapp/meta-flows/decideAdmin

Escolhe (e opcionalmente envia) o Flow certo para uma mensagem

Corpo da requisição

textstringobrigatório

Mensagem do cliente. Obrigatória.

phonestring

Telefone para enviar o Flow escolhido. Omitido, só decide.

Exemplo de requisição (Decidir qual Flow enviar)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/decide" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "queria que alguém me ligasse"
  }'

Resposta (Decidir qual Flow enviar)

200Só decidiu

json

{
  "flow_key": "contato-rapido",
  "decided": true,
  "sent": false
}

200Nenhum Flow serve

json

{
  "flow_key": "",
  "decided": false,
  "sent": false
}

Campos da resposta

flow_keystring

flow_key do Flow escolhido. Texto vazio quando nenhum serve.

decidedboolean

true quando algum Flow foi escolhido.

sentboolean

true quando o Flow foi enviado ao phone.

Erros (Decidir qual Flow enviar)

Status	Quando	Corpo
400	Corpo que não é JSON ou `text` vazio.	`{"error":"text é obrigatório"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A loja não tem IA configurada, o Flow escolhido não está publicado, ou o envio falhou.	`{"error":"whatsapp: provider de IA não configurado"}`