Enviar formulario

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

Descripción

Envía un mensaje con un botón que abre un Native Flow de WhatsApp, un formulario nativo que recolecta datos estructurados (nombre, teléfono, email, CPF/CNPJ, dirección) sin salir de la conversación. Soporta dos flujos preconfigurados: contact_details (Datos del cliente) y registration_offer (Oferta de registro), además de un escape hatch vía buttonParamsJSON para flujos completamente personalizados. Ideal para captura de leads, registros y ofertas con confirmación rápida.

Compatibilidad de cliente: los Native Flows aún no son compatibles con WhatsApp Web/Desktop. El botón del formulario solo se renderizará para destinatarios en las apps oficiales de Android e iOS, en otros clientes el mensaje aparecerá sin el botón interactivo.

Ejemplos

Oferta de registro (registration_offer)

Envía una oferta con título y descripción. El botón abre el Flow default de registro con campos visibles configurables.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":           "5511999999999",
    "message":          "Lock in your spot in the course with 50% off!",
    "formType":         "registration_offer",
    "buttonLabel":      "I want it",
    "offerName":        "Go Course - May Cohort",
    "offerDescription": "Lifetime access + certificate + 30-day support"
  }'

Captura de datos de contacto (contact_details)

Usa el flujo oficial contact_details de WhatsApp. Oculta los campos que no quieres pedir vía las flags *Visible. Aquí pedimos solo nombre, teléfono y email.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":                 "5511999999999",
    "message":                "To finish your support request, please complete your details:",
    "formType":               "contact_details",
    "buttonLabel":            "Fill in details",
    "fullNameVisible":        true,
    "phoneNumberVisible":     true,
    "emailVisible":           true,
    "cpfOrCnpjVisible":       false,
    "deliveryAddressVisible": false
  }'

Flujo personalizado vía `buttonParamsJSON`

Escape hatch para tus propios flujos (creados en WhatsApp Business Manager). Cuando se proporciona buttonParamsJSON, el servidor ignora todos los demás campos relacionados con el flujo (formType, flowId, flags de visibilidad, offerName, etc.) y usa el JSON literal como params del botón Native Flow.

Crear Flows

Abre el WhatsApp Business Manager para crear y gestionar tus Flows personalizados (obtén el flow_id aquí).

Flows Playground

Prueba y prototipa schemas de Flow en el playground oficial de Meta antes de enviarlos a producción.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":           "5511999999999",
    "message":          "Take the quick survey and earn 10% off",
    "buttonLabel":      "Take survey",
    "buttonParamsJSON": "{\"flow_message_version\":\"3\",\"flow_token\":\"my-token-123\",\"flow_id\":\"123456789012345\",\"flow_cta\":\"Take survey\",\"flow_action\":\"navigate\",\"flow_action_payload\":{\"screen\":\"WELCOME\"}}"
  }'

Respuesta exitosa

El messageType retornado es interactive (un formulario es una variación de mensaje interactivo Native Flow), y content refleja el message que enviaste. Guarda el messageId (y el flowToken, generado automáticamente cuando no envías uno) para correlacionar con la respuesta del flujo en el webhook.

200 OK

{
  "success": true,
  "message": "Form message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "interactive",
    "content":     "Lock in your spot in the course with 50% off!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "my-instance"
    }
  }
}

Cuando el usuario llena y envía el formulario, WhatsApp envía un mensaje interactive_response cargando el flow_token (el UUID que proporcionaste o el autogenerado) y el JSON con las respuestas. Captúralo vía webhook/websocket para correlacionar con el envío original.

Parámetros de ruta

instance

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

token

string

requerido

TokenAccount o TokenInstance.

Content-Type

string

requerido

application/json

Cuerpo de la solicitud

number

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us).

message

string

requerido

Texto mostrado en la burbuja del mensaje, sobre el botón que abre el Flow.

formType

string

predeterminado:"registration_offer"

Tipo de formulario preconfigurado: "contact_details" (Datos del cliente) o "registration_offer" (Oferta de registro). Ignorado si se proporciona buttonParamsJSON.

buttonLabel

string

predeterminado:"Add information"

Texto mostrado en el botón que abre el Flow (flow_cta).

flowToken

string

Token para correlacionar la respuesta del formulario con el envío. Cuando se omite, el servidor genera un UUID automáticamente. Puedes usar este token para vincularlo con un lead/oportunidad en tu CRM.

flowId

string

ID del Flow en WhatsApp Business. Defaults por formType:

contact_details → 1889354358373616
registration_offer → 892701196712475

Sobrescríbelo solo si pretendes usar un Flow personalizado por nombre (sin usar buttonParamsJSON).

flowMessageVersion

string

predeterminado:"4"

Valor flow_message_version enviado a WhatsApp.

messageVersion

int

predeterminado:"3"

message_version del payload Native Flow.

buttonParamsJSON

string

Escape hatch para flujos completamente personalizados. Cuando se proporciona, el servidor envía este JSON literal como params del botón Native Flow e ignora formType, flowId, flowToken, flowMessageVersion, messageVersion, todas las flags *Visible, offerName y offerDescription. Útil para integrar con flujos que has creado en WhatsApp Business Manager con schemas personalizados.

fullNameVisible

boolean

predeterminado:"true"

Muestra el campo “Full name” en el formulario. Ignorado si se proporciona buttonParamsJSON.

phoneNumberVisible

boolean

predeterminado:"true"

Muestra el campo “Phone number”.

emailVisible

boolean

predeterminado:"true"

Muestra el campo “Email”.

cpfOrCnpjVisible

boolean

predeterminado:"true"

Muestra el campo “CPF/CNPJ”.

deliveryAddressVisible

boolean

predeterminado:"true"

Muestra el campo “Delivery address”.

offerName

string

Título de la oferta mostrado dentro del Flow. Usado cuando formType=registration_offer.

offerDescription

string

Descripción de la oferta mostrada dentro del Flow. Usada cuando formType=registration_offer.

delay

int

predeterminado:"0"

Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor muestra el indicador “escribiendo…” al destinatario.

replyTo

string

ID del mensaje a responder. El mensaje original debe pertenecer a la misma instancia y estar guardado en la base de datos.

replyPrivate

boolean

predeterminado:"false"

Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original.

source

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, landing-sales, n8n).

Notas

Los Flows contact_details y registration_offer son plantillas preaprobadas de WhatsApp listas para usar. Si necesitas un formulario con campos específicos (preguntas personalizadas, lógica de pantalla), usa buttonParamsJSON con tu propio Flow.
El flowToken es tu identificador para vincular la respuesta del formulario con el registro originador (lead, pedido, etc.). Si no envías uno, guarda el UUID autogenerado para poder correlacionar después.
Cuando se envía buttonParamsJSON, todos los demás campos relacionados con el Flow se ignoran, tomas el control total del payload, incluyendo flow_id, flow_action, flow_action_payload y flow_message_version.
Native Flow solo funciona en chats 1-a-1 (@s.whatsapp.net) y grupos (@g.us); las newsletters (@newsletter) no son compatibles con WhatsApp.
La respuesta del formulario llega como un evento interactive_response, no es un mensaje de texto regular, así que maneja el webhook en consecuencia.

Errores

HTTP	Status interno	Mensaje
400	,	`Instance name is required`
400	,	`Invalid request: <detail>`
400	,	`Number is required`
400	,	`Message is required`
400	`invalid_number`	`Invalid phone number format: <detail>`
400	`reply_message_not_found`	`Original message not found (ID: ...)`
400	`reply_message_instance_mismatch`	`Original message does not belong to this instance`
400	`private_reply_failed`	(motivo del fallo de redirección privada)
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "Message is required" }
}

​Descripción

​Ejemplos

​Oferta de registro (registration_offer)

​Captura de datos de contacto (contact_details)

​Flujo personalizado vía buttonParamsJSON

Crear Flows

Flows Playground

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Oferta de registro (registration_offer)

Captura de datos de contacto (contact_details)

Flujo personalizado vía `buttonParamsJSON`

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores