SDK FAQ and troubleshooting

Common integration questions

• Can the web widget be anonymous? Yes. Web integrations may start anonymous and can attach a short-lived signed identity after host login. Native SDK integrations require a signed customer identity token before network operations.
• Does mobile render the web widget in a WebView? No. iOS, Android, Flutter, React Native, NativeScript and Capacitor present the shared native widget and native transport. Capacitor may still host the rest of the application UI in its normal WebView.
• What are the supported floors? iOS 15.1, Android API 26, Flutter 3.22.3 or later with Dart 3.4 through 3.x, React Native 0.76 through 0.87 with the New Architecture, NativeScript 8.9 through 9.x and Capacitor 6 through 8.
• Can I keep multiple active conversations in one client? No. One accountScope owns one active native session and durable outbox. Finish or reset the current session before starting another. Framework wrappers use logout when switching identities; direct native clients use resetSession and are then recreated for the next account.
• Does the public SDK stream AI tokens? No. The public API returns typed snapshots and wait-for-assistant results. Do not build a token-by-token UI from polling events.
• Do push and voice come with the base package? No. They are separate opt-in native capabilities with their own provider setup and permissions.

Map errors to the next safe action

Read the typed error code and preserve the request identity. network and rate-limited states can be retried under the SDK's rules while the widget may show a separate reconnecting loading state. session-expired requires a fresh token for the same account. field-invalid, payload-too-large and message-rejected require host or customer correction. idempotency-conflict means the host must investigate the original key rather than sending a new message.

import { DobroDeskSdkError } from "@dobrodesk/mobile-protocol";

try {
  await client.sendMessage(text, idempotencyKey);
} catch (error) {
  // These host functions render controls; they do not retry inside catch.
  if (!(error instanceof DobroDeskSdkError)) {
    showRecoverableSdkError(error);
    return;
  }
  switch (error.details.code) {
    case "network":
    case "rate-limited":
      showRetryControl();
      break;
    case "session-expired":
      showRefreshAndRetryControlForTheSameAccount();
      break;
    case "field-invalid":
    case "payload-too-large":
    case "message-rejected":
      showCorrection(error.details);
      break;
    case "idempotency-conflict":
      investigateOriginalRequest(error.details);
      break;
    default:
      showRecoverableSdkError(error);
  }
}

Check the host before opening a support request

1. Confirm that apiOrigin is an HTTPS origin without a path, query or credentials and that integrationId is the intended DobroDesk integration.
2. Confirm that the signed token is issued by the host backend for the current customer and that accountScope is stable for that customer only.
3. Confirm that the native presenter is called from a foreground screen and that the host did not mount a second client for the same account.
4. Confirm that a retry reuses the original idempotency key and that logout or reset was not called while the operation was merely offline.