API Reference

Complete reference for the Lingu React Native SDK classes and hooks.

LinguChat Component

The main component for rendering the chat interface.

Import

import { LinguChat } from '@lingu/react-native-sdk';

Props

interface LinguChatProps {
  // Required
  apiKey: string;
  
  // Display
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  theme?: 'light' | 'dark' | 'system';
  primaryColor?: string;
  autoOpen?: boolean;
  showBackButton?: boolean;
  
  // Callbacks
  onBackPress?: () => void;
  onSessionStart?: (sessionId: string) => void;
  onSessionEnd?: (sessionId: string) => void;
  onMessageSent?: (message: string) => void;
  onMessageReceived?: (message: string) => void;
}

Example

<LinguChat
  apiKey="lingu_abc123"
  position="bottom-right"
  theme="light"
  primaryColor="#3b82f6"
  autoOpen={false}
  onSessionStart={(id) => console.log('Started:', id)}
/>

---

useLinguChat Hook

Custom hook for building your own chat UI.

Import

import { useLinguChat } from '@lingu/react-native-sdk';

Usage

const {
  messages,
  isLoading,
  config,
  sendMessage,
  startSession,
  endSession,
  isSessionActive,
} = useLinguChat({
  apiKey: 'your-api-key-here',
});

Options

interface UseLinguChatOptions {
  apiKey: string;
  baseURL?: string;
}

Return Value

Property	Type	Description
messages	Message[]	Array of chat messages
isLoading	boolean	True while waiting for AI response
config	`WidgetConfig	null`
sendMessage	(text: string) => Promise<void>	Send a message
startSession	() => Promise<string>	Start a new session, returns session ID
endSession	() => Promise<void>	End the current session
isSessionActive	boolean	Whether a session is currently active

Message Type

interface Message {
  id: string;
  text: string;
  sender: 'user' | 'bot';
  timestamp: Date;
}

Example: Custom Chat UI

import { useLinguChat } from '@lingu/react-native-sdk';
import { View, TextInput, FlatList, Text, Button } from 'react-native';

function CustomChat() {
  const [input, setInput] = useState('');
  const {
    messages,
    isLoading,
    sendMessage,
    startSession,
    isSessionActive,
  } = useLinguChat({
    apiKey: 'your-api-key',
  });

  useEffect(() => {
    startSession();
  }, []);

  const handleSend = async () => {
    if (!input.trim()) return;
    await sendMessage(input);
    setInput('');
  };

  return (
    <View style={{ flex: 1 }}>
      <FlatList
        data={messages}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => (
          <Text style={{
            alignSelf: item.sender === 'user' ? 'flex-end' : 'flex-start',
            padding: 10,
            margin: 5,
            backgroundColor: item.sender === 'user' ? '#3b82f6' : '#e5e7eb',
            borderRadius: 10,
          }}>
            {item.text}
          </Text>
        )}
      />
      
      {isLoading && <Text>AI is thinking...</Text>}
      
      <View style={{ flexDirection: 'row', padding: 10 }}>
        <TextInput
          value={input}
          onChangeText={setInput}
          placeholder="Type a message..."
          style={{ flex: 1, borderWidth: 1, borderRadius: 20, paddingHorizontal: 15 }}
        />
        <Button title="Send" onPress={handleSend} />
      </View>
    </View>
  );
}

---

LinguAPI Class

Low-level API client for direct API access.

Import

import { LinguAPI } from '@lingu/react-native-sdk';

Constructor

const api = new LinguAPI(apiKey: string, baseURL?: string);

Methods

getConfig()

Fetches widget configuration from the API.

const config = await api.getConfig();
// Returns: WidgetConfig

startSession()

Starts a new chat session.

const sessionId = await api.startSession();
// Returns: string (session ID)

sendMessage(message, sessionId)

Sends a message and receives an AI response.

const response = await api.sendMessage('Hello!', sessionId);
// Returns: { text: string, ... }

endSession(sessionId)

Ends the current session.

await api.endSession(sessionId);
// Returns: void

sendHeartbeat(sessionId)

Sends a heartbeat to keep the session alive.

await api.sendHeartbeat(sessionId);
// Returns: void

Example: Direct API Usage

import { LinguAPI } from '@lingu/react-native-sdk';

async function chatExample() {
  const api = new LinguAPI('your-api-key');
  
  // Get widget configuration
  const config = await api.getConfig();
  console.log('Widget configured:', config.name);
  
  // Start a session
  const sessionId = await api.startSession();
  console.log('Session started:', sessionId);
  
  // Send a message
  const response = await api.sendMessage('What are your hours?', sessionId);
  console.log('AI response:', response.text);
  
  // End session when done
  await api.endSession(sessionId);
}

---

Type Definitions

WidgetConfig

interface WidgetConfig {
  id: string;
  name: string;
  primaryColor: string;
  backgroundColor: string;
  textColor: string;
  position: ChatPosition;
  theme: ThemeMode;
  greetingMessage: string;
  // ... additional config properties
}

ChatPosition

type ChatPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';

ThemeMode

type ThemeMode = 'light' | 'dark' | 'system';

---

Error Handling

All API methods may throw errors. Wrap calls in try-catch:

try {
  await api.sendMessage('Hello', sessionId);
} catch (error) {
  if (error.message.includes('network')) {
    console.log('Network error, please try again');
  } else if (error.message.includes('session')) {
    console.log('Session expired, starting new session');
    await api.startSession();
  } else {
    console.error('Unexpected error:', error);
  }
}