Follow Avox Docs on Google
Pick Avox Docs as a preferred source and Google shows these pages more often when you search for help with Avox.
Follow Avox Docs on Google
Pick Avox Docs as a preferred source and Google shows these pages more often when you search for help with Avox.
This page is written for an AI assistant (ChatGPT, Claude, Gemini, an agent in your own code) that has been given an Avox API key and asked to build something: a booking table, a template, a WhatsApp Flow, an automation. If you are a person, give your assistant this page's address together with the key, and ask it to read the page first.
Everything below is an instruction to the assistant. The full list of endpoints is on Builder API reference, the machine-readable version is /openapi.json, and every error code is on API errors.
Follow these rules in order. They keep the person's Switchboard safe and make every call succeed the first time.
Read the docs before calling anything
Read this page, then Builder API quick start and the reference page for the area you will build in: Tables and rows, Flows, Templates or Automations. The machine-readable schema of every request body is at /openapi.json. Never guess a field name: use the ones the docs and the schema show.
Authenticate with the key you were given, and nothing else
Send Authorization: Bearer <key> on every request to https://api.avox.com/api/v1/.... The key
starts with avx_live_ or avx_test_. Never ask the person for a password, a dashboard sign-in,
a Meta or WhatsApp token, or any other secret: the key is all you need. Never print the key back,
write it into files you share, or put it in a URL.
Call GET /api/v1/me first
It tells you the key's Switchboard, its WhatsApp number, its scopes (what it may do), and
every limit with what's already used: tables, rows per table, Flows, templates, automations,
live requests this month, and today's builder calls (reads and writes). Plan your work so it fits.
If a scope you need is missing, stop and tell the person which one (for example
tables:write): an Admin adds it in Settings > API Keys > Permissions.
Call GET /api/v1/catalog next
It lists the premade tables, Flows, templates and automations with their ids, what each needs, and the allowed column types, trigger types and step types. Starting from a premade is faster and safer than building from scratch: prefer one when it fits what the person asked for.
Build in this order: table, template, Flow, automation
Later pieces point at earlier ones by id, so make them in this order:
POST /api/v1/tables, then rows). A Flow or automation that uses a table
needs its id and its column ids.POST /api/v1/templates). WhatsApp reviews every new template; it is
PENDING until WhatsApp decides. An automation can only be switched on with approved
templates, so check GET /api/v1/templates/{id} until status is APPROVED (reviews can take
from minutes to a day; don't poll faster than once a minute).POST /api/v1/flows makes a draft). Validate it, fix what the validation
reports, then publish it.POST /api/v1/automations). They are created as drafts; switch one on
with POST /api/v1/automations/{id}/activate only when the person wants it live.Always validate before you publish
For a Flow, call POST /api/v1/flows/{id}/validate (or POST /api/v1/flows/validate with JSON
before you create it) and fix every item in validation.lint.errors,
validation.lint.live (severity error) and validation.validationErrors before
POST /api/v1/flows/{id}/publish. A published Flow can't change. For an automation, read the
problems list each save returns and fix them before you activate it.
Send an Idempotency-Key with every create
Make a new random value (a UUID) for each new thing you create and send it as the
Idempotency-Key header. If a request times out or you aren't sure it worked, retry with the
same key and the same body: you get the first result back and nothing is made twice. A
different body with the same key is refused (idempotency_conflict).
Send If-Match when you change something
Every item comes with an etag. When you change it, send If-Match: <etag>. If someone changed
it in the meantime you get 412 version_conflict and nothing is written: read it again, apply
your change to the new version, and retry. For rows, send each row's updatedAt instead.
Respect the limits
Every call counts against the plan's daily builder calls (reads and writes apart; see
limits.apiCallsToday in /me, and the Avox-Daily-Remaining header on every answer). Prefer
one bulk request (up to 1,000 rows) over many single ones. On 429, wait the number of seconds
in Retry-After before retrying. Never loop on an error.
Read every error and fix the cause
Errors look like { "ok": false, "error": { "code", "message", "docs_url", "request_id", "details" } }.
details lists each problem with a path (the field, like rows[3].price or
actions[1].actionConfig.templateId) and a message. Fix exactly those fields and retry. The
docs_url explains the code and what to do. Retry unchanged only for rate_limited,
idempotency_in_progress, meta_unreachable and internal_error.
Confirm before anything is deleted or goes live
Ask the person before you delete a table, column, row, Flow, template or automation, before you
publish a Flow, and before you switch an automation on. Never send force: true or
confirm: true without telling the person what will happen (the error that asks for it lists
what would break or which values would be emptied).
Some things stay in the dashboard on purpose. Tell the person to do these there when they come up:
A test key (avx_test_...) can read everything its scopes allow and run every check
(/me, /catalog, lists, validate, a CSV import dry_run), but every change is refused with
test_key_read_only. Use one to plan and check your work; use a live key to make it.
This is what a good session looks like for "set up booking reminders for my salon".
# 1. Who am I, what may I do, what's left on the plan?
curl https://api.avox.com/api/v1/me -H "Authorization: Bearer $AVOX_API_KEY"
# 2. What can I start from?
curl https://api.avox.com/api/v1/catalog -H "Authorization: Bearer $AVOX_API_KEY"
# 3. The Appointments table, from its premade.
curl -X POST https://api.avox.com/api/v1/tables \
-H "Authorization: Bearer $AVOX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1e8a1c-4b6e-4a55-9a43-2a1c3e7d9b10" \
-d '{"premadeId":"appointments"}'
# 4. The reminder template, from the Avox library (WhatsApp reviews it).
curl -X POST https://api.avox.com/api/v1/templates \
-H "Authorization: Bearer $AVOX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0d3b2f9e-8f61-4c0b-a0a7-5d7f1e2c4b88" \
-d '{"libraryId":"booking_reminder","language":"en_US"}'
# 5. Once the template is APPROVED: the premade automation, as a draft.
curl -X POST https://api.avox.com/api/v1/automations \
-H "Authorization: Bearer $AVOX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9a7c5e3b-1d2f-4e6a-8b9c-0f1e2d3c4b5a" \
-d '{"premadeId":"booking_reminder_day","timeZone":"Asia/Kolkata"}'
# 6. After the person says yes: switch it on.
curl -X POST https://api.avox.com/api/v1/automations/AUTOMATION_ID/activate \
-H "Authorization: Bearer $AVOX_API_KEY"
If step 5 answers automation_not_ready, its details say exactly what's missing (a table made
from a premade table, an approved template, a connected app) and how to make it.
Last updated