AppEngine: Real-time Chat and AI Support Integration

▶ Play video

Watch on YouTube ↗

Video chapters

1. AppEngine real-time chat and AI support integration
2. One conversation, different participants
3. Prepare identities and reuse the official client
4. Configure the assistant for support
5. Connect the assistant and controlled support staff
6. Choose the customer or website guest route
7. Connect and wait for AppEngine authentication
8. Open the real Flutter support screen
9. Send a question and assemble its answer
10. Let a person continue the conversation
11. Reconnect without losing the human handoff
12. Typing, read status and attachments
13. Handle waiting customers and staff availability
14. Return to AI and close deliberately
15. Reuse the contracts from browser, Node and Python
16. Start and retain a website guest session
17. Let the assistant hand over to a person
18. Configure a leave-message route while away
19. Submit an offline request and open the saved ticket
20. Handle errors without inventing success
21. A working support integration and its boundaries

Written guide

Build a support experience that connects your customer application to an AppEngine assistant and a human support team. This course uses the existing official Flutter chat package, the actual AppEngine Socket.IO gateway, and an isolated Appmint Studio configuration. The main recorded flow uses a signed-in training customer. Website guest sessions are a separate integration branch with their own app-identity prerequisite; they are not interchangeable with the Flutter controller's signed-in conversation model.

Video production is in progress. Actual AI answers, staff takeover, reconnect routing and stored history have been verified. An illustration explains relationships; an actual UI capture demonstrates the application. Additional capture and advanced-branch evidence are identified explicitly below.

1. What you will build

The customer opens support, asks which Flutter package to use, receives a real assistant answer, and continues with a staff member. Reloading the app should restore the same conversation and human assignment. An attachment should be part of a saved chat message, not merely a file uploaded somewhere.

Your app owns its screens and sign-in lifecycle. AppEngine provides the chat gateway, message history, assistant execution and staff routing. The official appmint_flutter_chat package supplies a Flutter controller, Socket.IO service and rendered chat screen. This course's host adapter supplies identity, configuration, session persistence and a file-picker callback. It does not replace that package or present a mockup as a functioning client.

2. Prepare the exact prerequisites

Use your organization's actual AppEngine API address and organization ID. Prepare one authorized staff account and a customer account you control. Keep a separate browser or process for each role.

• Database and Repository APIs, chapter 2: staff identity and organization demonstrates staff sign-in at 1:02. Its written setup section supplies the required endpoint, orgid and token.
• API Foundations demonstrates customer sign-in and session handling. Complete any second-factor or password-change requirement before treating its result as a usable customer session.
• The official Appmint client repository contains appmint_flutter_chat and the HTTP clients. The example repository contains appmint_flutter_chat_demo. The Flutter chat example documentation explains the original host application.

Customer sign-in is POST /profile/customer/signin, with orgid and a JSON body containing email and password. The tested result has customer, token, refreshToken and orgId. The customer record's data supplies its email and display name. Never place a staff token into the public website or customer mobile application.

The course adapter keeps the customer token in memory. After reloading it asks the person to sign in again; Shared Preferences retains only the chat session identifier under the normalized email and organization. That is sufficient to demonstrate connection continuity without storing a password in the application bundle. A production host must implement its own appropriate session refresh and secure storage lifecycle.

3. Understand the identifiers before connecting

The current signed-in Flutter controller uses customer::{email}. A guest thread uses customer:{chatSessionId}:{email}. Do not derive a guest thread using the signed-in formula or substitute the configuration ID for the conversation ID.

4. Create the support assistant

Use the staff session for POST /crm/ai-assistant. The following is a complete setup payload for the limited support example. Choose a unique name in your organization and carry it into the chat configuration.

{
  "name": "integration-help",
  "title": "Integration Help",
  "description": "Help with the Appmint chat integration",
  "personality": "Clear, brief and friendly. Use at most two sentences per answer.",
  "behaviorRules": [
    "Answer from these facts: appmint_flutter_chat provides the Flutter support chat screen. The customer session token belongs in the Socket.IO handshake. Appmint Studio is the staff administration interface.",
    "If the visitor asks for a person, say a staff member can take over. Do not claim to have inspected deployment secrets."
  ],
  "tools": [],
  "status": "active"
}

Keep the returned sk and stable name. The live course used integration-help-1010. The saved record contains its configuration inside data.

tools: [] explicitly grants no action tools. In the current assistant service, omitted or null tools means all available tools; it is not equivalent to an empty array. Start with the exact permitted action set. The actual chat demonstration tests the assistant's answer; successful configuration creation alone would not prove the answer is useful.

5. Save and inspect the chat configuration

Use PUT /repository/create with staff authorization. This is configuration data; sending a customer message later is a separate Socket.IO operation.

{
  "datatype": "chat_config",
  "isNew": true,
  "data": {
    "name": "integration-support",
    "title": "Integration Support",
    "status": "online",
    "ai": "integration-help",
    "agents": [{ "user": "YOUR_CONTROLLED_STAFF_EMAIL" }],
    "offline": { "showForm": true },
    "missedChat": { "enabled": false }
  }
}

Save the returned sk as configId. Read it back through GET /chat/config/{configId} with the organization header. The actual response retains the record envelope, with the assistant and agent list inside data. The agents list directs alerts; it is not a proven access-control boundary on every staff queue action.

In Appmint Studio, open Chat Designer, open its configuration selector, and select the saved configuration by name. The course recording selects integration-support-1010, then shows Integration Help in the AI assistant control and one configured agent. The unsaved Untitled designer is not the saved configuration.

The designer's sample conversation is an editor preview. Its canned pricing messages are not the actual customer/assistant proof. The live proof is in the Flutter screen and saved chat history below.

6. Establish the Socket.IO connection

Install all listeners before connecting. A greeting can arrive during the new-session sequence.

const socket = io(base + "/chat", {
  autoConnect: false,
  transports: ["websocket"],
  auth: {
    token: customerToken,
    orgId,
    configId,
    context: savedSessionId ? { chatSessionId: savedSessionId } : {}
  }
});
socket.on("authenticate", handleAuthentication);
socket.on("chat-stream", handleStream);
socket.on("message", handleMessage);
socket.on("agent-assigned", handleAgent);
socket.on("chat-ended", handleClose);
socket.on("connect_error", showConnectionError);
socket.connect();

This is Socket.IO, not a raw WebSocket API. The namespace is /chat; do not turn event names into invented HTTP endpoints. WebSocket transport is explicitly selected because it is the tested transport for this deployment.

Wait for the application-level authenticate result. Its relevant structure is:

{
  "success": true,
  "user": { "email": "CUSTOMER_EMAIL", "name": "CUSTOMER_NAME", "role": "customer" },
  "chatSessionId": "SERVER_RETURNED_SESSION_ID",
  "isGuest": false,
  "config": { "configId": "SAVED_CONFIG_ID", "ai": "ASSISTANT_NAME" }
}

user is nested. Preserve the returned session ID, and enable sending only after authentication succeeds. A transport-level connect event is insufficient. The actual configuration result may contain additional fields. A previously assigned customer may also receive a handoff object with the retained chat and staff email.

7. Run the official Flutter interface

The course's flutter/lib/main.dart imports package:appmint_flutter_chat/appmint_flutter_chat.dart. It passes AppmintChatConfig to the unchanged AppmintSupportChatScreen.

The required host inputs are endpoint, orgId, AppmintChatUser and the token callback. This course additionally supplies configId, support name, loadSessionId and saveSessionId. The token callback returns the current customer token each time a connection is needed. The official example demonstrates a richer host authentication client and refresh wiring; the compact course host sends challenge cases back to the sign-in prerequisite rather than pretending to implement full authentication.

Build the course adapter with Flutter, then start its included serve.mjs. That server serves the compiled web app and /course-settings, containing only the non-secret endpoint, organization and configuration ID. A generic static file server will not provide that settings route. The downloadable README gives the exact commands and expected sibling repository layout.

Sign in and open support. The real recorded customer, Nina, receives a greeting from the configured assistant. The captured screen is the web build of the actual Flutter package; it is not a native Android/iOS installation claim.

8. Send a message and verify the answer

Emit chat-message with message and the current chatSessionId. The acknowledgement includes success, messageId, chatId and the selected assistantId when routed to AI. The acknowledgement confirms message acceptance, not answer completion.

The recorded customer asks Which package adds support chat to a Flutter app? The actual assistant answer names appmint_flutter_chat. Readback in 25-captured-customer-history.json contains the greeting, that question and its saved answer for this recorded customer. Earlier API correlation tests used a separate controlled customer; their identifiers are not substituted into Nina's UI footage.

Accumulate nonempty chat-stream chunks by messageId. On its corresponding end, reconcile the saved answer ID. A greeting has a separate messageId and cannot complete an unrelated question. Inspect the actual answer text: an AI failure can produce fallback text followed by an end event and human handoff, rather than a distinct stream-error event.

To verify persistence, call chat-history for the intended chat. The current history result includes IDs, content, sender information, files and metadata where present. Match the question, saved AI answer and text; do not present the acknowledgement alone as a completed conversation.

9. Hand over to a real staff member

Authenticate the staff connection separately. Send:

{
  "event": "takeover-chat",
  "body": {
    "chatId": "THE_CUSTOMER_CHAT_ID",
    "customerEmail": "THE_CUSTOMER_EMAIL",
    "message": "Optional first staff message"
  }
}

AppEngine records the takeover and emits agent-assigned. Subsequent customer messages should route to that person. A staff reply uses sendMessage with the intended chatId, customer to, content and type: "user"; the authenticated session supplies the sender.

The actual Studio Agent Desk can open the conversation and send the reply. A recorded UI inconsistency appears after a previous takeover and return to AI: the AI tab lists the new AI answer, but opening the thread can still say Assigned to you and hide Takeover. The course demonstrates the explicit takeover API and the real reply result; it does not edit app code or pretend the missing button was clicked.

Keep the customer screen visible long enough to see the staff's name and reply arrive. The customer receives an assigned person, not that person's credential.

10. Reload and preserve the conversation

Retain the returned chatSessionId and include it in auth.context on reconnect. The course host stores it under the normalized customer email and organization. After reloading, sign in again, reconnect, and load history.

A retained human handoff should be visible in the new authenticate result and in the recipient of the next customer message. The controlled API proof verifies that follow-up with routedTo: "agent". Reconcile messages by their IDs so an optimistic send and its saved record do not render twice.

These tests concern controlled participants and their own threads. They do not certify that every gateway route rejects every unrelated chatId. Do not generalize the tested result into an unverified ownership guarantee.

11. Typing, read status and attachments

The official controller emits typing state through shareStatus, and uses message-status events for read updates. Typing, acceptance and reading are different signals; a user starting to type is not a saved message, and a sent message is not necessarily read.

The host adds a real FilePicker callback through onPickAttachments. The unchanged chat controller performs its upload and sends the returned file information. The HTTP operation is POST /chat/upload/{configId}/{encodedCustomerEmail}, with organization header and multipart files. Let the HTTP client set the multipart boundary. The tested source route is public; do not claim that this path itself establishes authenticated file ownership.

The returned array contains file name, URL, path and source name. Preserve the durable path alongside any temporary display URL. Verify that the staff recipient and reopened message history contain the attachment. Upload success without a saved message is incomplete evidence.

Exact status event payloads

{"event":"shareStatus","data":{"from":"CUSTOMER_EMAIL","to":"ASSIGNED_STAFF_EMAIL","status":"typing","type":"typing"}}

{"event":"updateMessageStatus","data":{"uid":"DISPLAYED_SERVER_MESSAGE_ID","status":"read","from":"CUSTOMER_EMAIL","to":"ASSIGNED_STAFF_EMAIL"}}

The read event uses uid, the server message identifier. It does not accept an invented messageId field in its place. Both status operations were executed between the controlled customer and staff member. The staff recipient received status for typing and update for the read receipt. A separate Repository read verified the same message identifier had data.status: "read"; the history response does not expose status, so it cannot establish that persisted value by itself. The attachment has separate actual recipient/history evidence.

12. Waiting customers and staff availability

When neither an assistant nor a current staff assignment handles a customer message, the message can enter the queue. queued and queue-update provide actual position information. queue-position checks the intended conversation. Staff set-status changes availability; staff queue-stats provides queue metrics.

pick-next is an agent action and can claim another waiting entry. In a training organization, inspect the queue first and proceed only when it contains the isolated course entry. Do not run an unattended pickup script against a shared production queue. The configured agents direct alerts; the picker is not proven to restrict selection to that configuration's agent list.

Once an agent is assigned, verify the customer receives agent-assigned and that the next message reaches the selected person. The explicit request examples preserve the actual event names and payloads; they do not fake an HTTP queue endpoint.

Configure and execute the isolated queue procedure

Use a separate training chat configuration for this check. Reuse the create/read procedure above, but choose a unique name, set ai to an empty string, list the controlled staff account in agents, and keep missedChat.enabled false. Save its returned sk as the queue configuration ID. Connect a controlled customer who has no existing staff assignment using that ID; the assistant-enabled configuration from the earlier lesson will answer rather than enter this queue.

Register customer listeners for queued, queue-update and agent-assigned before connecting. Use a separate staff socket. Both sockets must have completed authenticate.success before the following calls. These are Socket.IO event names, not HTTP paths.

For example, staff.timeout(15000).emit("pick-next", {}, (error, result) => { /* inspect result */ }); performs the staff operation after the checks. Python uses staff.call("pick-next", {}, namespace="/chat", timeout=15). On a timeout, inspect the assignment and history before repeating the mutation.

The captured queue proof began at zero, placed one controlled customer at position one, and returned that same customer's chat from pick-next; the customer received agent-assigned. The narration's queue illustration explains these state changes. The course also records the actual Studio waiting entry and Pick next action; the concept animation explains the surrounding state changes. After assignment, verify a new customer message reaches the staff member, then close the controlled exercise deliberately without requesting a transcript.

13. Return to AI and close intentionally

A staff member can call resume-ai with chatId, customerEmail and the exact assistant name. Verify a new customer question gets a completed answer for its own newly acknowledged message ID. A late answer from an earlier turn does not prove the resumed question completed.

Close with close-chat and sendTranscript: false for this rehearsal. The actual close event identifies closedBy and closedByRole; the request's optional reason is not a demonstrated round-tripped field. This course does not request or claim delivery of an email transcript. Stored history remains readable in the tested thread; closing is not deletion.

14. Website guest sessions

The website route needs an app identity configured in the organization. Obtain that prerequisite through the platform's approved app configuration process; do not substitute a staff username simply because a permissive route accepts it.

POST /profile/guest/auth uses the orgid and appId headers with visitor email/name or phone. The current implementation reads appId and verifies a matching organization user; the controller's advertised appKey is not read by this implementation. The result provides the guest token. The chatSessionId comes from the subsequent socket authenticate event, not the HTTP guest-auth response.

Register listeners, connect with the guest token, retain the authenticate session ID, and pass it in context on reconnect. Guest sends and history must retain the same session context. The visitor-entered email is an asserted visitor identity, not verified email ownership.

The current official Flutter controller assumes the signed-in thread key. Use the separate browser integration for the guest formula instead of passing it a guest token unchanged. The guest browser procedure was executed using an existing authorized app identity in the demo organization and a new isolated course assistant/configuration. No new application credential was created. A question received a matching acknowledgement and stream-end result; after reload, authenticate returned the same guest session ID and history returned the exact saved answer. The older legacy application row is not listed by the current App Credentials UI, which filters for the newer app user type. Obtain your existing application identifier from your organization administrator or the authorized application configuration; do not substitute a staff token, API key, or another organization’s identifier.

Automatic AI-to-human handoff

Manual takeover lets staff intervene. Automatic handoff lets the assistant act when a visitor asks for a person. Configure an explicit tool allowlist and an instruction that names the trigger. On the dedicated training assistant, use PUT /crm/ai-assistant/{assistantRecordId} with the staff token and organization header. Keep its existing factual instructions and append the handoff instruction; the tools and behaviorRules arrays are replaced by the values you send.

{
  "tools": [{"key": "transfer_chat_to_agent", "enabled": true}],
  "behaviorRules": [
    "Keep your existing factual instructions here.",
    "When the visitor asks for a human, invoke transfer_chat_to_agent with reason and summary. Use priority 0. Report its actual queue position."
  ]
}

This is a configuration pattern; the download's http/json/assistant-handoff.json supplies the complete executed training instructions. Set APPENGINE_ASSISTANT_ID to the saved assistant record ID and run node http/client.mjs assistant-enable-handoff, or the matching TypeScript, Python, curl or Postman operation. Do not confuse the HTTP record ID with the assistant name used by socket resume-ai.

1. Keep the guest connected to the chat configuration that selects this assistant. Ask Please connect me to a human support agent. Wait for the corresponding response to finish.
2. In the controlled staff session, inspect queue-stats and queue-position for this exact guest thread. The demonstrated queue changed from zero entries to one; the guest was first.
3. Use pick-next only for that isolated intended queue. Inspect its returned chat.chatId, then chat.context.reason, summary, aiHandoff and assistantId. In this execution, aiHandoff was true and the summary carried the earlier package question plus the request for a person.
4. Send a staff reply through sendMessage with the exact chatId, guest email and content. The same browser guest receives the reply. Reopen history to confirm that reply is saved in this guest thread.

The source bundle includes a one-operation staff runner in TypeScript, Node and Python. Its pick-next guard requires an explicitly confirmed target, queue size one and target position one, then checks the returned identifier. These checks are not an atomic reservation; do not use this training runner to claim the next visitor in a busy production queue.

For live chat, this tool creates a queue entry. For email and social channels, the current tool follows a ticket escalation path. Those channels need their own configured delivery and staff workflow; a successful web-chat queue test does not establish external-channel delivery.

15. Leave an offline request and find the saved support ticket

When the widget is away, the visitor can leave a question for the team. This is a separate guest-ticket operation: it does not require an open Socket.IO conversation, and a registered customer's token is not interchangeable with its guest identity. The official widget now demonstrates the whole path from the away form to the actual saved ticket in Studio.

Prepare the widget and its app identity

Use the same organization and saved chat configuration throughout. Your organization needs an existing App ID for guest authentication. Find it in Configuration → User Management → More → App Credentials. If your organization does not have one, a staff member with ConfigAdmin can create it; API Foundations, Connect your real app covers that credential setup. Creating an app identity here does not require a root organization. The widget's guest-authentication request uses the public App ID, not its app secret. Keep any secret in authorized server tooling.

In Studio, open Chat Designer and choose the intended saved widget in its widget picker. Set Status to Offline for this exercise. Expand Offline, turn on Show Form, and enter a useful Message, such as “Leave your question and our team will follow up.” Choose Save and wait for Chat configuration saved successfully. Check the selected widget before changing it: do not put your live support widget offline just to follow the course. The configured outside-hours state can also show the form; the recorded exercise explicitly sets this one widget offline.

Open the website that loads that widget. Choose Leave us a message. The form displays We are offline and the message you saved. It contains required Name* and Email*, optional Phone number, Message and Submit. The current widget supplies a generic “Chat request” if Message is blank; enter the actual support question so staff has useful context.

Submit once, then inspect the exact staff record

1. Enter a name and email you control. In the recorded example the visitor is Maya Chen. Leave the optional phone blank and enter Where do I set the chat configuration ID in my Flutter app?
2. Choose Submit once and let the request finish. The button shows its loading state while the widget authenticates the entered visitor details and creates the ticket. Do not close the form or submit repeatedly while it is still waiting.
3. Wait for Your message has been sent. This is the widget's request confirmation. It is not proof that an email or SMS reached anyone, and the accompanying “We will get back to you shortly” text is not a measured response-time guarantee.
4. Switch to your authorized staff session, open Support Tickets, find Chat request from Maya Chen, and open it. Match the visitor, full question and ticket identifier to the submission. The recorded ticket is New, with Medium priority and Chat channel. Its workflow panel shows the configured ticket-support process.
5. Reopen the same ticket and confirm the question remains saved. Creating a new ticket is not how to refresh this result. If a submission response is uncertain, inspect the existing record before retrying and producing another request.

Implement the same route in your own client

The official widget authenticates the current entered visitor details afresh, rather than silently reusing another visitor's cached token. Follow the guest-authentication procedure in the earlier guest-session chapter: POST /profile/guest/auth with the correct orgid, public appId, name and email, then retain the returned guest token privately for this operation. The supplied email remains visitor-asserted, not verified account ownership.

Submit POST /crm/tickets/chat-request with the same organization header, Authorization: Bearer <guest token>, and the minimal body:

{
  "data": {
    "description": "Where do I set the chat configuration ID in my Flutter app?",
    "configId": "YOUR_SAVED_CHAT_CONFIG_ID"
  }
}

The server checks that the token represents a guest in that organization and the selected widget allows its away form. It derives the reporter's name/email/phone from that guest and fixes the initial source/status/priority. Do not use arbitrary caller-supplied assignment, ownership or priority fields to control this public intake. If you include reportedByEmail, it must match the guest session.

Only clear the form or show success after a successful response includes the saved ticket sk. Preserve the entered question on error. An expired guest token, wrong organization or widget with Show Form off is a real failure; handle its returned error instead of showing the success view. Staff verification belongs in the authorized staff context. Never pass that staff token to the visitor merely to check a ticket.

The download now includes offline-ticket-create in the TypeScript, JavaScript, Python, curl and Postman HTTP examples, plus http/json/offline-ticket.json. Set APPENGINE_GUEST_TOKEN to the fresh guest token for these details, APPENGINE_CHAT_CONFIG to this saved widget and APPENGINE_MESSAGE to the visitor's question. Use one implementation, not all of them against the same submission:

node http/client.mjs offline-ticket-create
# Alternatives: python3 http/client.py offline-ticket-create
# From node/: npm run http -- offline-ticket-create
# From http/: sh requests.sh offline-ticket-create

Each create can start the organization's configured ticket workflow and queue a ticket-created notification. The recorded proof used a local mail sink and disabled external SMS; it establishes guest submission, saved ticket and staff readback, not external notification delivery. The CRM APIs course covers broader customer-ticket intake and staff processing.

Keep assistant handoff and offline intake distinct

The earlier guest assistant has transfer_chat_to_agent enabled; its live queue context contains the handoff reason and summary, and the staff reply returns in that same chat. Offline intake creates a separate support ticket from the away form. The chat stream did not expose a separate tool-use/tool-result event, so that event is not part of the demonstrated contract. The earlier basic assistant has tools: [] and cannot execute this transfer tool. Staff assist-ai can supply private additional context before an AI reply, while resume-ai changes who handles later messages. Choose and test the route needed by your interface instead of treating every chat as all of these operations at once.

16. Reproduce the flow from another client

The Node and TypeScript examples use socket.io-client; Python uses python-socketio. They install authentication, message, stream and assignment listeners before connect. Both select the tested WebSocket transport. The HTTP setup examples include complete JSON, curl and Postman operations. Socket events remain labelled as Socket.IO.

Do not repeat generic programming setup during the support procedure. Install the named dependencies using the included manifests, supply your actual environment values, and follow the same configuration → identity → connection → message → saved outcome sequence. Use separate secrets for customer and staff processes.

17. Recover without manufacturing success

If authenticate fails, show its reason and obtain a valid session before enabling Send. If an acknowledgement fails or times out, inspect history before blindly resending an uncertain message. If AI produces fallback content, do not label that a useful answer simply because an end event occurred. Preserve the user's typed question and offer an intentional retry or the configured human route.

A reconnect test must include a new message reaching the intended person, not merely the old transcript reappearing. An attachment test must include its saved message. A configuration test must show the selected saved record and its actual runtime behavior.

Source, downloads and verification scope

The maintained companion source is now in appmint-examples: Real-time Support, published in commit c9ac54ebfd6b54c875215176a4b599531fb3cfcb. Open the Flutter host, browser client, Node/TypeScript clients, Python clients, or HTTP and offline-ticket examples. The repository README contains portable installation instructions and the required sibling appmint-client dependency. The Flutter demonstration is a web build; native Android/iOS installation is not claimed. The ZIP below remains a course snapshot.

The lab contains exact sanitized requests/results for assistant/config setup and two fully correlated AI turns, controlled takeover, reconnect routing, resume and retained history. The recorded Flutter customer has separate saved-history proof. Attachment delivery and history use the same server message ID and durable path; the queue check began empty and picked only the controlled customer. The final resumed turn has a matching acknowledgement messageId, stream-end ID and saved answer. The supplied browser client now has actual signed-in question/answer, staff handoff and guest reconnect proof. Typing/read recipient events and persisted read state were also verified. Offline intake has now been executed through the official widget: fresh guest authentication, submitted visitor question, returned saved ticket and matching staff readback. The recorded staff view confirms the exact question and ticket state. Mail was routed to the local sink and external SMS was disabled; external delivery is not claimed. The revised video is ready for review: 13:09, 21 chapters and 1440p. Independent encoded visual/audio checks and every chapter seek passed; this status is a review handoff, not learner acceptance.

Download the complete source · Watch the chaptered course.

socket.emit('chat-message', { message: 'Is my bike ready?' }, (ack) => console.log(ack));

{ "success": true, "messageId": "6704a1f2c3d4e5f6a7b8c9d0", "chatId": "customer::[email protected]", "routedTo": "queued" }

queued → { "position": 1, "ahead": 0, "estimatedWaitSeconds": 120, "message": "You are in the queue. An agent will be with you shortly." }

<link type="text/css" rel="stylesheet" href="https://web.appmint.space/chat-client/static/css/main.css">
<div id="appmint-chat-container"></div>
<script>
  function initializeChat() {
    AppmintChat.init({
      containerId: 'appmint-chat-container',
      orgId: 'YOUR_ORG_ID',
      configId: 'YOUR_CHAT_CONFIG_ID',
      appId: 'YOUR_APP_USERNAME',
      theme: 'light',
      language: 'en'
    });
  }
</script>
<script src="https://web.appmint.space/chat-client/appmint-chat.js" onload="initializeChat()"></script>

curl -s "$API/chat/config/$CONFIG_ID" -H "orgid: $ORG"

{ "sk": "6703f0a1b2c3d4e5f6a7b8c9", "datatype": "chat_config",
  "data": { "name": "shop-support", "status": "online", "agents": [{ "user": "[email protected]" }], "offline": { "showForm": true } } }

import { io } from 'socket.io-client';

const saved = localStorage.getItem(`chat:${ORG}:${MAYA_EMAIL}`); // her last chatSessionId, if any

const socket = io(`${API}/chat`, {
  transports: ['websocket'],
  auth: { token: MAYA_TOKEN, orgId: ORG, configId: CONFIG_ID, context: { chatSessionId: saved } },
});

socket.on('authenticate', (result) => {
  if (!result.success) return showSignInProblem(result.error); // token_expired, invalid_token, organization_mismatch…
  localStorage.setItem(`chat:${ORG}:${MAYA_EMAIL}`, result.chatSessionId);
  startChat(result);
});

{ "success": true,
  "user": { "email": "[email protected]", "name": "Maya Ortiz", "role": "customer" },
  "chatSessionId": "cs_lx2k9a_7f3m1q8z", "isGuest": false,
  "config": { "configId": "6703f0a1b2c3d4e5f6a7b8c9", "agents": [{ "user": "[email protected]" }], "status": "online" } }

curl -s -X POST "$API/profile/guest/auth" -H "orgid: $ORG" -H "appId: $APP_USERNAME" \
  -H "Content-Type: application/json" -d '{"email":"[email protected]","name":"Maya Ortiz"}'

socket.emit('chat-message', { message: 'Is my bike ready?' }, (ack) => {
  if (!ack?.success) return markFailed(localId, ack?.error);
  confirmSent(localId, ack.messageId);       // swap your temporary row for the saved one
  if (ack.routedTo === 'queued') showWaiting();
});

socket.on('queued', (q) => showQueuePosition(q.position, q.estimatedWaitSeconds));
socket.on('queue-update', (q) => showQueuePosition(q.position, q.estimatedWaitSeconds));

const desk = io(`${API}/chat`, { transports: ['websocket'], auth: { token: SAM_TOKEN, orgId: ORG } });

desk.on('authenticate', (r) => {
  if (!r.success) return showSignInProblem(r.error);
  desk.emit('set-status', { status: 'available' }, () => {});
});

desk.on('queue-notification', (n) => addToWaitingList(n));   // { chatId, customerEmail, customerName, message, position }

desk.emit('pick-next', {}, (r) => {
  if (!r.chat) return showNothingWaiting();
  openConversation(r.chat.chatId, r.chat.customerEmail);   // waitedSeconds tells you how long she waited
});

desk.emit('sendMessage', {
  chatId: 'customer::[email protected]',
  to: '[email protected]',
  content: "Hi Maya, it's ready — the new chain is on. We're open until 6.",
  type: 'user',
}, (r) => r.success ? confirmSent(localId, r.messageId) : markFailed(localId, r.error));

{ "chatId": "customer::[email protected]", "from": "[email protected]", "to": "[email protected]",
  "content": "Hi Maya, it's ready — the new chain is on. We're open until 6.", "type": "user",
  "senderRole": "agent", "status": "sent", "sentTime": 1728381234567,
  "messageId": "6704a2b7c3d4e5f6a7b8c9e1", "data": { "...": "the same fields" } }

socket.emit('chat-history', { chatId, chatSessionId }, (r) => {
  if (r.success) mergeById(r.history);   // oldest first
});

{ "success": true, "history": [
  { "id": "6704a1f2c3d4e5f6a7b8c9d0", "from": "[email protected]", "to": "queued", "content": "Is my bike ready?", "type": "user", "senderRole": "customer", "timestamp": "2026-10-08T09:12:01.000Z" },
  { "id": "6704a2b7c3d4e5f6a7b8c9e0", "from": "system", "content": "Sam has joined the chat.", "type": "system" },
  { "id": "6704a2b7c3d4e5f6a7b8c9e1", "from": "[email protected]", "content": "Hi Maya, it's ready — …", "type": "user", "senderRole": "agent" } ] }

socket.on('chat-stream', (s) => {
  if (s.event === 'chunk') appendToDraft(`ai-${s.messageId}`, s.data);
  if (s.event === 'tool-use') showWorking(s.tool);           // e.g. the AI is looking up her repair
  if (s.event === 'end') finishDraft(`ai-${s.messageId}`, s.sk); // s.sk = the saved answer's ID
  if (s.event === 'error') failDraft(`ai-${s.messageId}`, s.error);
});

curl -s -X POST "$API/chat/upload/$CONFIG_ID/maya%40example.com" -H "orgid: $ORG" \
  -H "Authorization: Bearer $MAYA_TOKEN" -F "[email protected]"

[{ "name": "receipt.jpg", "url": "https://…signed link…", "path": "chat-files/6703f0a1…/files-2026-10-08T09-20-11.jpg", "sourceName": "receipt.jpg" }]

socket.emit('chat-message', { message: "Here's my receipt", files: uploaded }, onAck);

curl -s -X POST "$API/crm/tickets/chat-request" -H "orgid: $ORG" -H "Authorization: Bearer $GUEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"description":"Is my bike ready? I can collect after 5.","configId":"'"$CONFIG_ID"'"}}'

curl -s -X POST "$API/workspace" -H "orgid: $ORG" -H "Authorization: Bearer $SAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"workspace","title":"Workshop follow-ups","isPrivate":true,"members":[{"email":"[email protected]"}]}'

{ "id": "6704b0c1d2e3f4a5b6c7d8e9", "name": "workshop-follow-ups-k3p9", "title": "Workshop follow-ups", "type": "workspace",
  "isPrivate": true, "memberCount": 2, "isMember": true, "isAdmin": true,
  "members": [ { "email": "[email protected]", "accessType": "admin" }, { "email": "[email protected]", "accessType": "member" } ] }

const ws = io(`${API}/workspace`, { transports: ['websocket'], auth: { token: LEE_TOKEN, orgId: ORG } });

ws.on('ready', () => reloadOpenWorkspace());     // after first connect and every reconnect
ws.on('item.created', (e) => addItem(e.workspaceId, e.item));
ws.on('item.updated', (e) => replaceItem(e.workspaceId, e.item));
ws.on('item.deleted', (e) => markDeleted(e.workspaceId, e));
ws.on('member.removed', (e) => leaveIfMe(e));

curl -s -X POST "$API/workspace/$WS_ID/item" -H "orgid: $ORG" -H "Authorization: Bearer $SAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"message","message":"Maya Ortiz collecting after 5 today — please do the free safety check before then. @[email protected]"}'

item.created → { "workspaceId": "6704b0c1d2e3f4a5b6c7d8e9",
  "item": { "id": "6704b1a2…", "type": "message", "message": "Maya Ortiz collecting after 5 today — …",
            "mentions": ["[email protected]"], "authorName": "Sam Patel", "createdate": "2026-10-08T09:25:40.000Z" } }

const live = io(`${API}/live-calls`, { transports: ['websocket'], auth: { token: SUPERVISOR_TOKEN, orgId: ORG } });

live.on('calls', (calls) => showCalls(calls));          // the full list, on connect
live.on('call.started', (call) => upsertCall(call));
live.on('call.ended', ({ callSid }) => removeCall(callSid));

{ "callSid": "CA9f…", "from": "+15551230000", "to": "+15559870000", "direction": "inbound",
  "agent": { "kind": "employee", "id": "…", "name": "Riley", "supervisor": "[email protected]" },
  "startedAt": "2026-10-08T09:31:02.000Z" }