Publishing

Open Publish after testing and saving the agent in Playground. Each website channel has its own visibility control. Hosted-page access settings do not apply to the widget, iframe, or Telegram.

Choose an access mode

• Public lets anyone with the link open and use the agent.
• Owner only requires the signed-in workspace owner.
• Password requires the link and the password you set. New passwords must contain at least eight characters.

Changing or removing password access invalidates earlier password access. Share passwords through a separate trusted channel and change them when they may have been exposed.

Workspace viewers can inspect and copy publication details, but only members with write permission can change access.

Direct link

Use the direct link when the agent should open as a standalone page. Copy it into a website button, email, QR code, or social post. Test the link in a signed-out or private browser window so you see the same access prompt as a visitor.

Floating widget

Copy the widget script into the website pages where the floating chat launcher should appear. The script uses the agent’s Public ID and opens the customer-facing chat in a popup.

After installing it:

1. Confirm the launcher appears once.
2. Test opening, closing, scrolling, and sending a message.
3. Check desktop and mobile layouts.
4. Verify the site security policy allows the Orkata script and frame origins.

Identify signed-in visitors

For trusted identity, do not rely on a plain user ID or profile from browser code. A visitor can edit browser JavaScript and impersonate another customer. Open Publish → Chat bubble → Identify signed-in visitors, create a signing secret, and store it in your server environment as ORKATA_IDENTITY_SECRET.

Extend your existing login response after authentication succeeds. Sign the customer record returned by your database—not identity fields submitted by the browser—and add visitorIdentityToken beside your normal response data:

{ "visitorIdentityToken": "eyJhbGciOi..." }

The Publish panel includes syntax-highlighted examples for Node.js, Python, PHP, Ruby, .NET, and Go. The token must contain v: 1, the agent Public ID in aud, the stable customer ID in sub, integer iat and exp timestamps. Include name, email, and phone whenever they are available, and put additional trusted profile fields in the optional JSON-object metadata claim. All profile fields are covered by the signature. Tokens may live for at most 24 hours; one hour is a practical default. Never expose the signing secret to browser code or a public environment variable.

In the frontend, read the additional field from the same successful login response and pass it to the widget:

async function loginUser(email, password) {
  const response = await fetch("/api/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password })
  });
  if (!response.ok) throw new Error("Login failed");

  const { user, visitorIdentityToken } = await response.json();
  window.orkata.identify(visitorIdentityToken, {
    client_context: {
      currentPage: window.location.pathname,
      locale: document.documentElement.lang
    }
  });

  return user;
}

The optional client_context object gives the agent current browser context, such as the page, selected product, or locale. It is sanitized, limited to 6 KB of JSON, sent with chat requests, and not stored with the signed profile. Because it comes from the browser, Orkata labels it unverified and never uses it for authentication or authorization. Put trusted attributes in signed metadata instead.

The exchange is: existing login request → authenticated server user → normal login response plus identity token → window.orkata.identify() → Orkata. No additional endpoint is required. If the application restores long-lived sessions without running login again, add a fresh identity token to its existing session-bootstrap or token-refresh response too. The browser receives the short-lived token but never the signing secret. Orkata verifies the signature, audience, issue time, expiry, maximum lifetime, and signed metadata before the profile can reach chat logs, Helpdesk, or the agent prompt. Invalid and expired tokens are rejected.

Existing browser-only integrations remain compatible during migration. Both legacy forms continue to work:

window.orkata.identify("customer-123", {
  name: "Ayu",
  email: "ayu@example.com",
  phone: "+62 812 3456 7890",
  metadata: { plan: "pro" }
});

window.orkata.identify({
  id: "customer-123",
  name: "Ayu",
  email: "ayu@example.com"
});

Orkata sanitizes and stores a legacy profile but labels it Unverified in Chat Logs and exports. The agent may use it for low-risk personalization, but it is not treated as proof of identity or authorization. A valid signed token is labeled Verified, takes precedence over legacy data, and can safely upgrade an existing unverified session without inheriting unsigned fields. Migrate legacy calls to signed tokens when practical; no flag or coordinated cutover is required.

Call window.orkata.removeUser() when the visitor signs out. Removing the current user clears the stored token, starts a fresh anonymous chat, and prevents the next visitor from seeing the identified visitor’s locally stored sessions; it does not delete historical chat logs. Rotating the signing secret immediately invalidates every token created with the previous secret.

Embedded chat

Use the iframe code when the complete conversation should remain visible inside a page. Give the container enough height and width for the transcript and message composer, and keep the generated title for accessibility.

Helpdesk escalation follows the same conversational flow on hosted pages, embedded chat, the chat bubble, Telegram, and WhatsApp. When a visitor agrees to human support and no identified email is available, the bot asks for the email in the conversation. The visitor replies in the normal composer; no separate contact form opens. The bot then validates the email, creates the ticket, and confirms its number and subject without repeating the address.

Telegram bot

Use the Telegram channel when visitors should be able to message the agent from a private Telegram chat.

1. Open @BotFather, run /newbot, and finish Telegram’s setup prompts.
2. Copy the bot token BotFather gives you.
3. In Publish → Telegram, paste the token and select Connect Telegram bot.
4. Open the bot from the connection panel and send a test message.

Use a dedicated Telegram bot for each Orkata agent. A Telegram bot can have only one active webhook, so connecting it to another service or agent replaces its current message destination. Orkata encrypts the bot token before storage and does not display it again.

Telegram conversations support private text chats and visitor attachments. Visitors can send JPEG, PNG, WebP, and text-selectable PDF files within the configured attachment limits when the agent’s plan, model, and attachment setting allow them. Each Telegram chat has separate history and uses the agent’s configured model, knowledge sources, actions, Helpdesk, and AI credits.

Custom Button actions with supported web or Telegram links render as native Telegram inline buttons. Collect data actions configured for conversational collection gather and submit their fields in chat; rendered forms remain unavailable. When a Telegram visitor agrees to Helpdesk escalation, the bot asks for their email in the conversation, submits the ticket without opening a form, and confirms the ticket number and subject. Later visitor messages are added to the active ticket. Helpdesk agents can reply with text and supported image or PDF attachments, which are delivered back to the same Telegram chat while the bot remains connected.

Turn off Channel availability to pause inbound messages and Helpdesk replies without removing the bot token or webhook. Turn it back on to resume the same connection. Disconnecting removes the Orkata webhook and stored connection while preserving existing chat logs. If a token may have been exposed, revoke it with BotFather as well.

WhatsApp Cloud API

Use the WhatsApp channel to receive and answer customer messages through a Meta WhatsApp Business Account. Connect the account from Publish → WhatsApp, register the generated callback URL and verify token in Meta, subscribe the messages webhook field, and activate the webhook in Orkata.

WhatsApp conversations use the agent’s configured model, knowledge sources, supported actions, Helpdesk, conversation logs, and AI credits. When attachments are enabled for the agent, visitors can send JPEG or PNG images and text-selectable PDFs for AI analysis. Orkata validates and stores these files with the conversation under the same 5 MB file and five-page PDF limits used by other chat surfaces.

Collect data actions configured for conversational collection can ask for and submit their fields in WhatsApp. Rendered forms remain available only on web chat surfaces.

When a visitor asks for human support, the bot collects their email in chat, creates a Helpdesk ticket, and routes later text, image, and PDF messages into that ticket. Helpdesk agents can send text, JPEG or PNG images, and PDFs back to the same WhatsApp conversation. Files remain limited to two per message and 5 MB each; WhatsApp does not accept WebP images through this workflow.

Meta permits free-form agent replies during the rolling 24-hour customer-support window opened by a visitor message. Outside that window, an approved WhatsApp message template is required; Orkata reports the failed delivery in the Helpdesk ticket composer. Use a long-lived system-user access token for a durable production connection.

Turn off Channel availability to pause inbound messages and Helpdesk replies while keeping the Meta callback, access token, and connection details. Turn it back on to resume without reconnecting. Use Disconnect WhatsApp only when the stored connection should be removed.

Before going live

Confirm the access mode, test the most important questions, review actions that can send data outside Orkata, and provide visitors with the notices and human-support path appropriate to your use case.

Next step

After visitors begin using the agent, review Analytics and Chat Logs.