SOURCE_ID: import_from_slack NAME: Import Slack Messages CATEGORY: First-party Import messages from one or more Slack channels into Floqer, either as a one-time historical backfill or as an ongoing source that re-syncs on a schedule. Imported messages become available to your Floqer workflows for routing, enrichment, alerting, and the like. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_slack`. POST /api/v1/sources/import_from_slack/preview Scope: sources:read Returns up to 10 sample message rows across the selected channels, without creating anything. Use this to validate the channel selection and inspect row shape before committing. POST /api/v1/sources/import_from_slack Scope: sources:write Creates the source, runs the historical backfill across the selected channels, and — for an active source — keeps re-syncing on a schedule. Returns `source_instance_id` (the new source's UUID). POST /api/v1/sources/import_from_slack/options/channels Scope: sources:read Resolves the available Slack channels for the connected workspace (see §5). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? } — `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Source-agnostic. Every endpoint for this source first verifies the API-key user has an active Slack connection. Missing connection → 424. 2. IMPORT TYPE (ONE-TIME VS ONGOING) `import_type` is optional and defaults to "static". Values: "static" One-shot historical backfill across the selected channels — no recurring schedule. `frequency` and `expiration_date` are NOT allowed in this mode. "active" Initial backfill PLUS recurring sync on the cadence in `frequency` (a cron string), continuing until `expiration_date` (a long default applies when omitted). `frequency` is required when `import_type: active`. Both `frequency` and `expiration_date` are only valid when `import_type: active` — sending either with a static import is rejected with 400. 3. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400 — the body is strict. Preview accepts: channels required: non-empty array of Slack channel IDs Create accepts all the preview fields plus: name required: display name for the new source import_type "static" | "active"; optional (defaults to "static") frequency cron string; required when import_type === "active"; not allowed for static expiration_date ISO date in the future; optional, active only; not allowed for static 4. FIELD CATALOGUE channels (string[]) — required Non-empty array of Slack channel IDs to import from (at most 50 per request). Resolve them with the `channels` dynamic-options call (§5) — the option `value` is the channel ID. name (string) — required on create only Human-readable display name for the source. import_type (string) — optional, create only "static" (one-shot backfill) or "active" (backfill + recurring sync). Defaults to "static". See §2. frequency (string) — required on create when import_type === "active" Cron string for the re-sync cadence (e.g. "*/15 * * * *"). Not allowed when import_type is "static". expiration_date (string) — optional, active only ISO date in the future after which an active source stops syncing. Not allowed when import_type is "static". 5. DYNAMIC OPTIONS One dynamic-options field name is available for this source. POST to /api/v1/sources/import_from_slack/options/channels with body `{}`. channels Context: none. Returns: {value: , label: , extras} for each channel in the connected Slack workspace. Use the returned `value`s directly inside `channels[]`. Connection check: the call verifies the API-key user has an active Slack connection first. Missing connection → 424. 6. HOW TO CONFIGURE END-TO-END Typical flow for an AI agent building a Slack import source: Step 1 — Resolve the channels POST /api/v1/sources/import_from_slack/options/channels Body: {} Pick the channel `value`s (channel IDs) you want to import from. Step 2 — Preview before committing POST /api/v1/sources/import_from_slack/preview Body: { "channels": ["C0123ABCD", "C0456EFGH"] } Check the returned `data[]` row shape (up to 10 sample messages across the channels). Iterate until you're happy — preview never creates anything. Step 3 — Create the source POST /api/v1/sources/import_from_slack Body: + the create-only fields: "name": "", "import_type": "static" | "active", "frequency": "*/15 * * * *", // only when import_type=active "expiration_date": "2027-01-01" // optional, active only Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 3b — (Optional) Poll imported rows while the backfill runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 3) `total_count` grows as the backfill (and later syncs) import messages. Step 4 — Sync the source into a workflow (so its messages flow downstream) POST /api/v1/sources//sync ( = UUID from Step 3 ) First build `field_mapping`: a. GET /api/v1/workflows → pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs → each input has a `reference` like `{{input.text}}`. c. Map each workflow input (reference WITHOUT braces) to a source field — the source fields are the keys on the preview `data[]` rows. Body: { "workflow_id": "", "field_mapping": { "input.text": "" }, "push_existing": true, "run": "all" } See concepts.txt §10 for the full sync semantics (source-agnostic). The backfill runs asynchronously — the create call returns as soon as the source is created and the backfill has started, not when messages have finished arriving. 7. KEY NOTES - Slack connection is mandatory. If the API-key user has no active Slack connection, every endpoint (preview, create, options) returns 424 ("User is not connected to 'slack'."). Surface this as a "connect Slack first" CTA. - `channels` must be a non-empty array of channel IDs (at most 50). Resolve exact IDs with the `channels` dynamic-options call — the option `value` is the channel ID. - Preview returns at most 10 sample message rows total across the selected channels; `metadata.total_results` reflects that sample count, not the total messages in the channels. - `import_type` defaults to "static" (one-shot backfill). `frequency` and `expiration_date` are only valid when `import_type: active` — sending either with a static import is a 400. - Credits are consumed when the source is created. If credit consumption fails (e.g. insufficient balance), the source is still created but its backfill can't start; the API returns 402 so you can top up and retry. - Use PATCH /status to pause an active source and resume it later without recreating it. 8. WHERE IT FITS UPSTREAM (in Slack) Messages live in channels in the user's connected Slack workspace. THIS SOURCE Creates a Slack import source. On creation it backfills history across the selected channels; an active source also re-syncs on the `frequency` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported messages become available to your Floqer workflows — wire the source into a workflow to route messages, extract leads / intent, or trigger alerts. 9. WHEN TO USE - One-time export of a channel's history into a Floqer workflow: `import_type: static`. - Keep selected channels syncing into a workflow on a schedule (e.g. parse new messages for intent or leads): `import_type: active`, `frequency: "*/15 * * * *"`. When you instead want to send messages OUT of Floqer INTO Slack, use the Slack action template inside a workflow — see the action catalog in action-catalog.txt. Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference