Chat deployment

Deploy a workflow as a chat page, then share its link or embed it in your site. Each message starts a fresh workflow run using the active deployment.

You need workspace Admin access and permission to deploy chats. Configure a Start block for the message and attachments. To retain earlier conversation context, configure Agent Memory and use <start.conversationId> as the conversation ID. The chat sends the latest input, conversationId, and current files; it does not automatically pass the whole conversation history to every block.

Create a chat

1. Open Deploy → Chat.
2. Set a unique URL and Title.
3. Choose at least one field in Output. For an Agent answer, select content from the block that produces it.
4. Choose Access control and complete its settings.
5. Set a Welcome message and optional event policies, then click Launch Chat.
6. Open the chat link, submit a message, and verify the response and recorded run in Logs.

The event policies are independent. Custom clients need X-Sim-Stream-Protocol: agent-events-v1 to receive their frames; the hosted UI sends it. Public chat removes tool arguments and results from its tool-call metadata. See Agent stream events.

Output selection

The picker groups fields by block. Agent fields include content, model, tokens, toolCalls, providerTiming, and cost; a successful structured response can expose different fields. Choose the values your chat should show, rather than every available field.

The hosted client also negotiates structured output frames for non-text values such as file metadata. That is separate from the thinking/tool policies.

Access control

For Password, set and share the password with intended callers. For Email, add individual addresses such as user@example.com or domains such as @example.com to Allowed emails:

OTP codes expire after 15 minutes. The hosted UI uses a 30-second resend countdown; server request limits still apply. Verification creates an authentication cookie for subsequent chat requests.

For SSO, configure the identity provider and allowed addresses/domains. See SSO for setup and capability requirements.

Sharing

Direct link

https://www.sim.ai/chat/your-slug

Use your deployment's origin instead of www.sim.ai when self-hosting.

Iframe

<iframe
  src="https://www.sim.ai/chat/your-slug"
  width="100%"
  height="600"
  title="Chat"
></iframe>

Your site's Content Security Policy must permit the chat origin in frame-src. Protected chats still require authentication; the browser's cookie policy can affect authentication inside an iframe.

API submission

POST /api/chat/{identifier} returns SSE. Reuse a conversationId across messages when the workflow uses Agent Memory. For live answer tokens, send the protocol header and handle resets:

curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
  -H 'Content-Type: application/json' \
  -H 'X-Sim-Stream-Protocol: agent-events-v1' \
  -d '{"input":"I need help with my order","conversationId":"order-4821"}'

const response = await fetch('https://www.sim.ai/api/chat/your-slug', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Sim-Stream-Protocol': 'agent-events-v1'
  },
  body: JSON.stringify({
    input: 'I need help with my order',
    conversationId: 'order-4821'
  })
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
if (!response.body) throw new Error('Response body is missing')

const reader = response.body.getReader()
const decoder = new TextDecoder()
let rawSse = ''
try {
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    rawSse += decoder.decode(value, { stream: true })
  }
} finally {
  reader.releaseLock()
}

The TypeScript example collects raw SSE for inspection. Use the reference parser to render answer text, honor chunk_reset, and handle terminal results/errors. Without the protocol header, answer chunks contain settled final-turn text.

With file uploads

Send file metadata and a base64 data URL:

curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
  -H 'Content-Type: application/json' \
  -d '{"input":"What does this document say?","files":[{"name":"report.pdf","type":"application/pdf","size":1048576,"data":"data:application/pdf;base64,..."}]}'

Replace the illustrative data URL with the actual file contents. A request accepts at most 15 files, and each file's encoded data field is limited to 14,680,064 characters. The selected model and upload policy can impose additional limits.

Protected chats

A password-protected request includes password:

curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
  -H 'Content-Type: application/json' \
  -d '{"password":"your-chat-password","input":"Hello"}'

For email access, request and verify the OTP before sending messages:

curl -X POST 'https://www.sim.ai/api/chat/your-slug/otp' \
  -H 'Content-Type: application/json' \
  -d '{"email":"allowed@example.com"}'

curl -X PUT 'https://www.sim.ai/api/chat/your-slug/otp' \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"email":"allowed@example.com","otp":"123456"}'

curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"input":"Hello","conversationId":"order-4821"}'

Use the real code from the email. Protect cookies.txt, which holds the verified session cookie. SSO clients must complete the deployment's SSO authentication flow instead.

Limits and troubleshooting

• 403: inspect the response message. The chat may be inactive, or the caller may not meet its access control. Check both before redeploying.
• At least one output block is required: select an output field in Deploy → Chat.
• OTP missing: check the allowed address/domain, spam folder, and server mail setup; wait for resend limits before requesting another code.
• Iframe unavailable: check your site's frame-src and the browser's authentication-cookie policy.
• Old workflow response: deploy Update after changing the draft. Chat uses the active snapshot.
• Message too long: the chat API accepts at most 1,000,000 characters. The model's context window can be smaller; configured memory also contributes to context.

Related docs

• Deployment
• Start
• Agent stream events