Automations
Answer messages on a number, DMs and comments on Instagram and Facebook Pages, comments on TikTok.
Automations answer for the business. Create them on your own numbers and channels and on the ones your customers connect, with the same key. They are the same automations the dashboard editor and the AI assistant make, with the same fields and the same checks, so one made here opens in the editor and the other way around.
A number's automations run only while it is managed: see Set the inbound mode. Numbers connected through a session without a webhook_url start managed. Instagram, Facebook and TikTok channels always reach us: nothing to switch.
Create one on a number
POST/api/v1/connections/{id}/automations
One trigger and a flow of steps, with branches. Answers 201 with the automation. number_is_managed: false on the answer means it will not run until the number is managed.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
namerequired | body | string | |
triggerrequired | body | object | type and match, below. Comments can be limited to one post with post_id. |
stepsrequired | body | array | A flow, top to bottom, with branches: below. Up to 60 steps in all. |
settings | body | object | takeover_hours (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and ai_max_per_hour (default 10 per chat). |
enabled | body | boolean | Default true. |
Request
{
"name": "After hours",
"trigger": {
"type": "message_received",
"match": "outside_hours",
"hours": {
"timezone": "America/Sao_Paulo",
"days": [
1,
2,
3,
4,
5
],
"start": "09:00",
"end": "18:00"
}
},
"steps": [
{
"type": "reply_text",
"text": "Hi {{first_name}}, we are closed now and answer from 9:00. Leave your message here."
}
]
}Response 201
{
"id": "4d2a…",
"name": "Comment PRICE, get the list on WhatsApp",
"connection_id": "6f1c…",
"channel_id": null,
"phone": "+55 11 9…",
"number_is_managed": true,
"enabled": true,
"status": "active",
"broken_reason": null,
"trigger": {
"type": "comment_received",
"match": "keyword",
"keywords": [
"price"
],
"keyword_mode": "contains"
},
"steps": [
{
"type": "reply_comment",
"text": "Sent you a DM!"
},
{
"type": "ask_whatsapp",
"connection_id": "6f1c…",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
},
{
"type": "send_template",
"name": "price_list",
"language": "en"
}
],
"settings": {
"takeover_hours": 4,
"ai_max_per_hour": 10
},
"last_run_at": null,
"created_at": "…",
"updated_at": "…"
}trigger.type:message_receivedon a number;dm_receivedorcomment_receivedon Instagram and Facebook;comment_receivedon TikTok. Not started by a message:tag_addedwithtag(numbers, Instagram, Facebook: each time a contact gets the tag) andwebhook_received(numbers: your system POSTs{ "to": "+phone", ... }to the automation'swebhook_urlwith its secret as a Bearer token; the body is{{vars.webhook.*}}).trigger.match:any,keyword(keywords,keyword_modecontains|starts_with|exact),first_message,outside_hours(hours:{ timezone, days: [1..7], start: "09:00", end: "18:00" }, when open), orphone_number(Instagram and Facebook: the text has a phone number in it). One automation answers each message:phone_numberfirst, thenkeyword,first_message,outside_hours,any.- Steps:
reply_text{ text },send_file{ file_id, caption? } (a picture or PDF from the account's files, which are uploaded in the dashboard; inside the 24-hour window),ai_reply{ provider: anthropic | openai | openrouter, model, prompt, history?, max_tokens? },agent{ agent_id, wait_seconds? } (one of your AI agents answers, with its knowledge and tools),ask{ text, buttons?, save_to, expect: text | email | number | phone | choice, retry_text?, wait_minutes? } (asks and waits; the answer is saved in a contact field),send_template{ name, language, params? },call_webhook{ url } (your system decides; answer{ "reply": "..." }to send it),http_request{ method, url, headers?, body?, save_as? } (any API; its answer becomes{{vars.<save_as>...}}),set_field{ key, value },tag{ action: add | remove, tag },ai_extract{ provider, model, fields: [{ key, description }] },start_automation{ automation_id },handoff{ hours?, note? } (pauses the bot on the chat and emails you),notify_owner{ text } (an email to you),wait{ minutes },stop. Comments addreply_comment{ text } andhide_comment. Instagram and Facebook addask_whatsapp{ connection_id, text, confirm_text }. - Branches:
condition{ paths: [{ name, match: all | any, rules: [{ source: message | field | tag | var | hours, key?, op, value?, hours? }], steps }], otherwise } runs the first path whose rules hold;ai_decide{ provider, model, instructions?, paths: [{ name, description, steps }], otherwise } lets your model pick by meaning. After the path, the flow goes on below the branching step. - Loops: any step may carry an
id;goto{ to } jumps to it, as the last step of its line. A loop must pass anaskor await, and a run takes at most 20 jumps. - Text takes
{{name}},{{first_name}},{{message}},{{phone}}(numbers),{{contact.<field>}},{{vars.<path>}}(what earlier steps saved), and afterask_whatsapp,{{whatsapp}}, the number they gave. ai_replyuses your own key for that provider, saved in the dashboard (Automations, AI keys); keys never go through the API. AI keys lists which providers have one.
Errors besides the common ones: not_found, invalid_request, billing_required.
Create one on a channel
POST/api/v1/channels/{id}/automations
The same fields on an Instagram account, a Facebook Page or a TikTok account. This one answers an Instagram comment that says "price", asks the person for their WhatsApp number in a DM, and sends an approved template there from one of your numbers:
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The channel's id. |
namerequired | body | string | |
triggerrequired | body | object | type and match, below. Comments can be limited to one post with post_id. |
stepsrequired | body | array | A flow, top to bottom, with branches: below. Up to 60 steps in all. |
settings | body | object | takeover_hours (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and ai_max_per_hour (default 10 per chat). |
enabled | body | boolean | Default true. |
Request
curl -X POST https://easycoexistence.com/api/v1/channels/<channel_id>/automations \
-H "Authorization: Bearer ec_live_..." -H "Content-Type: application/json" \
-d '{
"name": "Comment PRICE, get the list on WhatsApp",
"trigger": { "type": "comment_received", "match": "keyword", "keywords": ["price"] },
"steps": [
{ "type": "reply_comment", "text": "Sent you a DM!" },
{ "type": "ask_whatsapp", "connection_id": "<connection_id>",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no." },
{ "type": "send_template", "name": "price_list", "language": "en" }
]
}'Response 201
{
"id": "4d2a…",
"name": "Comment PRICE, get the list on WhatsApp",
"connection_id": null,
"channel_id": "9a41…",
"enabled": true,
"status": "active",
"broken_reason": null,
"trigger": {
"type": "comment_received",
"match": "keyword",
"keywords": [
"price"
],
"keyword_mode": "contains"
},
"steps": [
{
"type": "reply_comment",
"text": "Sent you a DM!"
},
{
"type": "ask_whatsapp",
"connection_id": "6f1c…",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
},
{
"type": "send_template",
"name": "price_list",
"language": "en"
}
],
"settings": {
"takeover_hours": 4,
"ai_max_per_hour": 10
},
"last_run_at": null,
"created_at": "…",
"updated_at": "…"
}Rules the API holds you to, checked before anything is saved (400 invalid_request names the field):
- Free text only goes out within 24 hours of the person's last message; after that, a template.
- A comment gets one private reply (Meta's rule), so a comment automation sends one DM until the person answers. TikTok has no DMs: every answer is public, up to 150 characters.
ask_whatsapp:textmust say WhatsApp and name the business with{{business}};confirm_text(asked when their message already has a number) also shows it with{{whatsapp}}. Their number in an answer, or a yes, is their consent, and it is recorded. The step fails while the writing number cannot reach new people (banned, disconnected, suspended, blocked, limited or at red quality).send_templateon Instagram and Facebook goes to the numberask_whatsappcollected, so it comes after it; one first message per person per number every 7 days.
Errors besides the common ones: not_found, invalid_request, channel_unavailable, billing_required.
List automations
GET/api/v1/automations
Every automation on the account.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
external_ref | query | string | Partners: keeps the ones a customer connected, by the external_ref of their connect session. |
Response 200
{
"data": [
{
"id": "4d2a…",
"name": "Comment PRICE, get the list on WhatsApp",
"connection_id": null,
"channel_id": "9a41…",
"enabled": true,
"status": "active",
"broken_reason": null,
"trigger": {
"type": "comment_received",
"match": "keyword",
"keywords": [
"price"
],
"keyword_mode": "contains"
},
"steps": [
{
"type": "reply_comment",
"text": "Sent you a DM!"
},
{
"type": "ask_whatsapp",
"connection_id": "6f1c…",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
},
{
"type": "send_template",
"name": "price_list",
"language": "en"
}
],
"settings": {
"takeover_hours": 4,
"ai_max_per_hour": 10
},
"last_run_at": null,
"created_at": "…",
"updated_at": "…"
}
]
}List a number's automations
GET/api/v1/connections/{id}/automations
The same list, for one number.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
Errors besides the common ones: not_found.
List a channel's automations
GET/api/v1/channels/{id}/automations
The same list, for one channel.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The channel's id. |
Errors besides the common ones: not_found.
Get an automation
GET/api/v1/automations/{id}
One automation, as created.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
Response 200
{
"id": "4d2a…",
"name": "Comment PRICE, get the list on WhatsApp",
"connection_id": null,
"channel_id": "9a41…",
"enabled": true,
"status": "active",
"broken_reason": null,
"trigger": {
"type": "comment_received",
"match": "keyword",
"keywords": [
"price"
],
"keyword_mode": "contains"
},
"steps": [
{
"type": "reply_comment",
"text": "Sent you a DM!"
},
{
"type": "ask_whatsapp",
"connection_id": "6f1c…",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
},
{
"type": "send_template",
"name": "price_list",
"language": "en"
}
],
"settings": {
"takeover_hours": 4,
"ai_max_per_hour": 10
},
"last_run_at": null,
"created_at": "…",
"updated_at": "…"
}Errors besides the common ones: not_found.
Change an automation
PATCH/api/v1/automations/{id}
Fields left out keep their value; trigger, steps and settings replace the old ones whole. { "enabled": false } switches it off.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
name | body | string | |
trigger | body | object | type and match, below. Comments can be limited to one post with post_id. |
steps | body | array | A flow, top to bottom, with branches: below. Up to 60 steps in all. |
settings | body | object | takeover_hours (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and ai_max_per_hour (default 10 per chat). |
enabled | body | boolean | Default true. |
connection_id | body | uuid | Moves it to this number. |
channel_id | body | uuid | Moves it to this channel. Not with connection_id. |
Request
{
"enabled": false
}Response 200
{
"id": "4d2a…",
"name": "Comment PRICE, get the list on WhatsApp",
"connection_id": null,
"channel_id": "9a41…",
"enabled": false,
"status": "active",
"broken_reason": null,
"trigger": {
"type": "comment_received",
"match": "keyword",
"keywords": [
"price"
],
"keyword_mode": "contains"
},
"steps": [
{
"type": "reply_comment",
"text": "Sent you a DM!"
},
{
"type": "ask_whatsapp",
"connection_id": "6f1c…",
"text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
"confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
},
{
"type": "send_template",
"name": "price_list",
"language": "en"
}
],
"settings": {
"takeover_hours": 4,
"ai_max_per_hour": 10
},
"last_run_at": null,
"created_at": "…",
"updated_at": "…"
}Errors besides the common ones: not_found, invalid_request, billing_required.
Delete an automation
DELETE/api/v1/automations/{id}
Deletes it with its runs and the consents it collected.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
Response 200
{
"deleted": true
}Errors besides the common ones: not_found.
Test an automation
POST/api/v1/automations/{id}/test
Runs the steps on a sample message without sending anything. The AI step and your webhook really run, so you see the actual reply. 60 tests an hour.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
textrequired | body | string | The sample message. |
Request
{
"text": "how much?"
}Response 200
{
"id": "7c0e…",
"automation_id": "4d2a…",
"status": "done",
"skip_reason": null,
"test": true,
"trigger": {
"type": "comment_received",
"from": "mariasilva",
"text": "price?"
},
"steps": [
{
"step": 0,
"type": "reply_comment",
"status": "ok",
"output": "Sent you a DM!",
"ms": 412
},
{
"step": 1,
"type": "ask_whatsapp",
"status": "ok",
"output": "Hi Maria! What is your WhatsApp number? Bloom Café will send the price list there.",
"ms": 51
}
],
"tokens_in": 0,
"tokens_out": 0,
"error": null,
"awaiting": null,
"whatsapp": null,
"resume_at": null,
"created_at": "…",
"finished_at": "…"
}Errors besides the common ones: not_found, rate_limited.
List runs
GET/api/v1/automations/{id}/runs
What the automation did on each message, newest first, kept 30 days. Each step has status ok, failed or skipped, its output or error, and ms.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
status | query | queued | running | waiting | done | failed | skipped | waiting is a run paused on an ask_whatsapp question. |
limit | query | number | Default 50. |
Response 200
{
"data": [
{
"id": "7c0e…",
"automation_id": "4d2a…",
"status": "failed",
"skip_reason": null,
"test": false,
"trigger": {
"type": "comment_received",
"from": "mariasilva",
"text": "price?"
},
"steps": [
{
"step": 0,
"type": "reply_comment",
"status": "ok",
"output": "Sent you a DM!",
"ms": 412
},
{
"step": 1,
"type": "ask_whatsapp",
"status": "failed",
"error": "The number cannot start conversations (BLOCKED).",
"ms": 88
}
],
"tokens_in": 0,
"tokens_out": 0,
"error": "The number cannot start conversations (BLOCKED).",
"awaiting": null,
"whatsapp": null,
"resume_at": null,
"created_at": "…",
"finished_at": "…"
}
]
}skip_reason says why one did not answer: human_active (the business answered from the phone app), window_closed, ai_limit, no_reply, declined, superseded.
Errors besides the common ones: not_found.
Get a run
GET/api/v1/automations/{id}/runs/{run_id}
One run with every step's output and error.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The automation's id. |
run_idrequired | path | uuid | The run's id. |
Response 200
{
"id": "7c0e…",
"automation_id": "4d2a…",
"status": "failed",
"skip_reason": null,
"test": false,
"trigger": {
"type": "comment_received",
"from": "mariasilva",
"text": "price?"
},
"steps": [
{
"step": 0,
"type": "reply_comment",
"status": "ok",
"output": "Sent you a DM!",
"ms": 412
},
{
"step": 1,
"type": "ask_whatsapp",
"status": "failed",
"error": "The number cannot start conversations (BLOCKED).",
"ms": 88
}
],
"tokens_in": 0,
"tokens_out": 0,
"error": "The number cannot start conversations (BLOCKED).",
"awaiting": null,
"whatsapp": null,
"resume_at": null,
"created_at": "…",
"finished_at": "…"
}Errors besides the common ones: not_found.
AI keys
GET/api/v1/ai-keys
Which providers have a key saved in the dashboard and whether it last worked. Status only: a key is never written or read through the API.
Response 200
{
"data": [
{
"provider": "anthropic",
"status": "ok",
"last_error": null,
"checked_at": "…"
},
{
"provider": "openai",
"status": "failed",
"last_error": "401 invalid_api_key",
"checked_at": "…"
}
]
}Only providers with a saved key are listed. status is ok or failed, from the last time the key was used.