Mensageria

A API pública do Dailybot expõe endpoints de mensageria para entregar mensagens do bot, emails e conversas privadas no Slack, Microsoft Teams, Discord e Google Chat. Esta página inclui as tabelas de campos estruturadas de POST /v1/send-message/, POST /v1/send-email/ e POST /v1/open-conversation/ (incluindo o contrato completo de Button / modal_body / response / callback_auth), além da substituição de identidade send_as_user e o guia detalhado de botões interativos.

Construtor de botões

Abaixo da referência de send-message, um Construtor de botões interativo permite compor botões visualmente — de link, simples, aprovar/rejeitar, gatilho de workflow, formulário, comando, prompt e modal — e copiar o array buttons JSON exato, o comando dailybot chat send equivalente (usando --link-button, --button, --approve-button/--reject-button com --callback-url/--callback-bearer, ou --workflow-button, recorrendo a --buttons '<json>' para o que esses flags não conseguem expressar), ou um body de curl pronto para executar contra POST /v1/send-message/.

Substituição de identidade send_as_user (apenas Slack)

send_as_user permite que um chamador autorizado publique uma mensagem que parece vir de outro usuário — a mensagem exibe o nome de exibição e o avatar do Slack desse usuário em vez da identidade do bot. É útil para workflows automatizados que precisam apresentar mensagens na perspectiva de um membro específico da equipe.

Requisitos:

• O chamador deve ser administrador da organização ou ter uma chave de propriedade de um administrador.
• O usuário alvo (UUID de send_as_user) deve estar ativo e na mesma organização.
• Aplica-se apenas no Slack — outras plataformas ignoram o campo e voltam à identidade padrão do bot.
• send_as_user é mutuamente exclusivo com bot_username, bot_icon_url e bot_icon_emoji. Combiná-los retorna 400 com code: "send_as_user_conflict".

Quando send_as_user está definido, o Dailybot busca a identidade do Slack conectada do usuário e a usa como autora da mensagem. A mensagem ainda é enviada pelo token do bot do Dailybot — não usa o token do Slack do usuário.

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "The sprint is closed and all tickets are resolved.",
    "target_channels": ["C0123456789"],
    "send_as_user": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Códigos de erro para send_as_user:

Botões interativos

Cada mensagem pode carregar até 25 botões renderizados como elementos interativos nativos no Slack, Microsoft Teams, Discord e Google Chat. Dois valores de button_type são suportados:

• link — ao clicar abre a url no navegador do usuário.
• interactive — ao clicar aciona uma das quatro capacidades descritas abaixo.

Campos do botão

Todo botão interativo do lado do servidor carrega um button_id = "$btn/<uuid4>" gerado pelo servidor que é ecoado em todo corpo de callback para o chamador identificar cada clique de forma única. Valores de button_id fornecidos pelo cliente são silenciosamente sobrescritos.

Nota de compatibilidade: payload.callback_config e campos value de ações de integrações antigas ainda funcionam e são aditivos — prefira os campos de nível superior acima para novas integrações.

Matriz de compatibilidade

✔ = permitidos juntos, ✖ = rejeitado. Os cinco callbacks são mutuamente exclusivos entre si (button_callback_conflict).

Um modal com blocos input requer callback_url OU callback_workflow (400 button_modal_body_invalid, detail input_without_callback).

label_after_click e destroy_button compõem com tudo (incluindo response): destroy_button: false mantém o botão clicável — cada clique é um novo despacho com um id X-Dailybot-Delivery novo; em botões modais a troca de label_after_click ocorre no ENVIO do modal, não na abertura, então um modal cancelado deixa o botão clicável. Um botão interativo simples pode carregar response sem nenhum callback (o caso “Skip”).

URLs de callback interativas

Um botão interactive com callback_url recebe um HTTP POST do Dailybot quando o usuário clica. É a forma canônica para fluxos de aprovação, feedback e triagem leve construídos sobre /v1/send-message/.

Exemplo de requisição:

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Juan wants to buy a coffee. Approve?",
    "target_users": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "buttons": [
      { "label": "Yes", "button_type": "interactive", "value": "approve",
        "callback_url": "https://approvals.acme.example/v1/decisions/req_9812" },
      { "label": "No",  "button_type": "interactive", "value": "deny",
        "callback_url": "https://approvals.acme.example/v1/decisions/req_9812" }
    ]
  }'

Corpo do POST de callback — o Dailybot dispara isto quando o usuário clica:

POST https://approvals.acme.example/v1/decisions/req_9812
Content-Type: application/json
User-Agent: Dailybot-Chatbot/1.0
X-Dailybot-Event: button_click
X-Dailybot-Delivery: 5e2d…-uuid
X-Dailybot-Timestamp: 1782001872
X-Dailybot-Signature: t=1782001872, v1=6d9a3e…hex_hmac

{
  "event": "button_click",
  "bot_message_id": "$db/ae007b43-dde2-4fa9-bce3-71fb0975a249",
  "button":       { "id": "$btn/…", "value": "approve" },
  "user":         { "id": "…", "email": "…", "display_name": "…", "external_id": "U01ABCDEFG" },
  "organization": { "id": "…", "name": "…" },
  "platform":     "slack",
  "channel":      { "id": "D0123456", "type": "im" },
  "modal_fields": null,
  "metadata":     { "campaign": "coffee-approvals" },
  "sent_at":      "2026-07-22T14:30:00Z",
  "clicked_at":   "2026-07-22T14:31:12Z"
}

Valores de platform. Um de slack, msteams, discord ou hangouts. O Google Chat é entregue como hangouts (o identificador histórico de plataforma) — corresponda a esse valor, não a “gchat” ou “googlechat”. sent_at é marcado quando a mensagem da plataforma foi realmente entregue; clicked_at quando o usuário clicou. metadata retorna verbatim da sua chamada original a /v1/send-message/.

Verificação de assinatura. Todo POST carrega uma assinatura HMAC-SHA256 calculada com o segredo de assinatura de callback da sua organização sobre a string ASCII "{unix_timestamp}.{raw_body}".

Node.js:

const crypto = require('crypto');
function verify(rawBody, sigHeader, secretB64) {
  const secret = Buffer.from(secretB64, 'base64url');
  const parts = Object.fromEntries(sigHeader.split(',').map(s => s.trim().split('=')));
  const ts = parseInt(parts.t, 10);
  if (Math.abs(Date.now()/1000 - ts) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v1, 'hex'));
}

Python:

import hmac, hashlib, base64, time
def verify(raw_body: bytes, sig_header: str, secret_b64: str) -> bool:
    secret = base64.urlsafe_b64decode(secret_b64 + '==')
    parts = dict(p.strip().split('=', 1) for p in sig_header.split(','))
    ts = int(parts['t'])
    if abs(time.time() - ts) > 300:  # 5 min replay window
        return False
    expected = hmac.new(secret, f"{ts}.{raw_body.decode()}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts['v1'])

Idempotência. X-Dailybot-Delivery é único por tentativa de clique. Se o POST de saída do Dailybot for reenviado, o mesmo id de entrega é enviado — use-o como chave de deduplicação.

Reenvios. O Dailybot reenvia uma vez com backoff de 500 ms em erros 5xx / 429 / de rede. 2xx bem-sucedido completa o fanout; qualquer outro 4xx é tratado como terminal e descartado.

Botões modais

Adicione um objeto modal_body a um botão interactive para abrir um modal leve no clique. No envio, os valores de entrada do modal são publicados em callback_url junto com event: "modal_submit" e o value do botão clicado.

Esquema de modal_body:

Os tipos de bloco suportados são exatamente text, input e divider. O modal_body serializado deve ser ≤ 8 KiB. Valores name de entrada devem corresponder a ^[a-z][a-z0-9_]{0,62}$ e ser únicos dentro do modal.

{
  "title": "string, ≤ 200 chars, required",
  "submit_label": "string, ≤ 200 chars, default 'Submit'",
  "blocks": [
    // 1..10 blocks; supported block types:
    { "type": "text", "text": "≤ 3000 chars" },
    {
      "type": "input",
      "name": "snake_case_identifier",   // required, unique per modal; regex ^[a-z][a-z0-9_]{0,62}$
      "label": "Field label, ≤ 200",     // required
      "multiline": true,                  // optional, default false
      "required": true,                   // optional, default false
      "max_length": 1000,                 // optional, ≤ 3000
      "placeholder": "≤ 200",             // optional
      "default": "prefilled value"        // optional
    },
    { "type": "divider" }
  ]
}

Exemplo de requisição (aprovar com comentário):

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Sprint retro — how did it feel?",
    "target_teams": ["team_engineering_uuid"],
    "buttons": [
      { "label": "🚀 Great",   "button_type": "interactive", "value": "great",
        "callback_url": "https://retros.acme.example/v1/sprint-42" },
      { "label": "😐 Fine",    "button_type": "interactive", "value": "fine",
        "callback_url": "https://retros.acme.example/v1/sprint-42" },
      {
        "label": "📝 Add feedback",
        "button_type": "interactive",
        "value": "feedback",
        "callback_url": "https://retros.acme.example/v1/sprint-42",
        "modal_body": {
          "title": "Sprint feedback",
          "submit_label": "Send",
          "blocks": [
            { "type": "text", "text": "Anything on your mind about this sprint?" },
            {
              "type": "input",
              "name": "sentiment_note",
              "label": "Your feedback",
              "multiline": true,
              "required": true,
              "max_length": 1000,
              "placeholder": "One or two sentences is perfect."
            }
          ]
        }
      }
    ]
  }'

Corpo do POST de envio de modal (o Dailybot publica isto em callback_url):

{
  "event": "modal_submit",
  "bot_message_id": "$db/…",
  "button":       { "id": "$btn/…", "value": "feedback" },
  "user":         { "id": "…", "email": "…", "display_name": "…", "external_id": "U…" },
  "organization": { "id": "…", "name": "…" },
  "platform":     "slack",
  "channel":      { "id": "C…", "type": "channel" },
  "modal_fields": {
    "sentiment_note": "Retro was great, ship-per-day cadence is working."
  },
  "metadata":     { },
  "sent_at":      "2026-07-22T14:30:00Z",
  "clicked_at":   "2026-07-22T14:31:12Z"
}

Mesmos cabeçalhos / assinatura que button_click; apenas event e modal_fields diferem.

Modais somente de exibição (blocos contêm apenas text e divider, sem input) são permitidos sem callback_url — clicar em Submit apenas fecha o modal e nenhum POST é disparado.

Gatilhos de formulários internos

Um botão interactive com callback_form abre um formulário do Dailybot no clique. Nenhum serviço externo é chamado; o callback_url do chamador é ignorado (e rejeitado se ambos estiverem definidos).

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Need to request access to a system?",
    "target_channels": ["C0AF0FBT23D"],
    "buttons": [
      { "label": "Open access-request form",
        "button_type": "interactive",
        "value": "open_access_form",
        "callback_form": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    ]
  }'

callback_form deve ser o UUID de um formulário do Dailybot na organização do chamador (liste seus formulários via /v1/forms/ para encontrá-lo). Nomes e slugs são rejeitados — nomes de formulário são mutáveis e ambíguos. Formulários desconhecidos, arquivados ou inacessíveis → 400 button_callback_form_not_found. O formulário é preenchido pelo usuário pelo fluxo de formulários existente — veja /v1/forms/ para ler as respostas resultantes.

Gatilhos de comandos internos

Um botão interactive com callback_command executa um comando interno CONHECIDO do Dailybot no clique (ex.: help, kudos, checkin). Máx. 200 caracteres.

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Need help getting started?",
    "target_users": ["…"],
    "buttons": [
      { "label": "Open help",
        "button_type": "interactive",
        "value": "help",
        "callback_command": "help" }
    ]
  }'

Sem prefixo prompt:. A convenção legada "prompt: <text>" foi removida. Um callback_command que começa com prompt: (sem distinção de maiúsculas) é rejeitado com 400 button_callback_command_invalid — use o campo dedicado callback_prompt.

Atribuição. O comando roda sob a identidade do usuário que clica (escopo de papel, atribuição de uso) — não do remetente. Chamadores não podem usar callback_command para fazer outro usuário executar um comando que não tem permissão.

Comandos desconhecidos (não na lista de comandos integrados) falham suavemente com uma resposta localizada “That command isn’t available” ao usuário que clicou — sem erro para o remetente.

Gatilhos de prompts de IA

Um botão interactive com callback_prompt envia um prompt de texto livre (≤ 2000 caracteres) ao assistente de IA do Dailybot no clique, atribuído ao usuário que clica (sua cota de IA, suas permissões).

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Curious about last week?",
    "target_users": ["…"],
    "buttons": [
      { "label": "Ask the assistant",
        "button_type": "interactive",
        "value": "ask_ai",
        "callback_prompt": "Summarize incidents from the past 7 days." }
    ]
  }'

Prompts em branco ou acima do tamanho → 400 button_callback_prompt_invalid.

Gatilhos de workflows

Um botão interactive com callback_workflow aciona um workflow interno do Dailybot no clique, atribuído ao usuário que clica. callback_workflow deve ser o UUID de um workflow na organização do chamador — nomes/slugs são rejeitados. O workflow deve existir, pertencer à organização e estar ativo; caso contrário 400 button_callback_workflow_not_found.

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Deploy is ready.",
    "target_users": ["…"],
    "buttons": [
      { "label": "Run release workflow",
        "button_type": "interactive",
        "value": "run_release",
        "callback_workflow": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    ]
  }'

Nenhum POST externo é disparado e nenhum material de assinatura está envolvido — o gatilho é totalmente interno.

Variáveis de gatilho. Passos do workflow acionado podem referenciar o contexto do clique pelo namespace {{trigger.*}}: {{trigger.source}} (api | button_click | modal_submit), {{trigger.button_value}}, {{trigger.button_id}}, {{trigger.fields.<name>}} (entradas do modal), {{trigger.clicked_at}}, {{trigger.body.*}} (payload bruto), {{trigger.user.*}} (uuid, full_name, first_name, email, role do usuário que clicou) e {{trigger.triggered_by_user_uuid}}. Para ramificação simples por valor, aponte vários botões ao MESMO workflow com values diferentes e ramifique em {{trigger.button_value}}. Veja /developers/api/workflows para a referência completa de variáveis de gatilho.

Modal → Workflow

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

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Report an incident:",
    "target_users": ["…"],
    "buttons": [
      { "label": "Report", "button_type": "interactive", "value": "report",
        "callback_workflow": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "modal_body": {
          "title": "New incident",
          "blocks": [
            { "type": "input", "name": "summary", "label": "What happened?",
              "multiline": true, "required": true }
          ]
        } }
    ]
  }'

O workflow (tipo de gatilho api_trigger) pode então usar {{trigger.fields.summary}} em qualquer passo — pré-preencher uma resposta de formulário, compor uma mensagem, alimentar um prompt de IA. Botões modal-para-workflow não carregam segredo de assinatura (rota interna). Um modal com blocos input e SEM callback_url nem callback_workflow é rejeitado (input_without_callback).

Respostas automáticas

Qualquer botão (incluindo um botão interativo simples sem callback) pode carregar um objeto response — uma resposta automática mostrada ao usuário que clica:

{
  "message": "string — required, ≤ 2000 chars",
  "buttons": [],
  "replace_original": false,
  "ephemeral": false
}

O caso “Skip” — um botão cuja única função é reconhecer:

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Time for your weekly reflection!",
    "target_users": ["…"],
    "buttons": [
      { "label": "Start", "button_type": "interactive", "value": "start",
        "callback_form": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
      { "label": "Skip this week", "button_type": "interactive", "value": "skip",
        "response": { "message": "No problem — see you next week! 👋" } }
    ]
  }'

Momento. Com callback_url, a resposta é enviada imediatamente no clique, em paralelo com o POST de saída — é feedback instantâneo ao usuário (“Processing your approval…”), nunca condicionado ao resultado do despacho. Este é o padrão canônico de aprovação lenta: reconhecer instantaneamente via response, depois seu servidor acompanhar no próprio ritmo com um novo POST /v1/send-message/ ou editando a mensagem original dentro da janela de 72 h de bot_message_id. Com modal_body, a resposta é enviada após o ENVIO do modal. Com os callbacks internos (callback_form / callback_command / callback_prompt / callback_workflow), a resposta é enviada ANTES da entrega.

replace_original — substitui a mensagem de origem em vez de publicar uma nova. ephemeral — apenas Slack; ignorado em outros lugares.

Botões recursivos. response.buttons usa o mesmo esquema Button e é validado recursivamente: profundidade máxima de aninhamento 3, ≤ 25 botões por nível, button_id gerado pelo servidor em cada profundidade e um limite de tamanho serializado total de 16 KiB por botão de nível superior. Violações → 400 button_response_invalid com detail um de response_message_required, response_message_too_long, nesting_too_deep, too_many_buttons, button_too_large.

Autenticação de callback

Todo POST de callback é SEMPRE assinado com o cabeçalho HMAC X-Dailybot-Signature (veja Segredo de assinatura de callback). Se seu endpoint adicionalmente exige credenciais estáticas — token de API gateway, basic auth, cabeçalho fixo — anexe um objeto callback_auth. Só é válido junto com callback_url.

curl -X POST "https://api.dailybot.com/v1/send-message/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Approve the vendor payment?",
    "target_users": ["…"],
    "buttons": [
      { "label": "Approve", "button_type": "interactive", "value": "approve",
        "callback_url": "https://approvals.acme.example/v1/req_77",
        "callback_auth": { "type": "bearer", "token": "acme-gw-token-…" } }
    ]
  }'

Tipos (exatamente os campos do tipo escolhido — extras são rejeitados):

header_name deve ser um token de cabeçalho RFC 7230 válido e não pode ser um de host, content-length, content-type, transfer-encoding, connection, user-agent, nem qualquer coisa que comece com x-dailybot-. Violações → 400 button_callback_auth_invalid.

Credenciais são somente de escrita: nunca são retornadas por nenhuma API de leitura e nunca aparecem em logs. A assinatura HMAC permanece obrigatória — verifique-a mesmo quando também exigir auth estática.

Códigos de erro de botões interativos

Todos são HTTP 400. A forma da resposta segue o envelope existente ({ "detail": "…", "code": "…" }).

Os comportamentos existentes relacionados a botões (limite de buttons.length de 25, erros send_as_user_*, invalid_thread_responses, etc.) permanecem inalterados.

Segredo de assinatura de callback

Cada organização tem um único segredo de assinatura de callback usado para HMAC. É gerado automaticamente na primeira vez que uma mensagem com callback_url é enviada. O segredo nunca é retornado pela API pública; obtenha-o do administrador da sua organização (um endpoint de rotação / recuperação está no roadmap). Guarde-o no armazenamento de segredos do seu serviço; trate-o como um segredo de cliente OAuth.

Veja em ação

Receitas de automação construídas sobre a API send-message, a CLI e a skill de agentes — cada uma com exemplos de curl, CLI e prompts prontos para copiar e colar.

• Automação de chat e mensagens interativas
• Gates de aprovação de CI/CD
• Workflows a partir do chat
• Registro de incidentes com modais
• Ciclo de vida de formulários
• Automação de check-ins
• Relatórios da frota de agentes
• Todas as receitas de automação