> ## Documentation Index > Fetch the complete documentation index at: https://docs.tied.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a widget session > The entry point, and the only widget endpoint that works without `X-Auth-Token`. Creates a contact and contact inbox for a first-time visitor and returns the widget configuration with the session token in `website_channel_config.auth_token`. Calling it **with** a token returns the existing visitor rather than creating a second one — that is what makes a page reload continue the same conversation. The token lasts 180 days by default and there is no refresh: when it expires, call this again without it. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/widget/config openapi: 3.0.4 info: title: Tied API description: >- The Tied REST API. Three families of endpoint, each with its own credential: **Application** for everything inside an account, **Platform** for provisioning accounts and users, and **Client** for acting as a contact from your own surface. version: 1.1.0 termsOfService: https://tied.com/legal contact: email: hello@tied.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.tied.com description: Tied cloud security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management - name: Contacts API description: Public contact APIs - name: Conversations API description: Public conversation APIs - name: Messages API description: Public message APIs - name: CSAT Survey Page description: Customer satisfaction survey - name: Account description: >- The authenticated user's own account — read and update account settings. Distinct from the Platform family's **Accounts**, which provisions accounts across an installation. - name: Audit Logs description: Read the account's audit trail - name: Inbox API description: Public inbox lookup by channel identifier - name: Labels description: >- Create and manage the account's labels. Applying one to a conversation or contact is a separate endpoint under those resources. - name: Macros description: >- Saved multi-step actions an agent — or an integration — can run against one or more conversations. - name: Campaigns description: Ongoing website campaigns and one-off SMS and WhatsApp sends. - name: Contact Notes description: Internal notes on a contact. Never visible to the contact. - name: Help Center Categories description: Categories group a portal's articles, one tree per allowed locale. - name: Help Center Articles description: The articles a portal publishes, and their draft and archived states. - name: Summary Reports description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON. - name: Live Reports description: Right-now queue counts. No date range — these describe the present. - name: CSAT description: >- The satisfaction ratings contacts have submitted, and the metrics computed from them. - name: Notifications description: >- The per-user notification feed, its read and snooze state, and the settings that decide what lands in it. - name: Conversation Participants description: >- The agents watching a conversation. Participants get notified about it without being assigned to it. - name: Draft Messages description: >- The unsent reply held for a conversation. Stored in Redis, one per conversation. - name: Search description: >- One search service across conversations, contacts, messages and Help Center articles. - name: Dashboard Apps description: Embedded pages that appear as a tab beside a conversation. - name: Assignment Policies description: How conversations are handed out, and which inbox uses which policy. - name: Files description: Storing a file so another endpoint can attach it. - name: Bot Flows description: >- Scripted conversation flows, their versions, and the publish and rollback that move between them. - name: Billing description: >- Credit balance, usage, invoices, spend controls and the provider-hosted payment flows. - name: AMB Templates description: >- Saved Apple Messages primitive payloads an agent can reuse from the composer. - name: AMB Onboarding description: The in-flight Apple Messages for Business registration for an account. - name: Widget Session description: Starting a widget session and reading the visitor it belongs to. - name: Widget Conversation description: The visitor's conversation and its messages. - name: Widget Context description: Campaigns, agents, labels, events and uploads for a widget session. - name: CSAT Survey description: The public, unauthenticated survey a contact answers from a link. - name: Workspace description: Scheduling and cancelling deletion of the whole workspace. paths: /api/v1/widget/config: post: tags: - Widget Session summary: Start a widget session description: >- The entry point, and the only widget endpoint that works without `X-Auth-Token`. Creates a contact and contact inbox for a first-time visitor and returns the widget configuration with the session token in `website_channel_config.auth_token`. Calling it **with** a token returns the existing visitor rather than creating a second one — that is what makes a page reload continue the same conversation. The token lasts 180 days by default and there is no refresh: when it expires, call this again without it. operationId: create-widget-session parameters: - $ref: '#/components/parameters/website_token' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/widget_config' example: website_channel_config: allow_messages_after_resolved: true api_host: https://app.tied.com auth_token: >- eyJhbGciOiJIUzI1NiJ9.eyJzb3VyY2VfaWQiOiI5ODE4MjU1Ni04NDJmLTRkOTUtOGIwZC04ZjczY2Y5MWJmMTIiLCJpbmJveF9pZCI6NCwiZXhwIjoxODA1NTE3MTAyLCJpYXQiOjE3ODk5NjUxMDJ9.NQy93V5gzL1lLe2rp6hE_BB9Ciccmi4hwk46_ZmwhDU avatar_url: '' csat_survey_enabled: false disable_branding: false enabled_features: - attachments - emoji_picker enabled_languages: - name: English (en) iso_639_1_code: en - name: العربية (ar) iso_639_1_code: ar locale: en out_of_office_message: null portal: null pre_chat_form_enabled: false pre_chat_form_options: pre_chat_fields: - name: emailAddress type: email label: Email Id enabled: false required: true field_type: standard - name: fullName type: text label: Full name enabled: false required: false field_type: standard pre_chat_message: Share your queries or comments here. reply_time: in_a_few_minutes timezone: UTC utc_off_set: '+00:00' website_name: Webchat website_token: EXAMPLE_WEBSITE_TOKEN welcome_tagline: null welcome_title: null widget_color: '#FF073B' working_hours: - id: 22 inbox_id: 4 account_id: 1 day_of_week: 0 closed_all_day: true open_hour: null open_minutes: null close_hour: null close_minutes: null created_at: '2026-09-19T20:36:30.467Z' updated_at: '2026-09-19T20:36:30.467Z' open_all_day: false - id: 23 inbox_id: 4 account_id: 1 day_of_week: 1 closed_all_day: false open_hour: 9 open_minutes: 0 close_hour: 17 close_minutes: 0 created_at: '2026-09-19T20:36:30.472Z' updated_at: '2026-09-19T20:36:30.472Z' open_all_day: false working_hours_enabled: false contact: email: null id: 266 identifier: null name: silent-snow-603 phone_number: null pubsub_token: EXAMPLE_PUBSUB_TOKEN global_config: LOGO_THUMBNAIL: /brand-assets/tied-app-icon.png BRAND_NAME: Tied WIDGET_BRAND_URL: https://tied.com INSTALLATION_NAME: Tied '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/error_unauthenticated' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/error_message' security: [] components: parameters: website_token: name: website_token in: query required: true description: >- The web-widget inbox's public token, as it appears in your widget snippet. Required on every widget request. schema: type: string example: EXAMPLE_WEBSITE_TOKEN schemas: widget_config: type: object description: >- Everything the widget needs to render itself, plus the session token for every later call. properties: website_channel_config: type: object description: >- Widget appearance, enabled features, locales, pre-chat form, working hours — and `auth_token`, the session token to send as `X-Auth-Token` from here on. additionalProperties: true error_unauthenticated: type: object description: >- Returned by Devise when the `api_access_token` header is absent entirely, before the token check runs. Note `errors` holds plain strings, not objects. properties: errors: type: array items: type: string example: - You need to sign in or sign up before continuing. description: >- One or more messages explaining why the request was not authenticated. required: - errors error_message: type: object description: >- The shape returned by `render_unauthorized`, `render_not_found_error` and `render_could_not_create_error`. properties: error: type: string description: A single human-readable message. example: Resource could not be found required: - error ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.