The forms of the number
https://api.app2email.com/v1/{number}/submit/forms Scope: submissions:manage. Every form with its key, name, whether it is enabled, archived and published, whether the working copy differs from the published version (changed), its state on WhatsApp, its links and how many submissions it has. Definitions are left out: GET /submit/forms/{key} has one form's definition and fields.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270
Responses
Fields
- success boolean
- request_id string
- forms object[]
15 item fields
- id integere.g.
7 - key string
The form's name in the API and in its web address.
e.g.meter_reading - name stringe.g.
Meter reading - enabled boolean
false: its words and links answer nothing new; its submissions stay.
- archived boolean
true: hidden from the lists, takes no submissions.
- position integer
- definition object
The working copy. One form only.
12 fields
-
The form's public name, 1 to 60 characters.
e.g.Meter reading -
Under the title on the web page and in the forms menu, up to 300 characters.
- prefix string
2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). "" = the settings' default_prefix.
e.g.MR -
1 to 12 steps, in the order they are asked. One step is one screen; app2email splits a step over several screens by itself when WhatsApp's limits demand it.
-
2 to 12 stages a submission moves through. The first one is where a new submission starts. At least one of kind open and one of kind done. Left out: New (open), In progress (open), Done (done).
- who object
Who may submit.
3 fields
- trigger object
The message that opens the form on WhatsApp, and the words that send it.
5 fields
- words array
A contact who sends one of these words gets the form. Up to 10 words, 30 characters each. A word that another form of the number or an enabled Book-and-Pay word already uses is refused (word_taken).
e.g.["meter"] - header string
A bold line above the body, optional.
- body string
The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form.
e.g.Tap the button to send your reading.
- after object
What happens right after a submission.
4 fields
-
A last screen that lists the answers before sending.
- reply string
The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). "" = no reply. Left out: a thank-you with the reference.
-
The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission.
-
The reply carries a button to the submitter's status page.
-
- web object
The web page of the form.
4 fields
-
The form has a web page (links.web of the form).
-
Proving the WhatsApp number of a web submission with one message. optional: offered as Get updates on WhatsApp. required: the submission counts only once proven. off: never asked.
-
Also ask for an e-mail address at the end.
- success_text string
Shown after sending. "" = the standard text.
-
- notify object
The e-mail the business gets.
3 fields
-
E-mail the business for each submission (to the settings' notify_email).
- to array
Up to 5 more addresses.
-
Attach the submission's files.
-
-
0 to 20 calculated fields: values worked out from the answers each time they change, stored in extra. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0.
-
0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650).
-
- published object | null
The version live on WhatsApp, or null when it was never published.
2 fields
- hash stringe.g.
3f9a1c0b7d2e - published_at string (date-time)
- changed boolean
true: the working copy differs from the published version: publish to make it live on WhatsApp. false also while the form was never published (published is null then).
- flow object
The form's state on WhatsApp.
6 fields
- id string
Meta's id of the WhatsApp Flow. Empty until published.
- status string
Meta's status. Only PUBLISHED is sent to customers.
DRAFTPUBLISHEDDEPRECATEDBLOCKEDTHROTTLED - validation_errors object[]
Meta's complaints about the generated form, when there are any.
- checked_at string
When the status was last read from Meta. Empty: never.
- last_error string
Why the last publish failed. Empty when it worked.
- can_send boolean
true: the form can be sent inside WhatsApp now. false: its words and the send route answer with the web link.
- links object
How people reach the form.
- counts object
Its submissions.
- fields object[]
Every field and calculated value as a column. One form only.
- created string (date-time)
- updated string (date-time)
- count integer
Errors
- 400 The request is malformed (missing or invalid fields, query parameters or times).
- 401 Missing, invalid, revoked or expired API key.
- 403 The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account.
- 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found.
- 429 A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait.
- 500 Unexpected error on app2email's side.
- 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.