FigoAILabs API Documentation
    • Quickstart
    • Website Plugin
    • Mobile Plugin
    • Rate Limits & Pricing
    • FigoAI MCP Server Guide
    • FigoChat Mobile SDK
    • Figo Snap and Pay SDK
    • APIs
      • Chat Assistant API
        POST
      • Image Assistant API
        POST
      • Text To Speech API
        POST
      • Speech To Text API
        POST
      • Guardrails API
        POST
      • CV Scoring API
        POST
      • Web Search API
        POST
      • Sentiment Analysis API
        POST
      • Message Context API
        POST
      • Image Analyzer API
        POST
      • Upload Files With OCR
        POST
      • Extract Bank Account From Image
        POST
      • Check Assistant Health
        GET
    • Schemas
      • Sample Schemas
        • Pet
        • Category
        • Tag
      • Schemas
        • ApiKeyRequest
        • Assignee
        • AssistantRequest
        • AssistantTrainingRequest
        • AssistantTrainingRequestByUrl
        • CVScoringRequest
        • Cf
        • Change
        • ChangePasswordRequest
        • ChangePlanRequest
        • ChatRequest
        • ChatUser
        • CompanyEntityCreateRequest
        • CompanyEntityUpdateRequest
        • CompanyPreferenceUpdateRequest
        • ConfirmPasswordRequest
        • Contact
        • CreateUserRequest
        • CustomFields
        • CustomerContact
        • DescAttachment
        • Entry
        • FAQ
        • FBEntry
        • FBMessage
        • FBMessaging
        • FBRecipient
        • FBSendMessage
        • FBSender
        • FacebookReceiveMessageRequest
        • FacebookSendMessageRequest
        • FacebookSetupRequest
        • GoogleSignInRequest
        • GuardrailForAssistantRequest
        • GuardrailRequest
        • HallucinationTrack
        • IGEntry
        • IGMessage
        • IGMessaging
        • IGRecipient
        • IGSendMessage
        • IGSender
        • ImageChatRequest
        • ImageDefaultChatRequest
        • InstagramReceiveMessageRequest
        • InstagramSendMessageRequest
        • InstagramSetupRequest
        • LLMPoolRequest
        • LLMRequest
        • LayoutDetails
        • Message
        • MessageRequest
        • MessageRequestForWebSearch
        • Metadata
        • Payload
        • Profile
        • RefreshTokenRequest
        • RemitaPersonalSignInRequest
        • RemitaSignInRequest
        • RequestOTPRequest
        • ResetPasswordRequest
        • SaveAssistantFAQByTextRequest
        • SaveAssistantFAQByUrlRequest
        • SaveAssistantFAQRequest
        • SaveToolingAgentMapRequest
        • SaveToolingAgentRequest
        • SentimentValidationRequest
        • SignInRequest
        • SignUpRequest
        • TWDirectMessageEvent
        • TWMessageCreate
        • TWMessageData
        • TWTarget
        • TeamsLoginRequest
        • Text
        • TextToSpeechRequest
        • TransactionInitializeRequest
        • TwitterReceiveMessageRequest
        • TwitterSendMessageRequest
        • TwitterSetupRequest
        • UpdateAssistantFAQRequest
        • UpdateUserRequest
        • ValidateOTPRequest
        • Value
        • VerifyEmailRequest
        • WhatsAppReceiveMessageRequest
        • WhatsAppSendMessageRequest
        • WhatsAppSetupRequest
        • ZohoCreateTicketRequest
        • ZohoReceiveMessageRequest
        • ZohoReplyTicketRequest
        • ZohoSetupRequest
      • AssistantHealthResponse
      • FileUploadResponse
      • BankAccountExtractRequest
      • RateLimitResponse
      • BankAccountExtractResult
      • RawFile
      • LLMImage
      • StandardResponse

    FigoChat Mobile SDK

    The FigoChat SDK adds a ready-made AI chat screen to React Native, Flutter, Capacitor / Ionic (Angular, React, Vue), native Android and native iOS apps. Users can type, send voice notes and upload files (images are read with OCR). When a live agent takes over, the agent's replies appear in the same chat. The screen uses your brand color, and the conversation runs against your Figo AI assistant.
    PlatformPackageWhere
    React Native (Expo or bare)@figoailabs/figochat-react-nativenpm
    Flutter (iOS, Android, web*)figochatpub.dev
    Capacitor 8 / Ionic (Angular, React, Vue), iOS and Android@figoailabs/figochat-capacitornpm
    Android (Kotlin, Jetpack Compose), Android 8.0+com.github.figoailabs:figochat-androidGitHub, installed through JitPack
    iOS (Swift, SwiftUI and UIKit), iOS 16+FigoChat Swift packageGitHub, installed with Swift Package Manager
    * Voice notes are not available on Flutter web.
    Angular apps: use the Capacitor plugin. It works in Ionic Angular and in any Angular app wrapped with Capacitor, and opens the same native chat screen as the iOS and Android SDKs. The React Native package can't be used outside React Native.

    1. Before you start#

    You need three things, all from the FigoChat admin at app.figolabs.ai:
    1.
    An API key, which the SDK sends as Authorization: Bearer <apiKey>.
    2.
    An assistant ID: the AI chatbot your users will talk to.
    3.
    AI credits: the company needs at least 0.02 credits, or every call returns 401 Insufficient AI credits.

    Get an API key#

    1.
    Sign in to the FigoChat admin at app.figolabs.ai.
    2.
    In the sidebar, click API Keys.
    3.
    Click Create API Key, enter a name such as Mobile SDK, then click Create API Key in the window.
    4.
    Copy the key from the window that opens and store it somewhere safe, such as your secrets vault or CI variables.
    The key is shown only once. After you close the window, the list shows only a masked version (fg-key*************…). If you lose the key, create a new one.
    About API keys:
    Format: keys start with fg-key-.
    Scope: a key belongs to your company, and its usage is charged to the company's AI credits.
    Expiry: keys expire 3 years after they're created. Create a new key and ship it in an app update before then.
    Managing keys: the API Keys page lists each key's name, masked key, creator and creation date. You can rename a key with the edit button or delete it. Deleting a key immediately stops every app that uses it.

    Get the assistant ID#

    1.
    In the sidebar, click AI Chatbots.
    2.
    Open the chatbot your users should chat with.
    3.
    Next to Assistant ID, click the copy button.

    Check your AI credits#

    Every message, voice note and upload uses AI credits from the company's balance. Check the balance and top up under Billing in the sidebar.
    Security: the API key is shipped inside your app, so anyone who unpacks the app can read it and spend your credits. Create a key just for the SDK, so you can delete it without breaking your other integrations. If it leaks, delete it under API Keys and ship an update with a new key. For stronger protection, have your backend hand the key to the app after the user signs in, instead of building it into the app.

    2. Installation#

    React Native#

    Bare React Native apps (no Expo) must first run npx install-expo-modules@latest. @react-native-community/netinfo is needed for live agent messages.
    Microphone permission
    Expo (app.json):
    {
      "expo": {
        "plugins": [
          ["expo-audio", { "microphonePermission": "Allow $(PRODUCT_NAME) to record voice messages for chat." }]
        ]
      }
    }
    Bare iOS: add NSMicrophoneUsageDescription to Info.plist.
    Bare Android: add <uses-permission android:name="android.permission.RECORD_AUDIO" /> to AndroidManifest.xml.

    Flutter#

    or in pubspec.yaml:
    iOS (ios/Runner/Info.plist):
    <key>NSMicrophoneUsageDescription</key>
    <string>Record voice messages for chat.</string>
    Android (android/app/src/main/AndroidManifest.xml):
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.INTERNET" />
    <queries>
      <intent><action android:name="android.intent.action.VIEW" /><data android:scheme="https" /></intent>
    </queries>
    If pod install fails with an error mentioning XCLocalSwiftPackageReference, your CocoaPods is older than your Flutter's Swift Package Manager support. Update CocoaPods, or turn the integration off for the app in pubspec.yaml:

    Capacitor / Ionic (Angular, React, Vue)#

    The plugin runs the native iOS and Android SDKs, so it needs a few native settings.
    iOS
    1.
    In Xcode, set the app target's Minimum Deployments to iOS 16.0 or later (Capacitor's default is 15.0), then run npx cap sync ios again.
    2.
    Add to ios/App/App/Info.plist:
    <key>NSMicrophoneUsageDescription</key>
    <string>Record voice messages for chat.</string>
    The plugin needs Swift Package Manager, which is the default for new Capacitor 8 apps. If your iOS project still uses CocoaPods (there's a Podfile in ios/App), migrate it first with npx cap spm-migration-assistant.
    Android
    1.
    In android/variables.gradle, set minSdkVersion = 26.
    2.
    In android/build.gradle, add JitPack to allprojects.repositories:
    The chat doesn't run in a browser (ionic serve); calls there reject with UNIMPLEMENTED. Test on a simulator or device.

    Android (native)#

    The SDK is open source at github.com/figoailabs/figochat-android. Install it through JitPack, which builds it from the GitHub release tag:
    Building needs JDK 17.
    The module's manifest already declares the internet and microphone permissions and the chat screen. The microphone permission is requested the first time the user taps the mic.

    iOS (native)#

    The SDK is open source at github.com/figoailabs/figochat-ios. In Xcode, choose File → Add Package Dependencies…, enter https://github.com/figoailabs/figochat-ios, choose Up to Next Major Version from 1.1.0, and add the FigoChat library to your app target. In a Package.swift:
    Then add to Info.plist:
    <key>NSMicrophoneUsageDescription</key>
    <string>Record voice messages for chat.</string>

    3. Initialize#

    Call initialize once, for example right after the user signs in. Call it again whenever the user or the settings change.

    React Native#

    import { FigoChat } from '@figoailabs/figochat-react-native';
    
    FigoChat.initialize({
      apiKey: 'YOUR_API_KEY',
      assistantId: 'YOUR_ASSISTANT_ID',
      fullName: 'Ada Lovelace',
      emailAddress: 'ada@example.com',
      mobilePhone: '+2348012345678',
      primaryColor: '#F97316',
      // optional
      title: 'Support',
      welcomeMessage: 'Hi Ada! How can I help you today?',
    });

    Flutter#

    Capacitor / Ionic#

    import { FigoChat } from '@figoailabs/figochat-capacitor';
    
    await FigoChat.initialize({
      apiKey: 'YOUR_API_KEY',
      assistantId: 'YOUR_ASSISTANT_ID',
      fullName: 'Ada Lovelace',
      emailAddress: 'ada@example.com',
      mobilePhone: '+2348012345678',
      primaryColor: '#F97316',
      // optional
      title: 'Support',
      welcomeMessage: 'Hi Ada! How can I help you today?',
    });
    On Capacitor, initialize returns a promise that rejects with code CONFIG for bad parameters, and timeout is in milliseconds.

    Android (native)#

    iOS (native)#

    Parameters#

    ParameterTypeRequiredDefaultDescription
    apiKeystringYes–API key from API Keys in the FigoChat admin (see Before you start). Sent as Authorization: Bearer <apiKey>.
    assistantIdstringYes–Assistant the user chats with. Copy it from AI Chatbots → your chatbot → Assistant ID in the admin.
    fullNamestringYes–Signed-in user's full name.
    emailAddressstringYes–Signed-in user's email address.
    mobilePhonestringYes–Signed-in user's phone number in international format, e.g. +2348012345678.
    primaryColorstringYes–Brand color as hex (#RGB, #RRGGBB or #RRGGBBAA). Used for the header, the user's messages and the buttons. Text on top is black or white, whichever is easier to read.
    baseUrl (baseURL on iOS)string / URLNohttps://api.figolabs.aiAPI host.
    titlestringNoChatHeader title.
    welcomeMessagestringNo–First assistant message, shown before the user writes anything.
    threadIdstringNo–Resumes an earlier conversation. Use the value from getThreadId() / threadId.
    maxFilesnumberNo5Most files per message.
    maxFileSizeMBnumberNo10Largest file accepted.
    autoSendVoicebooleanNotruetrue sends the transcribed voice note right away; false puts the text in the input box so the user can edit it first.
    timeoutMs (RN), timeout (Flutter, iOS), timeoutMillis (Android)number / Duration / TimeIntervalNo120 sRequest timeout.
    initialize throws a CONFIG error if a required value is empty or primaryColor isn't a hex color.

    4. Show the chat screen#

    React Native#

    import { FigoChatView } from '@figoailabs/figochat-react-native';
    import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
    
    <Modal visible={open} animationType="slide" onRequestClose={() => setOpen(false)}>
      {/* a Modal is its own native window, so it needs its own SafeAreaProvider */}
      <SafeAreaProvider>
        <SafeAreaView style={{ flex: 1 }}>
          <FigoChatView onClose={() => setOpen(false)} />
        </SafeAreaView>
      </SafeAreaProvider>
    </Modal>
    Without the SafeAreaProvider inside the Modal, the header slides under the status bar on iPhones.
    PropTypeDefaultDescription
    onClose() => void–Shows a close button in the header.
    showHeaderbooleantrueHide the header if your app draws its own.
    placeholderstringType a messageInput placeholder.
    enableVoicebooleantrueShow the microphone button.
    enableAttachmentsbooleantrueShow the attach button.
    keyboardVerticalOffsetnumber0Extra space above the keyboard on iOS. Rarely needed: the screen already keeps the input just above the keyboard, including inside modals.
    iconsobject–Replace the built-in icons: send, attach, mic, stop, close, newChat.
    onError(e: FigoChatError) => void–Called for every error the screen shows (for logging).
    styleViewStyle–Container style.

    Flutter#

    ParameterTypeDefaultDescription
    onCloseVoidCallback?–Shows a close button in the header.
    showHeaderbooltrueHide the header if your app draws its own.
    placeholderStringType a messageInput placeholder.
    enableVoicebooltrueShow the microphone button (always off on web).
    enableAttachmentsbooltrueShow the attach button.
    onErrorvoid Function(FigoChatException)?–Called for every error the screen shows.

    Capacitor / Ionic#

    await FigoChat.open(); // opens the native chat screen full screen
    The chat has its own header with refresh and close buttons; closing it returns to your app.

    Android (native)#

    FigoChatScreen takes the same options as Flutter's FigoChatView (onClose, showHeader, placeholder, enableVoice, enableAttachments, onError), plus modifier.

    iOS (native)#

    FigoChatView takes onClose, showHeader, placeholder, enableVoice, enableAttachments and onError. FigoChatViewController is the UIKit container if you want to push it yourself.

    What the screen does#

    Text: type and send. A typing indicator shows while the assistant replies.
    Formatted replies: assistant replies arrive as HTML and are rendered as formatted text, drawn natively (no web view): bold, italics, underline, headings, bullet and numbered lists, line breaks and tappable links. Styling the bubble can't show (such as <span style> or fonts) is dropped and its text kept. Users never see tags or markdown symbols. What users type is always shown as typed.
    Voice: tap the microphone, speak, then tap stop. While the recording is turned into text the screen shows "Processing your voice message…", then the text is sent as a message (or placed in the input if autoSendVoice is false). Tap Cancel to discard the recording.
    Files: tap the paperclip to pick one or more files (on iPhone, native iOS and Flutter offer Photo library or Files). Each file uploads straight away and shows a progress chip. A file that fails is marked in red and can be removed. When the user sends, the files go with the message. If the user sends only files, the message says "Please review the attached file(s)."
    Errors: a message that fails shows "Not sent. Tap to retry", with a plain-language reason such as "Chat isn't available right now. Please try again later." Technical details (for example an invalid API key) are never shown to users; see Errors.
    Keyboard: the input stays just above the keyboard, and tapping the conversation closes the keyboard.
    Live agent: when the conversation is handed to a human agent (Tawk.to, Zoho SalesIQ or FreshChat), the agent's replies appear on the left, like assistant replies, as "Agent name says: …" (with the agent's name in bold). A notice also appears there when the agent leaves.
    New conversation: the refresh button in the header starts a new thread.
    Footer: a small "Powered by Figo AI Labs" line sits under the input bar. Tapping Figo AI Labs opens figolabs.ai in the browser.

    How live agent messages work#

    After the first reply, the screen subscribes to the conversation's realtime channel. It fetches the realtime settings from your API once per session and keeps them encrypted in memory with the SDK's FigoCrypto util (AES-256 with a random per-session key). They're decrypted only at the moment the channel is subscribed. The subscription stops when the chat closes or a new conversation starts.

    5. Other SDK calls#

    React NativeFlutter, Android, iOSDescription
    FigoChat.getThreadId()FigoChat.threadIdCurrent thread id. Save it to resume later with initialize({ threadId }).
    FigoChat.resetConversation()FigoChat.resetConversation()The next message starts a new thread.
    FigoChat.logout()FigoChat.logout()Clears the settings, e.g. when the user signs out.
    FigoChat.isInitialized()FigoChat.isInitializedWhether initialize has been called.
    FigoChat.getClient()FigoChat.clientThe API client, for building your own UI.
    new FigoCrypto()FigoCrypto()The encrypt/decrypt util, if you want to protect other values in memory: encrypt(text) and decrypt(value).
    friendlyMessage(error, context)friendlyMessage(error, context)The user-facing text for an error, as the chat screen shows it. context is chat, voice, recording or upload.
    htmlToText(html)htmlToText(html)A reply as plain text: tags and markdown removed, line breaks, • bullets and 1. numbers kept.
    htmlToRuns(html)htmlToRuns(html)A reply as styled runs (text, bold, italic, underline, link), for rendering it in your own UI the way the chat screen does.

    Events#

    Listen for messages to log them, run analytics or update your own UI. Both events give plain text:
    Message sent: fired when the API accepts the user's message. You get the text the user sent.
    Message received: fired for each assistant reply and each live agent message. You get the reply with its HTML stripped (htmlToText).
    Listeners can be added before initialize and stay registered after logout. An error thrown inside your listener never affects the chat.
    // React Native
    const sent = FigoChat.addListener('messageSent', (text) => analytics.track('chat_sent', { text }));
    const received = FigoChat.addListener('messageReceived', (text) => console.log('Assistant:', text));
    // later
    sent.remove();
    received.remove();
    // Capacitor / Ionic
    const sent = await FigoChat.addListener('messageSent', (e) => console.log('User:', e.text));
    const received = await FigoChat.addListener('messageReceived', (e) => console.log('Assistant:', e.text));
    // later
    await sent.remove();
    await received.remove();
    Capacitor calls: initialize, open, getThreadId() (resolves to { threadId }, or null before the first reply), resetConversation, logout, addListener and removeAllListeners. All of them return promises. Building your own UI isn't available on Capacitor; it always uses the native chat screen.

    Building your own UI#

    // React Native
    const client = FigoChat.getClient();
    const { answer, threadId } = await client.sendMessage('Hello', [/* uploaded file urls */]);
    const text = await client.transcribe({ uri, name: 'voice.m4a', mimeType: 'audio/mp4' });
    const urls = await client.uploadFiles([{ uri, name: 'receipt.jpg', mimeType: 'image/jpeg' }]);

    6. Errors#

    Every SDK call throws FigoChatError (React Native, iOS) or FigoChatException (Flutter, Android), each with a message and a code.

    What users see#

    The chat screen never shows the technical message to users. It shows plain-language text instead:
    SituationCodesMessage shown in the chat
    The chat can't work until you fix something (bad or expired key, no credits, plan limit, bad setup)401, 403, 49, CONFIG, NOT_INITIALIZEDChat isn't available right now. Please try again later.
    No connectionNETWORKYou seem to be offline. Check your internet connection and try again.
    Slow responseTIMEOUTThis is taking longer than usual. Please try again.
    Anything else, when sending a messageotherYour message couldn't be sent. Please try again.
    Anything else, with a voice messageotherWe couldn't process your voice message. Please try again.
    Anything else, when starting the microphoneotherThe microphone couldn't start. Please try again.
    Anything else, with a fileotherWe couldn't upload that file. Please try again.
    The full technical error still reaches onError, so log it there to find out why chat is unavailable. Apps with their own UI can call friendlyMessage(error) to get the same text.

    Error codes#

    codeMeaningWhat to do
    401Invalid or expired API key, missing header, or under 0.02 credits. The message gives the reason.Check the key and the credit balance.
    49The company's plan doesn't include this API.Upgrade the plan.
    99The API couldn't complete the request (e.g. a file failed to upload).Retry.
    TIMEOUTNo response within the timeout.Retry.
    NETWORKNo connection.Retry when the device is back online.
    PARSEThe server returned something that isn't JSON.Check baseUrl.
    CONFIGBad initialize parameters.Fix the parameters.
    NOT_INITIALIZEDAn SDK call was made before initialize.Call initialize first.
    EMPTYA message with no text and no files.–
    FILE_READThe picked file couldn't be read (React Native only).Pick the file again.
    UNIMPLEMENTEDA Capacitor call was made in a browser (e.g. ionic serve).Run on a simulator or device.
    REALTIMELive agent messages are unavailable (realtime not configured on the server, or the connection failed). Chat itself still works.Check the server's realtime settings and the network.

    7. Full examples#

    React Native#

    import React, { useEffect, useState } from 'react';
    import { Button, Modal, View } from 'react-native';
    import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
    import { FigoChat, FigoChatView } from '@figoailabs/figochat-react-native';
    
    export default function App() {
      const [open, setOpen] = useState(false);
    
      useEffect(() => {
        FigoChat.initialize({
          apiKey: 'YOUR_API_KEY',
          assistantId: 'YOUR_ASSISTANT_ID',
          fullName: 'Ada Lovelace',
          emailAddress: 'ada@example.com',
          mobilePhone: '+2348012345678',
          primaryColor: '#F97316',
          title: 'Support',
          welcomeMessage: 'Hi Ada! How can I help you today?',
        });
      }, []);
    
      return (
        <View style={{ flex: 1, justifyContent: 'center' }}>
          <Button title="Chat with us" onPress={() => setOpen(true)} />
          <Modal visible={open} animationType="slide" onRequestClose={() => setOpen(false)}>
            <SafeAreaProvider>
              <SafeAreaView style={{ flex: 1 }}>
                <FigoChatView onClose={() => setOpen(false)} onError={(e) => console.log('FigoChat', e.code, e.message)} />
              </SafeAreaView>
            </SafeAreaProvider>
          </Modal>
        </View>
      );
    }

    Flutter#

    Capacitor / Ionic Angular#

    // chat.service.ts
    import { Injectable } from '@angular/core';
    import type { PluginListenerHandle } from '@capacitor/core';
    import { FigoChat } from '@figoailabs/figochat-capacitor';
    
    @Injectable({ providedIn: 'root' })
    export class ChatService {
      private handles: PluginListenerHandle[] = [];
    
      async start(user: { name: string; email: string; phone: string }) {
        await FigoChat.initialize({
          apiKey: 'YOUR_API_KEY',
          assistantId: 'YOUR_ASSISTANT_ID',
          fullName: user.name,
          emailAddress: user.email,
          mobilePhone: user.phone,
          primaryColor: '#F97316',
          title: 'Support',
          welcomeMessage: 'Hi! How can I help you today?',
        });
        this.handles.push(
          await FigoChat.addListener('messageSent', (e) => console.log('User:', e.text)),
          await FigoChat.addListener('messageReceived', (e) => console.log('Assistant:', e.text)),
        );
      }
    
      open() {
        return FigoChat.open();
      }
    
      async stop() {
        await Promise.all(this.handles.map((h) => h.remove()));
        await FigoChat.logout();
      }
    }
    Call chat.start(...) after the user signs in and chat.stop() when they sign out.

    Android (native)#

    iOS (native, SwiftUI)#


    8. Example apps#

    Each SDK has a runnable example. Without an API key they still open the chat, and messages fail with the friendly "Chat isn't available right now" text, which is useful for checking the UI.
    PlatformExampleRun
    React Native (Expo)react-native/example in the figochatsdk repoPut the key in .env (see .env.example), then npx expo start --ios
    Flutterflutter/example in the figochatsdk repoflutter run --dart-define=FIGO_API_KEY=... --dart-define=FIGO_ASSISTANT_ID=...
    Androidsample/ in figochat-android./gradlew :sample:installDebug -PfigoApiKey=... -PfigoAssistantId=...
    iOSExample/FigoChatExample.xcodeproj in figochat-iosOpen in Xcode, set FIGO_API_KEY and FIGO_ASSISTANT_ID in the scheme's environment variables, and run
    Modified at 2026-11-17 13:26:34
    Previous
    FigoAI MCP Server Guide
    Next
    Figo Snap and Pay SDK
    Built with