How-to guide

Form links

Send a person a link to a form during a call, watch them fill it in, and read what they submit.

Limited today. Form links work with a fixed set of forms that VoiceLayer provides: demo-intake and auto-damage-evidence. You cannot add your own form through the API or the dashboard yet. Use this page if one of those fits, or to see how the feature works.

What you'll build

A link to a short form, sent by text or email, that the person fills in on their phone while your agent is on the line. You see each field as it is set and the final submission.

Prerequisites

  • A secret API key with the sdk:write scope. See Authentication and API keys.
  • To text the link, a phone number in your workspace (its id goes in sendSms.phoneNumberId) and a registered texting program. To email it, an address to send to.
  • curl.

POST /v1/forms creates a session and, if you ask, sends the link. This route is not in the generated clients, so use curl.

curl -s https://api.vlayers.ai/v1/forms \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "demo-intake",
    "recipientPhone": "+15550123",
    "recipientName": "Ada Lovelace",
    "prefill": { "firstName": "Ada" },
    "ttlSeconds": 3600,
    "sendEmail": { "to": "[email protected]", "subject": "Your intake form" }
  }'
  • formId and recipientPhone (E.164) are required. recipientName, prefill, webhookUrl, callbackFromNumber, sendSms and sendEmail are optional.
  • ttlSeconds is 60 seconds to 90 days. After that the link is expired.
  • Set sendSms (phoneNumberId, optional bodyPrefix) or sendEmail (to, optional subject and bodyPrefix), or both. Set neither to get the link back and deliver it yourself.
{
  "sessionId": "…",
  "token": "…",
  "url": "https://<your forms host>/f/<token>",
  "smsId": null,
  "emailId": "…",
  "expiresAt": "2026-11-04T16:04:05.000Z"
}

Anyone who has the url can read and fill the form, so send it only to the person it is for.

Errors: 404 form_not_found (not one of the provided forms), 400 invalid_webhook_url, 422 output_refused (the message text was refused), 502 sms_send_failed or email_send_failed.

Step 2: Watch the form during the call

In a voice agent, ctx.watchFormSession(token) follows the form while the call is live. It returns a function that stops watching. It is not available on a text conversation.

import { defineAgent, defineTool } from '@voicelayer/sdk';

export default defineAgent({
  name: 'intake',
  prompt: 'You collect intake details. When the caller has the form open, read their answers back.',
  capabilities: ['system.say'],
  tools: {
    ...defineTool({
      name: 'watch_form',
      description: 'Start following the form the caller was sent',
      input: { token: 'string' },
      run: async ({ token }, ctx) => {
        // keep the returned function if you want to stop watching early
        ctx.watchFormSession(token);
        return { watching: true };
      }
    })
  }
});

While you watch, the call's timeline records the form's events, with source: 'form': form.opened, form.field_set, form.fields_set, form.status, form.call_state and form.submitted.

Step 3: Read what was submitted

GET /v1/forms/responses lists submissions. Filter with formId, limit (1 to 200) and before (a time). This route takes a signed-in dashboard session, not an API key.

If you set webhookUrl when you created the link, VoiceLayer also posts to that address when the form is submitted.

Next steps

On this page