Developer docs

Set up the website embed, Flutter Customer SDK and GreenChat support workspace.

Keep integration keys on your backend. Keep keys, access tokens and customer data out of client code, logs and error reports.

Getting started

What GreenChat does

GreenChat adds customer chat to websites and Flutter apps. Agents respond to authorized channels in a shared workspace. Customer identities and staff sign-in use separate authentication flows.

Apply and set up your organization

Submit an application and save its receipt. Check the result and onboarding instructions with that receipt. Follow the instructions to confirm your first owner so the platform team can register and activate the organization before you sign in.

Apply for access

Add staff and channels

An organization owner can add or invite agents in Staff management, create a web or app channel under Channels and grant reception access through Assign staff. Existing accounts may need to accept an invitation first.

Website embed

Create a web channel and allow origins

Open Channels in the organization workspace and create a web channel. Add each origin with its scheme, hostname and any non-default port. Configure a same-origin ticket endpoint on your site and enable the embed. Find the generated script and public key in Integration settings.

Load the generated script

Place the snippet from your channel on a trusted page. The example shows the attribute format; use the exact values generated for your channel. The public key is safe to include in the script.

HTML

<!-- Copy the generated snippet from your web channel. -->
<script async
  src="https://chat.greenchat.cn/embed/v1/loader.js"
  data-site="REPLACE_WITH_48_HEX_PUBLIC_KEY"
  data-bootstrap="/greenchat/bootstrap"></script>

Issue a ticket on your backend

The loader POSTs JSON with challenge, purpose and optional source_page_url to the same-origin data-bootstrap endpoint. Verify the origin and visitor against your own policy. Set source_origin from trusted server configuration and call the GreenChat endpoint below. On success, return ticket and purpose (create or resume) as JSON with Cache-Control: no-store. Keep the intake key on your backend.

HTTP

POST /api/v1/integration/sites/{publicKey}/embed-tickets
Authorization: Bearer <server-only intake key>
Content-Type: application/json

{
  "challenge": "<64 lowercase hex characters from the loader>",
  "purpose": "create",
  "source_origin": "https://your-site.example"
}

Check CSP and send a test message

Allow the chat host in script-src, style-src and frame-src for the loader, stylesheet and chat frame. Allow the same-origin ticket request in connect-src. If the frame-ancestors policy blocks your site, check the channel allowlist and proxy. Test from the actual HTTPS origin, then claim and reply in the workspace.

Flutter Customer SDK

Installation and requirements

The repository contains private package version 0.1.0 for Android and iOS. It requires Dart 3.8 and Flutter 3.32 or newer. Use an authorized checkout or a pinned private Git reference and run flutter pub get. Declare INTERNET on Android and NSPhotoLibraryUsageDescription for the iOS image picker.

YAML

dependencies:
  greenchat_customer_sdk:
    path: ../support-center/packages/greenchat_customer_sdk

Authenticate the customer on your backend

Create a customer integration for an app channel. Verify the signed-in host user on your backend and derive a stable external_user_id from that session. Forward client_instance_id, code_challenge and purpose from GreenChatAuthRequest.toJson() to the ticket API. Return ticket and integration_id to your app and parse them with GreenChatTicket.fromJson. Keep integration keys and server credentials out of all Flutter and JavaScript code.

HTTP

POST /api/v1/integration/customer-integrations/{integration}/tickets
Authorization: Bearer <server-only customer integration key>
Content-Type: application/json

{
  "external_user_id": "<stable ID from your verified host session>",
  "client_instance_id": "<from GreenChatAuthRequest>",
  "code_challenge": "<from GreenChatAuthRequest>",
  "purpose": "customer.authenticate"
}

Initialize the SDK and open chat

Initialize Flutter bindings and create one GreenChatClient. Give your authProvider a bounded timeout and forward request.cancelled. The SDK exchanges the ticket at /api/v1/customer-identity/exchange and keeps the bearer in memory. Place GreenChatChatPage in a bounded layout. Opening default chat does not create a consultation.

Dart

import 'package:flutter/material.dart';
import 'package:greenchat_customer_sdk/greenchat_customer_sdk.dart';

// Supply your application's authenticated backend adapter as hostTicketProvider.
GreenChatClient createSupportClient(GreenChatAuthProvider hostTicketProvider) {
  return GreenChatClient(GreenChatConfiguration(
    apiBaseUri: Uri.parse('https://api.greenchat.cn/api'),
    authProvider: hostTicketProvider,
  ));
}

Widget supportScreen(GreenChatClient client) => Scaffold(
  body: GreenChatChatPage(client: client, locale: GreenChatLocale.en),
);

Send messages and read history

The default screen handles text, JPEG, PNG and WebP images, and continuous chat for the current identity. For a custom screen use history, messages and sendText. Use a consultationId that the current customer is authorized to access.

Dart

final history = await client.history(limit: 20);
final operation = client.prepareText(consultationId, 'Hello support');
await client.sendText(operation); // Reuse operation if the result is uncertain.
final page = await client.messages(consultationId, afterId: 0);

Sign in, sign out and switch users

After host sign-in, call await client.authenticate() or let the chat screen authenticate. Call await client.logout() when signing out and clear the host session. On account changes, update the host session and call client.switchIdentity(authProvider: nextProvider). Discard drafts, image data and pending operations from the previous identity.

Workspace and staff app

Sign in and claim inquiries

Sign in to the organization workspace with your authorized staff account. Select the organization, open the waiting queue and claim an inquiry on a channel you can receive. Reply with text or a supported image, and open customer profiles or history where authorized. Legacy attachment access depends on the client and permissions.

Transfer, close and reopen

Transfer a conversation to an eligible colleague and follow the confirmation prompts. Close an inquiry when it is resolved. To continue the conversation, open it from the closed queue and use the reopen action when available.

Work from the staff app

Get the Android or iOS staff app through your organization. Sign in and select your organization. Live updates and background push depend on the client, server configuration and device permissions. Android push uses FCM and iOS uses APNs.

Troubleshooting

Missing launcher or blocked origin

Check that the web channel is enabled and the script URL and data-site match the generated snippet. Match the exact scheme, host and port in the allowlist. Inspect browser network and CSP errors for blocked scripts, stylesheets or frames.

Authentication errors, 401, 403 or 429

For 401, check for expired, revoked or missing credentials and follow the sign-in flow. For 403, check origin, organization and channel access and integration status. For a failed ticket exchange, request a fresh ticket and check the instance, challenge and purpose. Respect Retry-After on 429.

Stale messages or missing push

Check the network, selected organization and conversation. The SDK polls while foreground chat is visible. Live-enabled workspace clients can fall back to polling. For background push, verify FCM or APNs setup, device registration, notification permission and battery restrictions.

Contact