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.
Build automations from your own code or an AI assistant. Every save is checked
exactly as in the dashboard's builder: each step's settings, the {{...}} values each message
uses, and the tables, columns, templates, Flows and apps the automation points at. Needs
automations:read / automations:write (deleting also needs Delete automations for the
person who set the key's permissions). Basics: Builder API quick start.
The JavaScript examples use the avox() helper from Builder API reference.
An automation is a trigger (triggerType and its triggerConfig) and a list of steps
(actions, each { "actionType", "actionConfig" }, run in order). Every new automation is a
draft: it runs only after POST /api/v1/automations/{automationId}/activate, which needs at
least one step, no problems, an unpaused Switchboard, approved templates, published Flows, and
room in your plan's automations that are on.
The trigger types, step types and their settings are the ones the builder shows; the full list
is in GET /api/v1/catalog (types.triggerTypes, types.actionTypes) and the schemas are in
/openapi.json. See Automation and
Automations with tables and Flows for what each does. The fastest and
safest start is a premade.
Table and column ids in a step's settings are the ids from GET /api/v1/tables/{tableId} (not
the keys). Messages use values like {{contact.first_name}}, {{row.price}} (a table trigger's
row) or {{order.status|unknown}} (an earlier Find a row step named order, with a fallback).
An automation's fields: id, name, status (draft, active, paused), triggerType,
triggerConfig, premadeId, stepCount, createdAt, updatedAt, etag, and with a single
automation, actions and canvas.
Query: status, limit (1 to 100), cursor.
curl "https://api.avox.com/api/v1/automations?status=active" -H "Authorization: Bearer $AVOX_API_KEY"
const { data } = await avox("/automations");
Creates a draft automation, all or nothing (it's made only when its steps can be saved). Counts
against your plan's automations; send an Idempotency-Key.
From a premade (ids in GET /api/v1/catalog): premadeId, and optionally name,
timeZone (for date and table triggers) and utcOffsetMinutes (for Business hours). The premade
is fitted to your Switchboard exactly as the dashboard does it: your table made from the premade
table it needs, your connected app, your approved template made from the Avox template it was
written for. When something's missing, the answer is automation_not_ready and details lists
each missing table (with the premadeId to create it from), app or approved template, and
nothing is made.
From a trigger and steps: name, triggerType, triggerConfig, and optionally actions.
curl -X POST https://api.avox.com/api/v1/automations \
-H "Authorization: Bearer $AVOX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4e8d2c6a-0b1f-4d7e-9c3a-5f6e7d8c9b0a" \
-d '{
"name": "Opening hours reply",
"triggerType": "keyword",
"triggerConfig": { "keywords": ["hours", "timing", "open"] },
"actions": [
{ "actionType": "send_text", "actionConfig": { "body": "Hi {{contact.first_name|there}}! We are open 10 am to 8 pm, Monday to Saturday." } }
]
}'
const { ok, data, error } = await avox("/automations", {
method: "POST",
headers: { "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({ premadeId: "booking_reminder_day", timeZone: "Asia/Kolkata" }),
});
if (!ok && error.code === "automation_not_ready") {
for (const d of error.details) console.log(d.path, d.message); // what to create first
}
Answers 201 with { automation, problems }. problems (also in warnings) are things that
must be fixed before it can be switched on, each with the step (actions[2] or trigger) and an
AVX code, like a table that was archived or a template variable with no value.
The automation with its trigger and steps, and its current problems.
curl https://api.avox.com/api/v1/automations/AUTOMATION_ID -H "Authorization: Bearer $AVOX_API_KEY"
const { data } = await avox(`/automations/${automationId}`);
Changes name, triggerType (always with its triggerConfig), triggerConfig, actions (the
whole list: steps you leave out are removed) and canvas. Changing the steps ends runs that are
waiting for a reply. Switch it on or off with the endpoints below, not here. Send If-Match with
the automation's ETag.
curl -X PATCH https://api.avox.com/api/v1/automations/AUTOMATION_ID \
-H "Authorization: Bearer $AVOX_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "Lp2..."' \
-d '{ "name": "Opening hours reply (weekdays)" }'
const { data: current } = await avox(`/automations/${id}`);
const actions = [...current.automation.actions, { actionType: "send_text", actionConfig: { body: "Anything else?" } }];
await avox(`/automations/${id}`, { method: "PATCH", headers: { "If-Match": current.automation.etag }, body: JSON.stringify({ actions }) });
Switches it on. Refused with automation_not_ready (problems, no steps, a template that isn't
approved, a Flow that isn't published; details names the step), switchboard_paused, or
plan_limit_reached (all the automations your plan allows are on).
curl -X POST https://api.avox.com/api/v1/automations/AUTOMATION_ID/activate -H "Authorization: Bearer $AVOX_API_KEY"
const { ok, error } = await avox(`/automations/${id}/activate`, { method: "POST" });
Switches it off (status paused); runs waiting for a reply end.
curl -X POST https://api.avox.com/api/v1/automations/AUTOMATION_ID/deactivate -H "Authorization: Bearer $AVOX_API_KEY"
await avox(`/automations/${id}/deactivate`, { method: "POST" });
Deletes it for good, with its "Used by" links on tables and templates. Needs Delete automations.
curl -X DELETE https://api.avox.com/api/v1/automations/AUTOMATION_ID -H "Authorization: Bearer $AVOX_API_KEY"
await avox(`/automations/${id}`, { method: "DELETE" });
Every run, newest first: the contact, what started it, when, how it ended and why, credits and
steps, plus counts per outcome. Query: from, to (times with their offset, at most 366 days
apart), outcome, trigger, limit (10, 25, 50 or 100), cursor.
curl "https://api.avox.com/api/v1/automations/AUTOMATION_ID/runs?limit=25" -H "Authorization: Bearer $AVOX_API_KEY"
const { data } = await avox(`/automations/${id}/runs?limit=50`);
One run step by step: each step, its values, the messages it sent with their status, the rows it read or wrote, and why it stopped (with the AVX code).
curl https://api.avox.com/api/v1/automations/AUTOMATION_ID/runs/RUN_ID -H "Authorization: Bearer $AVOX_API_KEY"
const { data } = await avox(`/automations/${id}/runs/${runId}`);
Credits used this period and all time, per run, per step that costs credits, per day (in tz,
an IANA time zone, default UTC), its share of the Switchboard's credits, and next month at the
current pace.
curl "https://api.avox.com/api/v1/automations/AUTOMATION_ID/credits?tz=Asia/Kolkata" -H "Authorization: Bearer $AVOX_API_KEY"
const { data } = await avox(`/automations/${id}/credits?tz=UTC`);
Last updated