Disparando workflows a partir de um botão de chat, de ponta a ponta

Um botão de disparo de workflow parece simples — clica, o workflow roda — mas a regra de elegibilidade, o contrato do payload e o namespace de variáveis que o workflow lê são específicos o suficiente para que errar um detalhe (um workflow que não é api_trigger, um payload em array em vez de objeto) falhe de forma explícita em vez de silenciosa. Este é o contrato completo.

Elegibilidade: apenas workflows api_trigger

Um workflow do Dailybot tem um tipo de evento — agenda, envio de formulário, conclusão de check-in, ou api_trigger (“When triggered via API or button”). Apenas workflows api_trigger podem ser disparados de fora — via CLI, o endpoint REST, ou o callback_workflow de um botão de chat. Qualquer outro caso retorna 400 workflow_not_triggerable.

Workflows são criados e editados exclusivamente no aplicativo web do Dailybot — não há caminho de CLI para criar ou alterar um. Uma vez que um workflow api_trigger exista, resolva seu UUID:

dailybot workflow list --filter api_trigger --json

--filter api_trigger é uma conveniência do lado do cliente sobre o workflow list padrão — retorna apenas os workflows que você pode disparar legitimamente. Inspecione a configuração de um deles com:

dailybot workflow get <workflow_uuid> --json

Trate o JSON retornado como a fonte da verdade sobre o que o workflow realmente faz — não adivinhe pelo nome dele.

Disparando diretamente (CLI / API)

# Fire it, no payload
dailybot workflow trigger <workflow_uuid> --json

# Fire it with a JSON payload the workflow can read
dailybot workflow trigger <workflow_uuid> \
  --payload '{"version": "v2.5", "environment": "production"}' --json

Equivalente em HTTP:

curl -s -X POST \
  -H "Authorization: Bearer $DAILYBOT_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"version": "v2.5"}}' \
  https://api.dailybot.com/v1/workflows/<workflow_uuid>/trigger/

Um disparo bem-sucedido retorna HTTP 202 — a execução fica enfileirada, não é síncrona, e a resposta não carrega nenhuma saída da execução; o workflow roda no servidor de forma assíncrona. --payload (ou o payload do corpo do request) precisa ser um objeto JSON — não um array, não um escalar — e é limitado a 8 KiB; qualquer coisa maior ou malformada retorna 400 workflow_trigger_payload_invalid. Um workflow congelado (desativado) retorna 403 workflow_frozen; um chamador sem permissão de execução recebe 403 workflow_execute_not_allowed; um UUID desconhecido retorna 404.

Confirme antes de disparar. workflow trigger tem efeitos colaterais — pode iniciar um deploy ou qualquer outra automação. Repita o workflow-alvo (nome + UUID) e o payload (ou “sem payload”) e aguarde um sim explícito antes de disparar a partir de um contexto de agente.

Disparando a partir de um botão de chat

O mesmo disparo do lado do servidor acontece quando o callback_workflow do botão de uma mensagem é clicado:

curl -sS -X POST 'https://api.dailybot.com/v1/send-message/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Ready to redeploy staging?",
    "target_channels": ["C0123456789"],
    "buttons": [
      {"label": "Redeploy staging", "button_type": "interactive", "value": "redeploy_staging",
       "callback_workflow": "$REDEPLOY_WORKFLOW_UUID"}
    ]
  }'

Atalho de CLI:

dailybot chat send -c C0123456789 -m "Ready to redeploy staging?" \
  --workflow-button "Redeploy staging=$REDEPLOY_WORKFLOW_UUID"

callback_workflow aceita apenas o UUID do workflow — nomes e slugs são rejeitados. UUIDs desconhecidos, inativos ou de outra organização retornam 400 button_callback_workflow_not_found. Nenhuma chamada HTTP externa acontece e nenhum segredo de assinatura está envolvido: o disparo é inteiramente interno ao Dailybot, atribuído ao usuário que clicou.

Disparado por botão vs. disparado por API — mesmo mecanismo, uma variável os diferencia

Ambos os caminhos passam pelo mecanismo de disparo idêntico do lado do servidor. A única diferença visível para os próprios passos do workflow é {{trigger.source}}, que resolve para "api", "button_click" ou "modal_submit" — assim, um workflow pode ramificar seu comportamento (por exemplo, pular um passo de confirmação quando disparado por um clique de botão já confirmado, mas perguntar novamente quando disparado diretamente via API).

Lendo o contexto do clique dentro do workflow

Os passos do workflow disparado referenciam o contexto do disparo através do namespace {{trigger.*}}:

Variável	Valor
{{trigger.source}}	"api" | "button_click" | "modal_submit"
{{trigger.button_value}}	O value do botão clicado
{{trigger.button_id}}	O $btn/<uuid4> gerado pelo servidor
{{trigger.fields.<name>}}	O valor enviado de um input do modal_body, se o botão abriu um modal antes
{{trigger.clicked_at}}	Timestamp do clique
{{trigger.body.*}}	O objeto bruto de --payload, quando disparado diretamente via API/CLI
{{trigger.user.*}}	uuid, full_name, first_name, email, role do usuário que clicou/disparou
{{trigger.triggered_by_user_uuid}}	Atalho para o UUID do usuário que disparou

Um workflow, vários botões

Em vez de criar workflows quase duplicados para variar um rótulo, aponte vários botões para o mesmo UUID de callback_workflow com values diferentes, e ramifique dentro do workflow com base em {{trigger.button_value}}:

{"message": "Choose a rollback target",
 "target_channels": ["C0123456789"],
 "buttons": [
   {"label": "Rollback to v2.3", "button_type": "interactive", "value": "v2.3", "callback_workflow": "$ROLLBACK_WORKFLOW_UUID"},
   {"label": "Rollback to v2.2", "button_type": "interactive", "value": "v2.2", "callback_workflow": "$ROLLBACK_WORKFLOW_UUID"}
 ]}

Modal → workflow: coletando input antes do disparo

modal_body se combina com callback_workflow — o clique abre o modal, e no envio os valores dos campos são entregues como {{trigger.fields.<input.name>}}, sem nenhum servidor externo envolvido:

{"label": "Report", "button_type": "interactive", "value": "report",
 "callback_workflow": "$INCIDENT_WORKFLOW_UUID",
 "modal_body": {
   "title": "New incident",
   "blocks": [
     {"type": "input", "name": "summary", "label": "What happened?", "multiline": true, "required": true}
   ]
 }}

O workflow pode usar {{trigger.fields.summary}} em qualquer passo — pré-preencher a resposta de um formulário, compor uma mensagem de acompanhamento, ou alimentar um prompt de IA.

Referência de erros

Erro	Quando
400 workflow_not_triggerable	O tipo de evento do workflow não é api_trigger
400 workflow_trigger_payload_invalid	O payload não é um objeto JSON, ou excede 8 KiB
400 button_callback_workflow_not_found	callback_workflow não resolve a um workflow ativo na organização do chamador
403 workflow_execute_not_allowed	O chamador não tem permissão para executar workflows
403 workflow_frozen	O workflow está desativado
403 plan_upgrade_required	Workflows não estão no plano da organização
404	UUID de workflow desconhecido

Referências cruzadas

• A API send-message, de ponta a ponta para o contrato completo de botões dentro do qual callback_workflow vive.
• /pt/developers/api/workflows para a referência completa de {{trigger.*}}.
• /pt/developers/cli para as flags de workflow list / get / trigger.

Navegue pelo hub de Soluções para o passeio voltado ao produto sobre disparar automações direto do chat.