Crie, edite e publique automações

Este passo a passo cria um rascunho que envia um link quando um contato comenta uma palavra-chave. Todos os IDs, horários, textos e URLs abaixo são ilustrativos. Substitua o ID da conta por um retornado em Listar contas. Use uma chave de API com os escopos necessários.

1. Crie um rascunho

Envie este corpo para POST /api/v1/automations com Authorization: Bearer <API_KEY> e Content-Type: application/json. A criação exige automations:write. O nome permite de 1 a 120 valores escalares Unicode, sem espaços nas extremidades ou caracteres de controle.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "name": "Guide request",
  "status": "draft",
  "configuration": {
    "contact_filter": "anyone",
    "trigger": {
      "type": "comment",
      "publication": {
        "mode": "all"
      },
      "keywords": {
        "mode": "specific",
        "match_mode": "whole_word",
        "values": [
          "guide"
        ]
      }
    },
    "opening": {
      "public_reply": {
        "enabled": false
      },
      "direct_message": {
        "delay_seconds": 0,
        "message": {
          "text": "Here is the guide you asked for.",
          "buttons": [
            {
              "type": "url",
              "title": "Open the guide",
              "url": "https://example.com/guide"
            }
          ]
        }
      }
    },
    "follow_up": null,
    "extras": {
      "cooldown": {
        "mode": "none"
      }
    }
  }
}

Resposta: HTTP 201

{
  "automation": {
    "id": "00000000-0000-4000-8000-000000000002",
    "account_id": "00000000-0000-4000-8000-000000000001",
    "name": "Guide request",
    "status": "draft",
    "has_unpublished_changes": false,
    "draft_updated_at": null,
    "created_at": "2026-09-01T12:00:00.000000Z",
    "updated_at": "2026-09-01T12:00:00.000000Z",
    "trigger_type": "comment",
    "configuration": {
      "contact_filter": "anyone",
      "trigger": {
        "type": "comment",
        "publication": {
          "mode": "all"
        },
        "keywords": {
          "mode": "specific",
          "match_mode": "whole_word",
          "values": [
            "guide"
          ]
        }
      },
      "opening": {
        "public_reply": {
          "enabled": false
        },
        "direct_message": {
          "delay_seconds": 0,
          "message": {
            "text": "Here is the guide you asked for.",
            "buttons": [
              {
                "type": "url",
                "title": "Open the guide",
                "url": "https://example.com/guide"
              }
            ]
          }
        }
      },
      "follow_up": null,
      "extras": {
        "cooldown": {
          "mode": "none"
        }
      }
    },
    "authoring_compatibility": "public_v1"
  }
}

O envelope é automation, não data. Uma escrita bem-sucedida salva a automação; não comprova que uma mensagem foi enviada. Guarde id e a string exata de updated_at. Não arredonde nem reformate os horários.

2. Consulte antes de editar

Chame GET /api/v1/automations/{automationId}?account_id=... com automations:read. O HTTP 200 retorna o mesmo envelope completo mostrado acima. Sempre comece uma edição com uma consulta atualizada.

3. Renomeie ou substitua a configuração

Para renomear, envie este corpo para PATCH /api/v1/automations/{automationId}. Substitua o horário do exemplo pelo valor da consulta atualizada.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z",
  "name": "Updated guide request"
}

Para mudar o comportamento, envie também o objeto configuration completo e modificado. Ele substitui a configuração salva; objetos e arrays internos não são mesclados. Você pode enviar o nome, a configuração ou ambos, mas não status. O HTTP 200 retorna o envelope completo de automation, incluindo o novo updated_at. Em uma automação ativa, consulte has_unpublished_changes. Quando verdadeiro, o nome e a configuração retornados descrevem o rascunho, enquanto a versão publicada anteriormente continua executando. draft_updated_at é informativo; o controle de concorrência sempre usa updated_at.

4. Publique ou pause

Após revisar o rascunho salvo, envie o corpo abaixo para POST /api/v1/automations/{automationId}/activate. Use a versão mais recente de uma nova consulta. A ativação exige automations:activate.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z"
}

O HTTP 200 retorna o envelope completo com status: "live" e a configuração publicada. Para pausar o processamento de novos triggers, envie o mesmo formato de corpo com uma versão atualizada para POST /api/v1/automations/{automationId}/deactivate; o HTTP 200 retorna status: "paused". Criar com status: "live" publica imediatamente e também exige o escopo de ativação.

Recupere sem duplicar escritas

409 com api_automation_version_conflict: consulte novamente, concilie as alterações mais recentes e reconstrua a edição.
422 com api_automation_invalid_configuration: consulte error.details.issues e corrija os caminhos indicados.
api_automation_committed_response_unavailable com committed: true e retryable: false: a escrita foi aplicada. Consulte a automação, ou a lista após criar, antes de decidir o próximo passo.
Um resultado incerto de criação não deve ser repetido às cegas: a criação não é idempotente.

Exemplo de resposta de conflito

HTTP 409.

{
  "error": {
    "code": "api_automation_version_conflict",
    "message": "The automation changed after the supplied version."
  }
}

Use o guia de erros para o envelope de resposta, IDs de correlação, falhas de autenticação e decisões de nova tentativa. Excluir arquiva a automação e retorna HTTP 204 sem corpo; não tente interpretá-lo como JSON.

Visão geral

Primeiros passos

Guias

Webhooks

Crie, edite e publique automações

1. Crie um rascunho

Resposta: HTTP 201

2. Consulte antes de editar

3. Renomeie ou substitua a configuração

4. Publique ou pause

Recupere sem duplicar escritas

Exemplo de resposta de conflito

​1. Crie um rascunho

​Resposta: HTTP 201

​2. Consulte antes de editar

​3. Renomeie ou substitua a configuração

​4. Publique ou pause

​Recupere sem duplicar escritas

​Exemplo de resposta de conflito

1. Crie um rascunho

Resposta: HTTP 201

2. Consulte antes de editar

3. Renomeie ou substitua a configuração

4. Publique ou pause

Recupere sem duplicar escritas

Exemplo de resposta de conflito