Installation

Yarn:

yarn add react-native-parlant

Npm:

npm install --save react-native-parlant

Expo

npx expo install react-native-parlant

Quick Start

import { SafeAreaView, StyleSheet } from "react-native";
import { useChat } from "react-native-parlant";
import { GiftedChat, IMessage } from "react-native-gifted-chat";

export default function Example() {
  const { messages, sendMessage, isTyping, isLoading } = useChat({
    agentId: "agent-id",
    api: "http://localhost:8800",
  });
  const onSend = (messages: IMessage[]) => {
    const userMessage = messages[0]?.text || "";
    sendMessage(userMessage);
  };

  return (
    <SafeAreaView style={styles.container}>
      <GiftedChat
        messages={messages}
        placeholder="Start typing..."
        onSend={onSend}
        isTyping={isTyping || isLoading}
        user={{
          _id: 1,
          name: "You",
        }}
        alwaysShowSend
        textInputProps={{
          style: styles.textInput,
        }}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "white",
  },
  textInput: {
    flex: 1,
    marginHorizontal: 10,
    paddingVertical: 12,
    paddingHorizontal: 16,
  },
});

API Reference

useChat(props: Props)

The main hook for managing chat sessions with Parlant AI agents.

Props

| Prop | Type | Required | Default | Description | | ----------------- | ------------------------ | -------- | ----------------------- | ------------------------------------- | | agentId | string | ✅ | - | The ID of the Parlant AI agent | | api | string | ✅ | http://localhost:8800 | The Parlant API endpoint | | initialMessages | IMessage[] | ❌ | [] | Initial messages to populate the chat | | moderation | string | ❌ | "auto" | Moderation setting for messages | | customerId | string | ❌ | "guest" | Unique identifier for the customer | | title | string | ❌ | "New Conversation" | Title for the chat session | | maxRetries | number | ❌ | 3 | Maximum retries for message fetching | | headers | Record<string, string> | ❌ | {} | Custom headers for API requests | | aiAvatar | string | ❌ | "" | Avatar URL for AI agent messages |

Returns

| Property | Type | Description | | ------------- | -------------------------------------------- | ------------------------------------- | | messages | IMessage[] | Array of chat messages | | sendMessage | (message: string) => Promise<MessageEvent> | Function to send a message | | isLoading | boolean | Whether a message is being sent | | isTyping | boolean | Whether the agent is currently typing |

append(currentMessages, newMessages, inverted?)

Utility function for appending messages to the chat.

Parameters

• currentMessages (TMessage[]) - Existing messages array
• newMessages (TMessage[]) - New messages to append
• inverted (boolean, default: true) - Whether to prepend (true) or append (false) messages

Types

IMessage

interface IMessage {
  _id: string | number;
  text: string;
  createdAt: Date | number;
  user: {
    _id: string | number;
    name?: string;
    avatar?: string | number | renderFunction;
  };
  image?: string;
  video?: string;
  audio?: string;
  system?: boolean;
  sent?: boolean;
  received?: boolean;
  pending?: boolean;
  quickReplies?: QuickReplies;
}

MessageEvent

interface MessageEvent {
  id: string;
  source: string;
  kind: "message" | "status";
  offset: number;
  creation_utc: string;
  correlation_id: string;
  data: {
    message: string;
    participant: {
      id: string;
      display_name: string;
    };
    flagged: boolean;
    tags: string[];
    status?: "typing" | "ready";
  };
  deleted: boolean;
}

Session

interface Session {
  id: string;
  agent_id: string;
  customer_id: string;
  creation_utc: string;
  title: string;
  mode: string;
  consumption_offsets: {
    client: number;
  };
}

Features

• 🤖 Real-time AI Chat - Connect to Parlant AI agents with real-time messaging
• 📱 Cross-Platform - Works with React Native, Expo, and React applications
• 🔄 Auto-Reconnection - Automatic retry logic for robust connections
• 🎯 TypeScript Support - Full TypeScript definitions included
• 💾 Session Management - Automatic session creation and management
• 🔒 Content Moderation - Built-in support for message moderation
• ⚡ Long Polling - Efficient real-time message fetching
• 🎨 Customizable - Flexible message and user interface customization

Advanced Usage

Custom Headers

const { messages, sendMessage } = useChat({
  agentId: "your-agent-id",
  api: "https://your-api.com",
  headers: {
    Authorization: "Bearer your-token",
    "X-Custom-Header": "custom-value",
  },
});

Initial Messages

const initialMessages: IMessage[] = [
  {
    _id: 1,
    text: "Hello! How can I help you today?",
    createdAt: new Date(),
    user: {
      _id: 2,
      name: "AI Assistant",
      avatar: "https://example.com/avatar.png",
    },
  },
];

const { messages, sendMessage } = useChat({
  agentId: "your-agent-id",
  api: "https://your-api.com",
  initialMessages,
});

Error Handling

const handleSendMessage = async (text: string) => {
  try {
    await sendMessage(text);
  } catch (error) {
    if (error.message === "Failed to send message") {
      // Handle send failure
      console.error("Message failed to send");
    } else if (error.message === "Failed to create session") {
      // Handle session creation failure
      console.error("Could not establish chat session");
    }
  }
};

Requirements

• React 16.8+ (for hooks support)
• TypeScript 4.0+ (optional but recommended)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For questions and support, please contact Adrian on X or open an issue on GitHub.

Ready to build AI agents that actually work?

⭐ Star this repo • 💬 Contact Adrian to Build It

Built with ❤️ by Adrian

Keywords: react-native, react, parlant, ai, agent, chat, conversation, typescript, react-native-parlant