Skip to main content
Poku forms let your AI agent collect structured data from a recipient mid-conversation or mid-task. The agent sends a unique Poku form link, the recipient fills out the form, and the response comes back to the agent via HTTP response or to your webhook.

​
How it works

  1. Your agent sends a form
  2. The recipient receives a link and opens the form in their browser
  3. They fill out the fields and submit
  4. The content is returned in the HTTP response if the form was filled out within the waitTime window. Otherwise, the form response can be delivered to your webhook within the followUpTime window.

​
Example: Dental customer intake form

Form SMS message received by recipient
Dental intake form
curl -X POST https://api.pokulabs.com/forms/sms \
  -H "Authorization: Bearer <your-poku-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi! Please complete your dental intake form before your appointment: {{url}}",
    "title": "Dental Patient Intake",
    "description": "Please fill out the fields below so we can prepare for your appointment.",
    "fields": [
      {
        "id": "name",
        "label": "Full Name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Smith"
      },
      {
        "id": "phone",
        "label": "Mobile Phone Number",
        "type": "phoneNumber",
        "required": true
      },
      {
        "id": "address",
        "label": "Home Address",
        "type": "address",
        "required": true
      },
      {
        "id": "insurance_id",
        "label": "Insurance ID / Member Number",
        "type": "text",
        "required": true,
        "placeholder": "e.g. BCBS123456789"
      },
      {
        "id": "issues",
        "label": "Describe any pain, sensitivity, or concerns",
        "type": "textarea",
        "required": false,
        "placeholder": "e.g. tooth pain upper right, sensitivity to cold..."
      }
    ],
    "to": "<your-phone-number>",
    "submitLabel": "Submit",
    "waitTime": 300,
    "followUpTime": 3600
  }'

​
Building a form

A form is defined inline in the API request. Each request includes the form’s content and the delivery details.

​
Form-level fields

FieldRequiredDescription
titleYesDisplayed at the top of the form
fieldsYesArray of input fields (see below)
descriptionNoSubtitle shown below the title
brandImageUrlNoYour logo, shown above the title
submitLabelNoLabel on the submit button. Defaults to Submit

​
Form fields

Each item in the fields array defines one input:
FieldRequiredDescription
idYesUnique key used in the response payload
labelYesText displayed above the input
typeYesInput type (see below)
requiredNoWhether the field must be completed. Defaults to false
placeholderNoPlaceholder text inside the input
helperTextNoSupplementary text shown below the input
optionsNoRequired for select fields — array of { label, value }
validationsNoRegex validation rules for text, textarea, email, and phoneNumber fields

​
Field types

TypeDescription
textSingle-line text input
textareaMulti-line text input
emailText input with built-in email validation
phoneNumberCountry code dropdown + phone number input
selectDropdown with predefined options
checkboxBoolean checkbox
addressAddress input with Google Places validation

​
Validations

Add custom regex rules to text, textarea, email, and phoneNumber fields. Each rule requires a title (shown below the field if it fails) and a pattern (regex the input must match). 
{
  "id": "code",
  "label": "Promo Code",
  "type": "text",
  "validations": [
    { "title": "Must be 6 characters", "pattern": "^.{6}$" },
    { "title": "Letters and numbers only", "pattern": "^[A-Za-z0-9]+$" }
  ]
}

​
waitTime and followUpTime

waitTime sets a countdown timer displayed directly on the form. When it expires, the agent moves on — but the form stays accessible for followUpTime.
ParameterDefaultBehavior
waitTimeNoneHolds the HTTP request open. Shown as a countdown on the form.
followUpTime90sKeeps the form open after waitTime. Submission delivered to your webhook. Once expired, the form shows “This form has expired.”
At least one field between waitTime or followUpTime must be supplied.

​
Response

When the form is submitted within waitTime: 
{
  "values": {
    "name": "John Smith",
    "email": "johnsmith@gmail.com"
  },
  "content": "Full Name: John Smith\nEmail Address: johnsmith@gmail.com"
}
values maps each field id to the submitted value. content is a formatted text summary your agent can read directly. When no submission is received within waitTime: 
{ "response": "Human did not respond. Continue where you left off." }

​
Channel Comparison

SMSWhatsAppSlack
API endpointPOST /forms/smsPOST /forms/whatsappPOST /forms/slack
Form deliveryLink sent via SMSFixed Poku template with form buttonLink sent via Slack message
Recipient requirementPhone number in supported countryWhatsApp accountMember of Poku workspace or own workspace via Pokubot
Customizable messageYes — defaults to "Please fill out this form: {{url}}"No — message is fixedYes — defaults to "Please fill out this form: {{url}}"