Recursiv Docs

Add 1:1 messaging, group chat, read receipts, and media sharing to any application using the Recursiv SDK. Works with React, Next.js, React Native, Node.js, or any TypeScript/JavaScript project.

What You’ll Build

1:1 direct messaging between users
Group conversations with multiple participants
Message reactions (like, heart, fire, laugh, sad, angry)
Media attachments (images, files)
Real-time updates via Socket.IO

Prerequisites

Node.js 18+ (22+ recommended)
A Recursiv API key with chat:read and chat:write scopes
npm install @recursiv/sdk

Step 1: Initialize the SDK

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const client = new Recursiv({
4   apiKey: process.env.RECURSIV_API_KEY!,
5   // baseUrl: 'https://your-instance.com/api/v1', // for self-hosted
6 });

Step 2: Create a Direct Message Conversation

1 // Get or create a DM with another user
2 const { data: dm } = await client.chat.dm({ user_id: 'user_abc123' });
3 console.log(`DM conversation created: ${dm.id}`);
4 // { id: 'conv_xyz', type: 'dm', created: true }

Step 3: Send Messages

1 // Send a text message
2 const { data: msg } = await client.chat.send({
3   conversation_id: dm.id,
4   content: 'Hey! How are you doing?',
5 });
6 console.log(`Message sent: ${msg.id}`);
7 
8 // Reply to a specific message
9 const { data: reply } = await client.chat.send({
10   conversation_id: dm.id,
11   content: 'I agree!',
12   reply_to_id: msg.id,
13 });

Step 4: Fetch Message History

1 // Get the last 50 messages
2 const { data: messages, meta } = await client.chat.messages(dm.id, {
3   limit: 50,
4 });
5 
6 for (const msg of messages) {
7   console.log(`${msg.sender.name}: ${msg.content}`);
8 }
9 
10 // Paginate for older messages
11 if (meta.has_more) {
12   const olderMessages = await client.chat.messages(dm.id, {
13     limit: 50,
14     offset: 50,
15   });
16 }

Step 5: List All Conversations

1 const { data: conversations } = await client.chat.conversations();
2 
3 for (const convo of conversations) {
4   const lastMsg = convo.last_message;
5   console.log(`${convo.name || 'DM'}: ${lastMsg?.content || 'No messages'}`);
6 }

React Integration Example

1 import { useState, useEffect } from 'react';
2 import { Recursiv } from '@recursiv/sdk';
3 
4 const client = new Recursiv({ apiKey: process.env.NEXT_PUBLIC_RECURSIV_KEY! });
5 
6 function ChatRoom({ conversationId }: { conversationId: string }) {
7   const [messages, setMessages] = useState<Message[]>([]);
8   const [input, setInput] = useState('');
9 
10   useEffect(() => {
11     client.chat.messages(conversationId, { limit: 50 })
12       .then(({ data }) => setMessages(data));
13   }, [conversationId]);
14 
15   const sendMessage = async () => {
16     if (!input.trim()) return;
17     const { data: msg } = await client.chat.send({
18       conversation_id: conversationId,
19       content: input,
20     });
21     setMessages(prev => [...prev, msg as any]);
22     setInput('');
23   };
24 
25   return (
26     <div>
27       <div className="messages">
28         {messages.map(msg => (
29           <div key={msg.id}>
30             <strong>{msg.sender.name}</strong>: {msg.content}
31           </div>
32         ))}
33       </div>
34       <input value={input} onChange={e => setInput(e.target.value)} />
35       <button onClick={sendMessage}>Send</button>
36     </div>
37   );
38 }

What’s Included vs Building from Scratch

Feature	Recursiv	Building from Scratch
1:1 messaging	`client.chat.dm()`	Design schema, build WebSocket server, handle reconnection
Group chat	`client.chat.send()`	Fan-out delivery, member management, permissions
Read receipts	Built-in (read cursors)	Track per-user read cursors, sync across devices
Media attachments	Upload API	S3 integration, presigned URLs, thumbnail generation
Message reactions	REST API	Custom reaction system, aggregation, real-time sync

Time to ship: Hours with Recursiv vs months from scratch.

Add Chat to Your App