Automations

Note

Paths are relative to the base URL: https://app.usenadia.com/api/public/v1. Every request needs an Authorization header holding your API key.

An automation is a template: a tree of steps drawn in the app (a trigger, messages with buttons, waits, conditions, actions). It carries no trigger word, no publication and no value. What runs is a pose of it on one publication: that publication’s trigger words, and one value per {variable} of the template. See Comment → DM automations for what the person on the other end experiences.

These endpoints do not exist in the original project. They are Instagram-only.

Endpoints

GET    /automation-flows                       the templates
POST   /automation-flows                       create one
GET    /automation-flows/{id}
PUT    /automation-flows/{id}                  name, channel, definition
PUT    /automation-flows/{id}/status           DRAFT, ACTIVE, PAUSED or ARCHIVED
DELETE /automation-flows/{id}
GET    /automation-flows/{id}/poses            where it is posed
POST   /automation-flows/{id}/poses            pose it on something already live
GET    /automation-flow-poses?integrationId=&mediaId=&workspace=   what runs on a channel, a publication or a workspace
GET    /automation-flow-poses/{id}
PUT    /automation-flow-poses/{id}             words, values, pause
DELETE /automation-flow-poses/{id}
GET    /automation-flow-poses/{id}/runs        the people
POST   /automation-flow-poses/{id}/poll        read the comments now
POST   /automation-flow-poses/{id}/replay      run on named comments
POST   /automation-flows/email-preview         render a Forward the email step's email
POST   /automation-flows/email-test            send yourself that email

Templates

GET /automation-flows lists them with status (ACTIVE and ARCHIVED ones run), issues (what blocks activation: level error, or a warning), and _count (poses, runs). POST (201) takes name (1 to 120 characters), integrationId (the Instagram channel the DMs go out from, nullable) and definition: the tree, whose shape is the one the editor writes; the server strips any words, publications or values it carries, since those belong to a pose. PUT /automation-flows/{id} takes the same three fields, each optional.

PUT /automation-flows/{id}/status with { "status": "ACTIVE" } is refused (400) while the template has an error.

{ "status": "ARCHIVED" } sets an ACTIVE template aside: its poses keep running as before, but POST /automation-flows/{id}/poses is refused, and so is any PUT /automation-flows/{id} that changes name, integrationId or definition (400). Only an ACTIVE template can be archived (400 otherwise: a PAUSED one is resumed first, a DRAFT is deleted), and an archived one only goes back to ACTIVE, with the same check as any activation. A post scheduled with a template archived since keeps it: the pose is still created when the post goes live.

Posing on a post you schedule

A post that has not published yet has no Instagram media ID, so there is nothing to pose on. Pass the template in the post’s Instagram settings on Create a post instead, and the pose is created the moment the post goes live:

"settings": {
  "post_type": "post",
  "automationFlowId": "<template id>",
  "automationKeywords": ["LIEN", "LEIN", "LIENS"],
  "automationVariables": { "ressource": "le guide Malte", "bouton": "Le guide", "lien": "https://…" }
}

Caution

The words and the values are checked when the post is scheduled: a missing variable, a button over 20 characters, a {lien} that is not a URL, a template that is not yours, and words or values sent without automationFlowId, are a 400. Nothing is dropped silently.

Posing on something already live

POST /automation-flows/{id}/poses

Field	Type	Required	Description
integrationId	string	Yes	The Instagram channel
mediaId	string	Yes	The post ID, or the story ID
kind	string	No	post (default: the template’s trigger) or story
keywords	string[]	Per template	The trigger words of this publication, 30 at most (a story reply needs none)
variables	object	Per template	One value per {variable} of the template

A template is posed once per publication. The response (201) is the pose.

Caution

Posing on a story is time-limited. A story lives 24 hours and is never collected into the video catalogue, so its ID comes from GET /inbox/stories/{integrationId} while it is live.

What runs

GET /automation-flow-poses?integrationId= lists the poses of a channel; add mediaId= for one publication. workspace= (an id from GET /workspaces) lists those of every channel of that workspace, instead of integrationId or with it: the channel must then be in that workspace, otherwise the list is empty. One of the two is required. Each pose carries its flow (id, name, status), its mediaId and source (post_comment or story_reply: what starts it), postId (the UseNadia post, when it came from the composer), its keywords, variables, active, and counts (runs, waiting, done, failed, emails).

PUT /automation-flow-poses/{id} changes keywords (30 at most), variables or active (false pauses this pose alone; the template’s status is the switch of them all). People already in the flow keep the tree they started on.

The people

GET /automation-flow-poses/{id}/runs?status=: one row per person, with their username, the keyword they used, their email once they gave it, and a status. It is what the app’s Export CSV writes, for an integration that collects the emails without a connected email tool:

Status	Meaning
PENDING	Matched, the first step not sent yet
WAITING	At a « wait for the answer » step
DELAYED	In a delay
DONE	Reached the end
HANDED_OFF	Handed to a human (the inbox shows it)
FAILED	error carries Meta’s message. Never retried by itself
SKIPPED	Ignored: once per person, own comment, a reply…

Poll and replay

POST /automation-flow-poses/{id}/poll reads the publication’s comments now and starts what a missed webhook left behind ({ checked, started }).

POST /automation-flow-poses/{id}/replay runs the automation on comments named by ID (commentIds, 1 to 50; resend restarts one that already has a run), whatever their date. One outcome per comment: started, or why not (not_on_post, already_has_a_run, no_keyword, once_per_user, is_a_reply, own_comment, no_author, outside_meta_7_day_window, pose_has_errors).

Caution

Replay is deliberately not a sweep: replaying a whole post would direct-message everybody who ever commented on it.

Previewing the email

A Forward the email step adds the contact to your email tool and can send them a template from that tool. In a template’s definition, it reads:

{
  "type": "action",
  "action": "forward_email",
  "provider": "resend",
  "destinationId": "…",
  "destinationName": "Guide readers",
  "templateId": "…",
  "templateName": "The link you asked for"
}

provider is the tool’s identifier (brevo, resend), or null while none is chosen. Ids are strings, Brevo’s included ("13"). An older "action": "brevo" step with listId is still read, and comes back in this shape.

Before anyone receives the email:

• POST /automation-flows/email-preview renders it with a run’s values, without sending anything. The answer (201) carries templateId, templateName, active (whether the tool would send the template: active on Brevo, published on Resend), the rendered subject and html, the template’s sender (name, email) and params, the values it was rendered with (LINK, RESOURCE, KEYWORD, USERNAME).
• POST /automation-flows/email-test actually sends it, to one address, and answers { "sent": true, "to": "…" }.

Field	Type	Required	Description
provider	string ≤ 50	Yes	The tool, the step’s provider (brevo, resend)
templateId	string ≤ 200	Yes	The template, the step’s templateId
brevoTemplateId	number	No, deprecated	Former shape, still accepted: read as provider: "brevo" with this templateId
dmLinkUrl	string ≤ 2,000	No	The link the DM gave
resourceName	string ≤ 200	No	The name of the resource
keyword	string ≤ 100	No	The trigger word
username	string ≤ 100	No	The person
to	string ≤ 320	Yes on the API (email-test)	Where to send the test

Without a connection to that tool, for a tool that does not send by template, or when the tool refuses (for example the test of a Resend template without a From or a subject), both routes return 400. The message of a refusal by the tool starts with its name.

Note

In the app, to defaults to the signed-in user’s address. There is no signed-in user behind an API key, so the API requires it and returns 400 without it.