Send Form

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

Description

Sends a message with a button that opens a WhatsApp Native Flow, a native form that collects structured data (name, phone, email, CPF/CNPJ, address) without leaving the conversation. It supports two ready-made flows: contact_details (Customer details) and registration_offer (Registration offer), plus an escape hatch via buttonParamsJSON for fully custom flows. Ideal for lead capture, sign-ups and offers with quick confirmation.

Client compatibility: Native Flows are not yet supported on WhatsApp Web/Desktop. The form button will only render for recipients on the official Android and iOS apps, on other clients the message will appear without the interactive button.

Examples

Registration offer (registration_offer)

Sends an offer with title and description. The button opens the default registration Flow with configurable visible fields.

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

Contact data capture (contact_details)

Uses WhatsApp’s official contact_details flow. Hide fields you don’t want to ask for via the *Visible flags. Here we ask for name, phone and email only.

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

Custom flow via `buttonParamsJSON`

Escape hatch for your own flows (built in WhatsApp Business Manager). When buttonParamsJSON is provided, the server ignores every other flow-related field (formType, flowId, visibility flags, offerName, etc.) and uses the literal JSON as the Native Flow button params.

Create Flows

Open the WhatsApp Business Manager to create and manage your custom Flows (get the flow_id here).

Flows Playground

Test and prototype Flow schemas in Meta’s official playground before shipping to production.

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\"}}"
  }'

Success response

The returned messageType is interactive (a form is a variation of a Native Flow interactive message), and content echoes the message you sent. Save the messageId (and the flowToken, generated automatically when you don’t send one) to correlate with the flow response on the 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"
    }
  }
}

When the user fills in and submits the form, WhatsApp sends an interactive_response message carrying the flow_token (the UUID you provided or the one auto-generated) and the JSON with the answers. Capture it via webhook/websocket to correlate with the original send.

Path parameters

instance

string

required

Instance name (e.g., $Instance_Name).

Headers

token

string

required

TokenAccount or TokenInstance.

Content-Type

string

required

application/json

Request body

number

string

required

Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us).

message

string

required

Text shown in the message bubble, above the button that opens the Flow.

formType

string

default:"registration_offer"

Pre-configured form type: "contact_details" (Customer details) or "registration_offer" (Registration offer). Ignored if buttonParamsJSON is provided.

buttonLabel

string

default:"Add information"

Text displayed on the button that opens the Flow (flow_cta).

flowToken

string

Token to correlate the form response with the send. When omitted, the server generates a UUID automatically. You can use this token to tie it back to a lead/opportunity in your CRM.

flowId

string

Flow ID in WhatsApp Business. Defaults per formType:

contact_details → 1889354358373616
registration_offer → 892701196712475

Override only if you intend to use a custom Flow by name (without using buttonParamsJSON).

flowMessageVersion

string

default:"4"

flow_message_version value sent to WhatsApp.

messageVersion

int

default:"3"

message_version of the Native Flow payload.

buttonParamsJSON

string

Escape hatch for fully custom flows. When provided, the server sends this literal JSON as the Native Flow button params and ignores formType, flowId, flowToken, flowMessageVersion, messageVersion, every *Visible flag, offerName and offerDescription. Useful to integrate with flows you’ve built in WhatsApp Business Manager with custom schemas.

fullNameVisible

boolean

default:"true"

Shows the “Full name” field in the form. Ignored if buttonParamsJSON is provided.

phoneNumberVisible

boolean

default:"true"

Shows the “Phone number” field.

emailVisible

boolean

default:"true"

Shows the “Email” field.

cpfOrCnpjVisible

boolean

default:"true"

Shows the “CPF/CNPJ” field.

deliveryAddressVisible

boolean

default:"true"

Shows the “Delivery address” field.

offerName

string

Offer title displayed inside the Flow. Used when formType=registration_offer.

offerDescription

string

Offer description displayed inside the Flow. Used when formType=registration_offer.

delay

int

default:"0"

Time in seconds to wait before sending. During the interval, the server shows the “typing…” indicator to the recipient.

replyTo

string

ID of the message to reply to. The original message must belong to the same instance and be saved in the database.

replyPrivate

boolean

default:"false"

When true and replyTo points to a message originating from a group, the reply is redirected to the private chat of the original author.

source

string

default:"api"

Origin identifier for traceability (e.g., crm, landing-sales, n8n).

Notes

The contact_details and registration_offer Flows are pre-approved WhatsApp templates ready to use. If you need a form with specific fields (custom questions, screen logic), use buttonParamsJSON with your own Flow.
The flowToken is your identifier to tie the form response back to the originating record (lead, order, etc.). If you don’t send one, save the auto-generated UUID so you can correlate later.
When buttonParamsJSON is sent, every other Flow-related field is ignored, you take full control of the payload, including flow_id, flow_action, flow_action_payload and flow_message_version.
Native Flow only works in 1-to-1 chats (@s.whatsapp.net) and groups (@g.us); newsletters (@newsletter) are not supported by WhatsApp.
The form response arrives as an interactive_response event, it isn’t a regular text message, so handle the webhook accordingly.

Errors

HTTP	Internal status	Message
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`	(reason for the private redirect failure)
404	—	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Error envelope:

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

Introduction

Instance

Events

Messages

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Observability

Description

Examples

Registration offer (registration_offer)

Contact data capture (contact_details)

Custom flow via `buttonParamsJSON`

Create Flows

Flows Playground

Success response

Path parameters

Headers

Request body

Notes

Errors

Introduction

Instance

Events

Messages

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Observability

Documentation Index

​Description

​Examples

​Registration offer (registration_offer)

​Contact data capture (contact_details)

​Custom flow via buttonParamsJSON

Create Flows

Flows Playground

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

Description

Examples

Registration offer (registration_offer)

Contact data capture (contact_details)

Custom flow via `buttonParamsJSON`

Success response

Path parameters

Headers

Request body

Notes

Errors