Automações
Gatilho e fluxo no formato do construtor do painel: criar, ligar e trocar pela API.
Uma automação é um gatilho e um fluxo: quando uma conversa começa, quando o cliente escreve ou quando um contato ganha uma etiqueta, o fluxo passa por condições e faz ações. A API fala o mesmo formato que o construtor do painel grava, então a automação criada por aqui abre igual no painel, e a do painel volta igual por aqui.
O formato do fluxo
definition tem version: 1, os blocos (nodes) e as ligações (edges). Cada bloco tem um id seu, o type, o kind (trigger, condition ou action), a posição no canvas e um config de valores simples. Cada ligação vai de from para to; a saída NÃO de uma condição leva branch: "no", e numa pergunta cada opção é option-1, option-2…, com other para o resto.
{
"version": 1,
"nodes": [
{ "id": "t", "type": "new-conversation", "kind": "trigger",
"position": { "x": 0, "y": 0 }, "config": { "trigger": "NEW_CONVERSATION" } },
{ "id": "c", "type": "contact-tag", "kind": "condition",
"position": { "x": 300, "y": 0 }, "config": { "tagId": "tag_01K7ZFA5X8Q2M4N6P8R0T2V4W6" } },
{ "id": "a", "type": "assign-team", "kind": "action",
"position": { "x": 600, "y": 0 },
"config": { "action": "ASSIGN_TEAM", "target": "team_01K7ZFB2C4D6E8F0G2H4J6K8M0" } }
],
"edges": [
{ "id": "t-c", "from": "t", "to": "c" },
{ "id": "c-a", "from": "c", "to": "a" }
]
}
O gatilho da automação sai do config.trigger dos blocos de gatilho, e volta em trigger na resposta (new_conversation, por exemplo). Uma condição pode juntar critérios no mesmo bloco, em extraConditions, com match all ou any.
GET /v1/automations/{automation_id} devolve a automação com o fluxo inteiro. Partir de uma parecida evita errar o config de um bloco. A lista, GET /v1/automations, vem sem o fluxo, para caber mesmo numa conta com dezenas deles. A regra antiga, de um passo só, vem como o fluxo que o construtor monta ao abri-la.Ids dentro do fluxo
Onde o bloco aponta para etiqueta, time, campo, pessoa ou canal, o valor é o id da API (tag_…, team_…, cf_…, usr_…, chn_…, frm_…), o mesmo das outras rotas. A rota confere que cada um é desta conta e recusa no lugar exato: 404 tag_not_found com param: "definition.nodes.1.config.tagId". Quadro, etapa, entrada e integração ainda não têm id na API e vão com o id do painel.
O que a API recusa no fluxo
Por cima da validação do construtor, a rota recusa com 422 invalid_request e o lugar em param:
- Dois blocos, ou duas ligações, com o mesmo
id. - Texto de
configcom mais de 4096 caracteres, o limite da mensagem do WhatsApp. - Webhook que não é
httpsou que aponta para a rede interna (localhost,10.0.0.5,169.254.169.254). - Laço que não volta por uma opção de pergunta (
option-1…). Um laço com espera mandaria mensagem para sempre; voltando pela resposta, cada volta espera o contato. O construtor do painel aceita esse laço: a automação do painel que tem um continua mudando pela API nonamee noenabled, mas para trocar o fluxo dela tire o laço.
Os blocos
| type | config |
|---|---|
| Gatilhos (kind: trigger) | |
| new-conversation | { "trigger": "NEW_CONVERSATION" } |
| contact-message | { "trigger": "CONTACT_MESSAGE" } |
| kanban-stage | { "trigger": "KANBAN_STAGE_ENTERED", "boardId", "columnId" }Só nos quadros novos; etapa vazia vale para qualquer uma. |
| contact-tag-added | { "trigger": "CONTACT_TAG_ADDED", "tagId" } |
| contact-created-with-tag | { "trigger": "CONTACT_CREATED_WITH_TAG", "tagId" } |
| form-submitted | { "trigger": "FORM_SUBMITTED", "formId": "frm_…" }Com o plugin Formulários: roda pelo contato que respondeu. |
| Condições (kind: condition; saídas yes e no) | |
| channel | { "channel": "WHATSAPP" | "INSTAGRAM" | "WEBCHAT" | "MANUAL" } |
| contact-tag | { "tagId" } |
| assigned-to | { "membershipId" }Vazio: qualquer pessoa. |
| assigned-team | { "teamId" } |
| conversation-status | { "status": "OPEN" | "IN_PROGRESS" | "RESOLVED" } |
| business-hours | { "businessHoursMode": "inside" | "outside", "businessHoursStart": "09:00", "businessHoursEnd": "18:00", "businessHoursDays": "1,2,3,4,5" }Dias de 0 (domingo) a 6. |
| message-text | { "keywords": "preço, valor" } |
| entry-point | { "entryPointId" }Vazio: qualquer entrada. |
| kanban-card | { "boardId", "columnId" } |
| form-answer | { "questionKey", "operator": "ANY_OF", "value": "o4k2j9x1a,o7m3p0q2b" }Só na automação por formulário: compara a resposta que disparou o fluxo. questionKey é a key da pergunta; opções pelos ids, separados por vírgula; moeda em centavos; sim ou não como true e false. |
| Ações (kind: action) | |
| assign-team | { "action": "ASSIGN_TEAM", "target": "team_…" } |
| add-tag | { "action": "ADD_TAG", "target": "tag_…" } |
| set-status | { "action": "SET_STATUS", "target": "RESOLVED", "outcome": "SUCCESS" }outcome só ao resolver: SUCCESS ou ABANDONED. |
| set-field | { "action": "SET_CUSTOM_FIELD", "target": "cf_…", "customFieldValue" }Campo de contato. |
| wait | { "delayAmount": 5, "delayUnit": "minutes" | "hours" | "days" } |
| send-message | { "messageBody" }Na automação por etiqueta ou por formulário, também channelId (chn_…): o número que envia. |
| ask-question | { "messageBody", "replyOptions": "Sim\nNão", "timeoutHours": 24 }Saídas option-1 a option-10 e other. |
| webhook | { "webhookUrl", "webhookMethod": "POST" | "PUT" | "PATCH" } |
| integration | { "integrationId" } |
| place-card | { "boardId", "columnId" } |
| send-template | { "channelId": "chn_…", "templateSource": "META", "templateName", "templateLanguage": "pt_BR", "templateBody", "templateVariables": "[{\"index\":1,\"source\":\"CONTACT_FIRST_NAME\"}]" }Só na automação por etiqueta ou por formulário. META sai por número oficial; INTERNAL, por QR Code, com internalTemplateId. templateVariables e templateUrlButtons são JSON em texto, como no Disparo. A API ainda não lista os templates. |
| send-form | { "formId": "frm_…", "mode": "LINK" | "AMI", "message" }Só na automação por etiqueta ou por formulário, e só pelo WhatsApp. LINK manda o link pessoal depois de message; AMI deixa a Ami fazer as perguntas, no formulário que permite. |
Um fluxo que o construtor recusaria volta 422 com a mesma frase que o painel mostra, em português, e o caminho do campo em param.
Automação por etiqueta
Com o gatilho contact-tag-added ou contact-created-with-tag, a automação roda pelo contato, mesmo sem conversa aberta: é a sequência de boas-vindas ou de cobrança. Ela começa por um gatilho só, não aceita os blocos que dependem da conversa (canal, responsável, situação, texto da mensagem, entrada e pergunta) e ganha dois: send-template e o send-message com channelId, o número que envia. exitTagIds lista as etiquetas que tiram o contato da sequência.
O gatilho form-submitted, do plugin Formulários, faz a automação por formulário: ela roda pelo contato que respondeu, com as mesmas regras da por etiqueta, e só nela vale form-answer, que compara a resposta que disparou o fluxo. send-form manda um formulário nas duas.
Criar, ligar e trocar o fluxo
curl https://api.amivu.com.br/v1/automations \
-H "Authorization: Bearer $AMIVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Quem já agendou vai para a recepção",
"definition": {
"version": 1,
"nodes": [
{ "id": "t", "type": "new-conversation", "kind": "trigger",
"position": { "x": 0, "y": 0 }, "config": { "trigger": "NEW_CONVERSATION" } },
{ "id": "a", "type": "add-tag", "kind": "action",
"position": { "x": 300, "y": 0 },
"config": { "action": "ADD_TAG", "target": "tag_01K7ZFA5X8Q2M4N6P8R0T2V4W6" } }
],
"edges": [{ "id": "t-a", "from": "t", "to": "a" }]
}
}'
A automação nasce desligada, a menos que o corpo traga enabled: true: quem pediu pode revisar no painel antes de ela falar com cliente. PATCH /v1/automations/{automation_id} muda o nome, liga e desliga, ou troca o fluxo; definition substitui o fluxo inteiro, então mande o fluxo completo. DELETE apaga de vez; para pausar, prefira enabled: false.
automations:read), mas criar, mudar e apagar volta 403 live_key_required. Escrever pede automations:write.O que a API não faz
- Incluir quem já tem a etiqueta. Ao ligar uma automação por etiqueta, o painel oferece pôr na sequência os contatos que já a têm. Pela API, ela vale para quem ganhar a etiqueta dali em diante.
- Histórico de execuções. A resposta traz
last_executed_at; quantas vezes rodou e o detalhe de cada execução ficam no painel. - Automação pessoal. O que a chave cria é da organização. As pessoais aparecem na lista com
owner_user_id.
Veja também A Ami e Servidor MCP, que monta fluxos conversando.
Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.