Start Node

Every workflow begins with a Start node. It defines when and how the workflow is triggered.

Trigger types

Manual trigger

The simplest option for testing. Click Run and optionally provide input data. Manual runs are ideal during development.

Webhook trigger

1. Set trigger type to Webhook.
2. Choose the HTTP method (GET, POST, PUT, PATCH, DELETE).
3. Copy the generated webhook URL from the configuration panel.
4. Configure authentication on the Start node (required to publish and to accept requests):
   • API Key (default) — you choose a secret value here
   • Bearer Token — you choose a token value here
   • Basic Auth — you choose username + password here

Open webhooks (None) are rejected. Publish fails until a secret is configured.

How webhook auth works

This secret is not an organization API key from Settings → API Keys. You create it on the Start node, then tell the external app how to send it when it calls your URL:

1. In TogoFlow, set the secret on the Start node and publish.
2. Copy the Full URL from the Start node — when auth is configured, the copy already includes the secret as a query param (e.g. ?api_key=…).
3. Paste that URL into the external app when registering the webhook.
4. If the app supports custom headers, you can instead use the bare URL plus a header (x-api-key or Authorization: Bearer …).

The request body becomes available as {{inputs}} for downstream nodes.

Example — API key in a header:

curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_WEBHOOK_SECRET" \
  -d '{"customer": "Acme Corp", "amount": 1500}'

Example — same secret in the query string (for apps that only accept a URL):

curl -X POST "YOUR_WEBHOOK_URL?api_key=YOUR_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"customer": "Acme Corp", "amount": 1500}'

Accepted query names for API key auth include api_key, apiKey, key, token, and the configured header name. Bearer auth also accepts ?token=… (or access_token / bearer).

Example — bearer token header:

curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WEBHOOK_TOKEN" \
  -d '{"customer": "Acme Corp", "amount": 1500}'

Prefer headers when the external app supports them — query secrets can appear in logs and referrers.

Schedule trigger

1. Set trigger type to Schedule.
2. Enter a cron expression (e.g. 0 9 * * * for every day at 9:00 AM).
3. Set the timezone (defaults to UTC).

The Start node name updates to reflect the schedule (e.g. "Every Morning (9am)").

App trigger

1. Set trigger type to App.
2. Select the app (Gmail, Slack, etc.).
3. Choose the event (e.g. "Email Received").
4. Connect your account via OAuth when prompted.

The event payload is available as {{inputs}} for downstream nodes.

Agent trigger

Used with the AI agent chat sidebar. The Start node acts as the entry point when the agent initiates or continues a workflow on your behalf.

Chat trigger

Turn a workflow into a chat backend for websites and apps. Callers POST a message to your chat URL; the workflow runs and returns a reply. Conversation memory is kept per sessionId.

There are two ways to expose chat:

Setup (both modes)

1. Set trigger type to Chat.
2. (Optional) Add a Chat Path — a custom segment appended to the URL (e.g. /support).
3. (Optional) Restrict Allowed origins to specific websites.
4. Publish the workflow — chat triggers only fire on published workflows.

The chat URL has the form:

POST https://api.togoflow.ai/api/v1/chat/{workflowId}[/chat-path]

Website widget (embed)

Paid feature: The website chat bubble is available on paid plans. Free workspaces can still use the chat API with an organization API key from a backend.

1. On the Chat Start node, turn on Website widget.
2. Set title, greeting, primary color, and which visitor fields to collect (name, email, phone).
3. Click Generate embed token and copy the snippet (shown once).
4. Paste the script on your site (before </body>):

<script
  src="https://app.togoflow.ai/embed/chat.js"
  data-workflow-id="WRK_your-workflow-id"
  data-token="tce_your_embed_token"
  async
></script>

Optional attributes:

The embed token is publishable — safe in frontend HTML. It is not an organization API key. Regenerate it from the Start node if it is leaked.

The widget loads config from:

GET https://api.togoflow.ai/api/v1/chat/{workflowId}/widget-config
Header: x-chat-embed-token: tce_…

Authentication (API)

Server-to-server: send an organization API key in the x-api-key header. Create one under Settings → API Keys. See API Keys.

Website widget: use x-chat-embed-token (or the script’s data-token). Do not put organization API keys in browser JavaScript.

In-app / logged-in users: you can also proxy through your app’s authenticated backend so the browser never holds a key.

Sending a message (server-to-server)

curl -X POST "https://api.togoflow.ai/api/v1/chat/WRK_your-workflow-id/support" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -d '{"message": "Hello, what can you help me with?"}'

Immediate reply (workflow finished):

{
  "success": true,
  "sessionId": "CHS_...",
  "executionId": "EXC_...",
  "reply": "Hi! I can help you with..."
}

Operator handoff (waiting + poll)

If the workflow pauses (for example Lark interactive card with Wait for response), the chat endpoint does not fail. It returns a holding reply and pending: true:

{
  "success": true,
  "sessionId": "CHS_...",
  "executionId": "EXC_...",
  "reply": "Thank you for your enquiry — please hold on while we get an operator.",
  "status": "waiting",
  "pending": true
}

The website widget shows that message and polls for later operator replies:

GET https://api.togoflow.ai/api/v1/chat/{workflowId}/messages?sessionId=CHS_...&after=ISO_TIMESTAMP
Header: x-chat-embed-token: tce_…

To push a reply into the visitor’s session from any channel (Lark, email, WhatsApp, Telegram, …), use an Action node:

Website Chat → Reply to Session

No extra credentials are required for Website Chat. See the Website Chat + Lark handoff recipe and Lark interactive cards.

Conversation memory

The first response returns a sessionId. Send it back with follow-up messages to continue the same conversation — the last 20 messages of the session are injected as history:

curl -X POST "https://api.togoflow.ai/api/v1/chat/WRK_your-workflow-id/support" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_ORG_API_KEY" \
  -d '{"message": "What did I just ask you?", "sessionId": "CHS_..."}'

Omit sessionId to start a fresh conversation. The embed script omits sessionId on the visitor’s first message so the server can attach visitor metadata cleanly.

Data available to nodes

Downstream nodes receive the chat payload as {{inputs}}:

Point an AI node at {{inputs.message}} and include {{inputs.history}} in its context for a bot-style assistant. For human handoff, notify an operator channel, wait if needed, then use Website Chat → Reply to Session.

When the run completes without waiting, the reply sent back to the caller is extracted from the final node's output (fields like reply, output, text, etc.).

Allowed origins

By default any website can call the endpoint from a browser (a valid API key or embed token is still always required). To restrict it, list origins in the configuration panel — comma or newline separated:

• Full origin: https://example.com (exact match)
• Bare domain: example.com (matches both http:// and https://)

The allowlist only applies to browser requests (which send an Origin header). Server-to-server callers like curl or a backend are authenticated by the API key alone.

Limits and errors

• Executions time out after 60 seconds when waiting for a full reply; the endpoint is rate-limited to 60 messages per minute per IP.
• Waiting/paused runs return pending: true instead of timing out the whole handoff.
• 401 — missing or invalid API key / embed token, or the key belongs to a different organization
• 403 — origin not allowed, free-tier widget/embed, or website widget disabled
• 404 — workflow not published, no chat trigger, widget disabled, or the chat path doesn't match
• 408 — the workflow didn't finish within the timeout (non-waiting path)
• 502 — the workflow execution failed (check the execution logs)

Response mode (webhook)

For webhook triggers, configure how TogoFlow responds to the caller:

• Return the last node's output as JSON
• Return a custom response body
• Return immediately (async execution)

Tips

• Use Manual while building, then switch to Webhook or Schedule for production.
• Always configure webhook authentication before publishing; treat the URL as public and the secret as private.
• For app triggers, ensure the app account stays connected under Settings → Connections.
• For an AI chatbot, keep the sync path fast so replies return within 60 seconds.
• For operator handoff, use Wait for response on Lark/Slack cards, then Website Chat → Reply to Session.
• Use the website widget + embed token for public sites; use organization API keys only on your server.