VYG Docs
Guides for brand teams

Sign-up forms

Check, edit, publish and pause your SMS, WhatsApp and Telegram sign-up forms with Claude, and see who signed up.

Sign-up forms are the pop-ups and inline forms that grow your text list. Claude can read how each form is doing, edit the draft, publish, schedule, pause, resume, duplicate or archive it, and import lists of people who signed up somewhere else. It uses four tools:

ToolWhat it does
signup_formsReads forms, their stats, published versions, where they are installed, and recent sign-ups.
manage_signup_formCreates, edits, publishes, schedules, pauses, resumes, duplicates and archives forms.
subscribe_signup_formAdds one person to a form. They get a confirmation text.
import_subscribersImports a list of people who already opted in, such as sign-ups from an event.

Who can use these tools

The tools follow the same rules as the Sign-up forms pages in vyg.ai. Reading (and subscribe_signup_form) needs sign-up forms turned on for your brand. Changing a form also needs permission to edit campaigns, the permission the editor asks for, and you must be signed in with your own VYG login (not an API key). If signup_forms is there but manage_signup_form is not, you can read forms but not change them. If the tools are missing, contact your VYG account manager.

Check your forms

  • "Which sign-up forms do we have, and which are live?"
  • "How many people signed up through the VIP form last month, and how many confirmed?"
  • "Is the pop-up showing on our Shopify store?"

signup_forms takes a view:

viewReturns
listEvery form with its status, channel (SMS, WhatsApp or Telegram) and the ways in that are on.
getOne form: texts, consent wording, schedule, the revision, and the "Before you publish" checklist.
statsSubmits, subscribers, conversion rate and failed opt-in asks, for one form or all of them, over a range.
versionsPublished versions, newest first, with the live one marked.
embed_statusWhether the Shopify theme embed has loaded lately, your store domains, and share links.
submissionsRecent opt-in events for one form.

Submissions are a record of consent, not a contact export. Phone numbers and emails are masked (+1••••••0100, a•••@example.com), the IP address and browser are never returned, and each row carries the consent wording the person saw when they signed up.

Edit and publish

Changes go to the form's draft first. Shoppers keep seeing the live form until you publish.

  • "Change the VIP form's confirmation text to mention our 15% welcome offer."
  • "Only show the pop-up on /collections pages, after 10 seconds."
  • "Publish the VIP form."
  • "Schedule the holiday form to start on 1 December at 9am New York time."
  • "Pause the giveaway form."
  • "Throw away my unpublished changes to the VIP form."
  • "Make a copy of the VIP form for the spring sale."

manage_signup_form takes an op:

opWhat it does
create_from_templateCreates a draft form from a template, with its own welcome series.
update_draftSaves changes to the draft. Shoppers still see the live form.
discard_draftThrows the unpublished changes away. The draft goes back to the live form.
publishPuts the draft live and records a version.
schedulePublishes a form that is not live yet so it starts later, and stops at an end time.
cancel_scheduleCancels the schedule of a form that has not started. It goes back to a draft.
pauseStops showing a live form.
resumeShows a paused form again.
restore_versionCopies a published version into the draft.
duplicateCopies a form into a new draft named "(name) (copy)" with its own welcome series.
archiveStops showing the form and moves it out of the list of forms.

These run the same code as the buttons in vyg.ai. A copy does not get the original's ways in (keywords, links, QR codes), so it cannot take sign-ups meant for the original; turn them on for the copy in the editor. Claude reads the form first and sends the expected_revision it read, so it never overwrites a change someone made in the editor in the meantime; if the form changed, the call is refused and Claude reads it again.

Publishing, scheduling and resuming run the same "Before you publish" checklist as the editor and the on/off switch in the list of forms, for the form's channel. For SMS that means the consent wording names your brand and says message frequency, "Msg & data rates may apply", STOP and HELP, with Terms and Privacy links, and the confirmation text asks for a Y reply. WhatsApp and Telegram forms need their own wording and a connected account. A form that fails a check is not published, and there is no override.

Claude edits the name, display settings and texts. Change the design itself (blocks, colors, images) in the sign-up form editor in vyg.ai.

Display and timing settings Claude can change in update_draft settings:

SettingWhat it does
trigger_modeany opens the form on the first timing rule; all waits until every rule has happened.
auto_close_secondsCloses an unanswered pop-up after this many seconds. null keeps it open.
close_after_submit_secondsCloses the thank-you step after a sign-up. null keeps it.
hide_after_submit_daysAfter a sign-up through this form, hides it for this many days, or never shows it again.
site_waitWaits for something on your page: a CSS selector, or a cookie banner (consent).
sms_inbound_opt_inSMS forms: single subscribes people who text the join message without a Y reply.

Waiting for the BigCommerce cookie banner needs BigCommerce connected, as in the editor.

Collecting email

Brands with email (beta:email-channel) can have an SMS form collect email too, as in the editor's email panel:

  • collect turns email and SMS collection on or off. At least one stays on. Turning email on adds an Email step when the design has no email field.

  • email_opt_in is single (the default) or double. Double opt-in sends a confirmation email first.

  • confirmation_template_id is the confirmation email for double opt-in. signup_forms view: "get" lists the ones the form can send under email_confirmation_templates. A double opt-in form cannot publish without one.

  • "Make the VIP form collect email too, with double opt-in, using the system confirmation email."

Add one person

subscribe_signup_form adds a person to a live form whose API way in is on. It sends a real text, so Claude confirms with you first.

  • The person gets a confirmation text and is subscribed only after they reply Y.
  • Claude must pass the consent wording they agreed to, word for word (at least 20 characters).
  • Forms with an age gate need a date of birth.
  • Daily limits and cooling periods apply, the same as the List building API.
  • A Telegram form answers text_start_required and sends nothing: the person joins by opening the form's Telegram link and pressing Start.
  • A WhatsApp form only takes sign-ups through the form itself.

The older tool subscribe_list_building_campaign still works and points to subscribe_signup_form.

Import a list

import_subscribers imports a list of phone numbers you collected somewhere else, such as a sign-up sheet at an event. Give each import a title. The file needs a phone column; status, first_name, last_name and email are optional:

phone,status,first_name,last_name,email
(214) 555-0100,subscribed,Michelle,Hobbs,michelle@example.com
214-555-0101,,Jacob,,
2145550102,unsubscribed,,,
  • "Import the attached list from this weekend's Fort Worth show."

  • "Which imports have we run, and how many people did each add?"

  • Claude previews the import first and tells you how many people are new, already subscribed, unsubscribed, or skipped.

  • A blank status means subscribed. For the subscribed rows, you confirm that those people agreed to receive marketing texts from you.

  • Subscribed people are added right away. No confirmation or welcome text is sent.

  • Numbers that texted STOP or are blocked are never resubscribed.

  • Rows marked unsubscribed are added as unsubscribed, or switch an existing subscriber off.

  • A number you already have is updated in place, not added twice.

  • Campaigns can go to the people on one import's file who are subscribed, including people who already were.

  • Past imports and the rows they skipped are in signup_forms views imports and import.

  • To import from your own systems, use POST /v1/list-building/imports with CSV text or JSON rows (up to 5,000 per import).

On this page