# Chat deployment (/workflows/deployment/chat) 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](/workflows/triggers/start) for the message and attachments. To retain earlier conversation context, configure [Agent Memory](/workflows/blocks/agent#memory) and use `` 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 [#creating-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](/logs-debugging). | Setting | Meaning | | - | - | | **URL** | Unique slug across workspaces, using lowercase letters, numbers, and hyphens | | **Title** | Name shown in the chat header | | **Output** | Selected block fields returned to the chat; at least one is required | | **Welcome message** | Initial greeting; defaults to `Hi there! How can I help you today?` | | **Access control** | Public, password, email, or supported SSO access | | **Include thinking** | Provider-exposed reasoning, off by default | | **Include tool calls** | Tool names and lifecycle status, off by default | 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](/workflows/deployment/agent-events). ### Output selection [#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 [#access-control] | Mode | Requirement | | - | - | | **Public** | Anyone with the link can submit messages | | **Password** | The caller supplies the configured password | | **Email** | Allowed addresses/domains verify with a six-digit email OTP | | **SSO** | OIDC single sign-on with configured identity provider and allowed email scope; requires the deployment's enterprise SSO capability | Public access allows anonymous people to run the workflow. Review what its input can trigger and what its selected outputs reveal before sharing the link. 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**: Email access control with an allowed domain entered 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](/platform/enterprise/sso) for setup and capability requirements. ## Sharing [#sharing] ### Direct link [#direct-link] ```text https://www.sim.ai/chat/your-slug ``` Use your deployment's origin instead of `www.sim.ai` when self-hosting. ### Iframe [#iframe] ```html ``` 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 [#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: ```bash 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"}' ``` ```typescript 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](/workflows/deployment/agent-events#reference-client) 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 [#with-file-uploads] Send file metadata and a base64 data URL: ```bash 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 [#protected-chats] A password-protected request includes `password`: ```bash 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: ```bash 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 [#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 [#related-docs] * [Deployment](/workflows/deployment) * [Start](/workflows/triggers/start) * [Agent stream events](/workflows/deployment/agent-events)