Contact Form 7 tag syntax is fiddly: the asterisk that marks a field required, the difference between options and values, the quoting rules for an option containing a space.
contact-form-7/add-form-field composes the tag from named arguments and inserts it into the template, with a label wrapper when you supply a label.
At a glance
| Ability | contact-form-7/add-form-field |
| Toolset | Contact Form 7 — toolset/contact-form-7 |
| Group | Contact Form 7 › Fields & Template |
| Requires | Contact Form 7, active on the site |
| Capability | manage_options, plus edit_contact_forms |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
What this does not do
The new field name becomes available as a mail tag the moment it exists — but nothing adds it to a mail template. A field that collects data no notification references is the most common way information gets quietly lost. Follow with contact-form-7/update-mail to put [your-new-field] in the body.
How it works
Check contact-form-7/list-field-types first. The available types depend on which Contact Form 7 modules and add-ons are active, and a type the site does not know renders as literal text on the front end.
The field is appended by default — before or after the submit button depending on how the template is written. Pass prepend: true to put it first instead.
Pass required: true rather than writing the asterisk yourself. The tag is composed for you, and options with spaces in their values are quoted correctly.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
form_id | integer | Yes | Form post ID, as returned by contact-form-7/list-forms. |
type | string | Yes | Field type, e.g. text, email, tel, textarea, select. Omit any trailing asterisk and use required instead. |
name | string | Yes | Field name, used as the mail tag. Letters, digits, hyphens and underscores. |
label | string | No | Visible label. Omit to emit the tag with no label wrapper. |
required | boolean | No — defaults to false | Marks the field required. |
options | array of strings | No | Tag options, e.g. class:wide, id:enquiry-phone or maxlength:40. Write each as key:value; a value containing spaces is quoted for you, and one with a space but no key is refused. |
values | array of strings | No | Quoted values, e.g. the choices of a select or radio field. |
prepend | boolean | No — defaults to false | Insert at the start of the template rather than the end. |
What comes back
| Name | Type | What it is |
|---|---|---|
form_id | integer | The form that was written. |
field | object | The field as parsed back out of the template. |
tag | string | The tag that was composed. |
template | string | The template after the insert. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Add a required phone field to form 42, labelled “Phone number”.
It resolves to one call:
{
"ability": "contact-form-7/add-form-field",
"parameters": {
"form_id": 42,
"type": "tel",
"name": "your-phone",
"label": "Phone number",
"required": true
}
}Worth knowing
- Not idempotent — calling it twice gives the form two fields with the same name, which Contact Form 7 handles badly.
- The field is not in any mail template until you put it there.
- A type this site has not registered renders as literal text on the front end rather than failing loudly.
Related abilities
- List Contact Form Field Types — check the type exists here first
- Update Contact Form Mail Template — put the new field in the notification
- Update Contact Form Field — change it once it exists
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category