Messaging

The Dailybot public API exposes messaging endpoints for delivering bot messages, emails, and private conversations across Slack, Microsoft Teams, Discord, and Google Chat. This page includes the full structured field tables for POST /v1/send-message/, POST /v1/send-email/, and POST /v1/open-conversation/ (including the complete Button / modal_body / response / callback_auth contracts), plus the send_as_user identity override and the Interactive buttons deep-dive.

Button Builder

Below the send-message reference, an interactive Button Builder lets you compose interactive buttons visually — link, plain, approve/reject, workflow, form, command, prompt, and modal buttons — and copy the exact buttons JSON array, the equivalent dailybot chat send command (using --link-button, --button, --approve-button/--reject-button with --callback-url/--callback-bearer, or --workflow-button, falling back to --buttons '<json>' for anything those flags can’t express), or a ready-to-run curl body for POST /v1/send-message/.

send_as_user identity override (Slack only)

send_as_user lets an authorized caller post a message that appears to come from another user — the message shows that user’s Slack display name and avatar instead of the bot’s identity. This is useful for automated workflows that need to present messages from the perspective of a specific team member.

Requirements:

• Caller must be an organization admin, or have a key owned by an admin.
• The target user (send_as_user UUID) must be active and in the same organization.
• Only applies on Slack — other platforms ignore the field and fall back to the standard bot identity.
• send_as_user is mutually exclusive with bot_username, bot_icon_url, and bot_icon_emoji. Combining them returns 400 with code: "send_as_user_conflict".

When send_as_user is set, Dailybot looks up the user’s connected Slack identity and uses it as the message author. The message is still sent through the Dailybot bot token — it does not use the user’s own Slack token.

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"
  }'

Error codes for send_as_user:

Interactive buttons

Every message may carry up to 25 buttons rendered as native interactive elements on Slack, Microsoft Teams, Discord, and Google Chat. Two button_type values are supported:

• link — clicking opens the url in the user’s browser.
• interactive — clicking triggers one of four capabilities described below.

Button fields

Every server-side interactive button carries a server-minted button_id = "$btn/<uuid4>" that is echoed back in every callback body so the caller can uniquely identify each click. Client-supplied button_id values are silently overwritten.

Legacy note: payload.callback_config and action value fields from older integrations still work and are additive — prefer the top-level fields above for new integrations.

Compatibility matrix

✔ = allowed together, ✖ = rejected. The five callbacks are mutually exclusive with each other (button_callback_conflict).

A modal with input blocks requires callback_url OR callback_workflow (400 button_modal_body_invalid, detail input_without_callback).

label_after_click and destroy_button compose with everything (including response): destroy_button: false keeps the button clickable — every click is a fresh dispatch with a fresh X-Dailybot-Delivery id; for modal buttons the label_after_click flip happens at modal SUBMIT, not at open, so a cancelled modal leaves the button clickable. A plain interactive button may carry response with no callback at all (the “Skip” case).

Interactive callback URLs

An interactive button with callback_url receives an HTTP POST from Dailybot when the user clicks. This is the canonical shape for approval, feedback, and lightweight triage flows built on top of /v1/send-message/.

Request example:

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" }
    ]
  }'

Callback POST body — Dailybot fires this when the user clicks:

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"
}

platform values. One of slack, msteams, discord, or hangouts. Google Chat is delivered as hangouts (the historical platform identifier) — match on that value, not on “gchat” or “googlechat”. sent_at is stamped when the platform message was actually delivered; clicked_at when the user clicked. metadata round-trips verbatim from your original /v1/send-message/ call.

Signature verification. Every POST carries an HMAC-SHA256 signature computed with your organization’s callback signing secret over the ASCII string "{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'])

Idempotency. X-Dailybot-Delivery is unique per click attempt. If Dailybot’s outbound POST is retried, the same delivery id is sent — use it as a dedup key.

Retries. Dailybot retries once with a 500 ms backoff on 5xx / 429 / network errors. Successful 2xx completes the fanout; any other 4xx is treated as terminal and dropped.

Modal buttons

Add a modal_body object to an interactive button to open a lightweight modal on click. On submit, the modal’s input values are POSTed to callback_url alongside event: "modal_submit" and the value of the clicked button.

modal_body schema:

Supported block types are exactly text, input, and divider. The serialized modal_body must be ≤ 8 KiB. Input name values must match ^[a-z][a-z0-9_]{0,62}$ and be unique within the 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" }
  ]
}

Request example (approve-with-comment):

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."
            }
          ]
        }
      }
    ]
  }'

Modal-submit POST body (Dailybot posts this to 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"
}

Same headers / signature as button_click; only event and modal_fields differ.

Display-only modals (blocks contain only text and divider, no input) are allowed without callback_url — clicking Submit just closes the modal and no POST fires.

Internal form triggers

An interactive button with callback_form opens a Dailybot form on click. No external service is called; the caller’s callback_url is ignored (and rejected if both are set).

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 must be the UUID of a Dailybot form in the caller’s organization (list your forms via /v1/forms/ to find it). Names and slugs are rejected — form names are mutable and ambiguous. Unknown, archived, or not-accessible forms → 400 button_callback_form_not_found. The form itself is filled by the user through the existing forms flow — see /v1/forms/ for how to read the resulting responses.

Internal command triggers

An interactive button with callback_command runs a KNOWN internal Dailybot command on click (e.g. help, kudos, checkin). Max 200 characters.

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" }
    ]
  }'

No more prompt: prefix. The legacy "prompt: <text>" convention has been removed. A callback_command starting with prompt: (case-insensitive) is rejected with 400 button_callback_command_invalid — use the dedicated callback_prompt field instead.

Attribution. The command runs under the clicking user’s identity (role scope, usage attribution) — not the sender’s. Callers cannot use callback_command to make another user run a command they aren’t allowed to run.

Unknown commands (not in the built-in commands list) fail softly with a localized “That command isn’t available” reply to the clicker — no error to the sender.

AI prompt triggers

An interactive button with callback_prompt sends a free-text prompt (≤ 2000 chars) to the Dailybot AI assistant on click, attributed to the clicking user (their AI quota, their permissions).

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." }
    ]
  }'

Blank or oversized prompts → 400 button_callback_prompt_invalid.

Workflow triggers

An interactive button with callback_workflow triggers an internal Dailybot workflow on click, attributed to the clicking user. callback_workflow must be the UUID of a workflow in the caller’s organization — names/slugs are rejected. The workflow must exist, belong to the organization, and be active; otherwise 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" }
    ]
  }'

No external POST fires and no signing material is involved — the trigger is fully internal.

Trigger variables. Steps of the triggered workflow can reference the click context through the {{trigger.*}} namespace: {{trigger.source}} (api | button_click | modal_submit), {{trigger.button_value}}, {{trigger.button_id}}, {{trigger.fields.<name>}} (modal inputs), {{trigger.clicked_at}}, {{trigger.body.*}} (raw payload), {{trigger.user.*}} (uuid, full_name, first_name, email, role of the clicker) and {{trigger.triggered_by_user_uuid}}. For plain value-branching, point several buttons at the SAME workflow with different values and branch on {{trigger.button_value}}. See /developers/api/workflows for the full trigger-variable reference.

Modal → Workflow

modal_body composes with callback_workflow: the click opens the modal, and on submit the field values are delivered to the workflow as {{trigger.fields.<input.name>}} — no external server involved.

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 }
          ]
        } }
    ]
  }'

The workflow (trigger type api_trigger) can then use {{trigger.fields.summary}} in any step — pre-fill a form answer, compose a message, feed an AI prompt. Modal-to-workflow buttons carry no signing secret (internal route). A modal with input blocks and NEITHER callback_url nor callback_workflow is rejected (input_without_callback).

Auto-replies

Any button (including a plain interactive button with no callback) may carry a response object — an automatic reply shown to the clicker:

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

The “Skip” case — a button whose only job is to acknowledge:

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! 👋" } }
    ]
  }'

Timing. With callback_url, the response is sent immediately on click, in parallel with the outbound POST — it is instant user feedback (“Processing your approval…”), never gated on the dispatch outcome. This is the canonical slow-approval pattern: acknowledge instantly via response, then have your server follow up on its own time with a new POST /v1/send-message/ or by editing the original message within the 72h bot_message_id window. With modal_body, the response is sent after modal SUBMIT. With the internal callbacks (callback_form / callback_command / callback_prompt / callback_workflow), the response is sent BEFORE handing off.

replace_original — replace the source message instead of posting a new one. ephemeral — Slack-only; ignored elsewhere.

Recursive buttons. response.buttons uses the same Button schema and is validated recursively: max nesting depth 3, ≤ 25 buttons per level, server-minted button_id at every depth, and a total serialized size cap of 16 KiB per top-level button. Violations → 400 button_response_invalid with detail one of response_message_required, response_message_too_long, nesting_too_deep, too_many_buttons, button_too_large.

Callback authentication

Every callback POST is ALWAYS signed with the HMAC X-Dailybot-Signature header (see Callback signing secret). If your endpoint additionally requires static credentials — an API gateway token, basic auth, a fixed header — attach a callback_auth object. It is only valid together with 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-…" } }
    ]
  }'

Types (exactly the fields of the chosen type — extras are rejected):

header_name must be a valid RFC 7230 header token and may not be one of host, content-length, content-type, transfer-encoding, connection, user-agent, or anything starting with x-dailybot-. Violations → 400 button_callback_auth_invalid.

Credentials are write-only: they are never returned by any read API and never appear in logs. The HMAC signature remains mandatory — verify it even when you also require static auth.

Interactive button error codes

All are HTTP 400. Response shape follows the existing envelope ({ "detail": "…", "code": "…" }).

The existing button-related behaviors (buttons.length cap of 25, send_as_user_* errors, invalid_thread_responses, etc.) are unchanged.

Callback signing secret

Every organization has a single callback signing secret used for HMAC. It is auto-generated the first time a message with callback_url is sent. The secret is never returned by the public API; obtain it from your organization’s admin (a rotation / retrieval endpoint is on the roadmap). Keep it in your service’s secret store; treat it like an OAuth client secret.

See it in action

Automation recipes built on the send-message API, the CLI, and the agent skill — each with copy-paste curl, CLI, and agent-prompt examples.

• Chat automation & interactive messages
• CI/CD approval gates
• Workflow triggers from chat
• Incident intake with modals
• Forms lifecycle automation
• Check-ins automation
• Agent fleet reporting
• All automation recipes