Link 🔗

An emotion-based anonymous matching system built on Series iMessage API. Connect users experiencing similar emotions for anonymous peer support.

What is Link?

Link is a Series-native messaging agent that uses emotion detection to anonymously match strangers who are feeling similar emotions. Once matched, users can have private, anonymous conversations where their messages are relayed through the system. Phone numbers stay completely private.

Features

• Emotion Detection: Automatically detects emotions from natural text (stressed, sad, anxious, lonely, happy)
• Anonymous Matching: Pairs users experiencing similar emotions
• Message Relaying: Messages are relayed anonymously between matched users
• AI Support: Optional integration with Gemini or Claude API for empathetic responses
• Privacy-First: Each user communicates through their own private chat with the bot

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure

Edit the configs file (not config.py) and update the required fields:

• SENDER_NUMBER - Your sender phone number from the Series dashboard
• API_KEY - Your Series API key
• API_BASE_URL - The base URL for the Series API (default: https://api.series.im)
• Kafka configuration (bootstrap servers, topic, consumer group, credentials)
• Optional: GEMINI_API_KEY or CLAUDE_API_KEY for AI responses

See config.py for the expected format (it's a reference file).

3. Run

python3 link.py

The system will connect to Kafka and start listening for messages.

How It Works

1. User Texts Link - Users send messages expressing their emotions (e.g., "I feel stressed" or "I'm really sad today")

2. Emotion Detection - Link analyzes the message to detect the primary emotion:

   • Stressed/overwhelmed
   • Sad/down
   • Anxious/worried
   • Lonely
   • Happy/excited

3. AI Response - Link sends an empathetic initial response (using AI if configured, or fallback messages)

4. Matching - Link searches for another user with the same emotion in the queue. If found, they're matched immediately; otherwise, the user joins the waiting queue.

5. Connection - When matched, both users receive a welcome message and are connected through separate private chats.

6. Anonymous Messaging - Messages are relayed anonymously between users. Each message appears as "Stranger: [message]" to maintain privacy.

7. Disconnect - Users can type /stop at any time to end the conversation.

Architecture

• Kafka Consumer: Listens for message.received events from Series
• In-Memory State: Tracks user states, emotion queues, and matches
• Series API: Sends messages via POST /api/chats and POST /api/chats/{chat_id}/chat_messages
• Event-Driven: Reacts to incoming messages in real-time
• LLM Integration: Optional Gemini/Claude API for empathetic responses

Emotion Detection

Link uses keyword-based emotion detection to categorize messages. It recognizes natural language expressions like:

• "I'm stressed", "overwhelmed", "burned out"
• "I feel sad", "down", "depressed"
• "I'm anxious", "worried", "panicking"
• "I'm lonely", "alone", "isolated"
• "I'm happy", "excited", "thrilled"

Commands

• /stop, stop, /end, /quit, /leave - Disconnect from current match

Demo Mode

The system includes a demo mode (enabled by default) that automatically creates a second user after 10 seconds if only one person is in the queue. This makes it easy to test with a single phone.

Privacy & Security

• Phone numbers are never shared between matched users
• All communication is anonymous
• Each user has their own private chat thread with the bot
• Messages are prefixed with "Stranger:" when relayed

Testing

1. Register phone numbers in the Series dashboard
2. Update the configs file with your credentials
3. Run python3 link.py
4. Text the sender number from registered phones
5. Express an emotion naturally
6. Wait to be matched (or use demo mode for instant matching)
7. Start chatting anonymously!

Example Flow

1. Phone 1: "Hey, I'm feeling really stressed about work"

   • Link: "I hear you - stress can be really overwhelming. I'm looking for someone who gets what you're going through. Hang tight."

2. Phone 2: "I'm so overwhelmed with everything"

   • Link: "I hear you - stress can be really overwhelming. I'm looking for someone who gets what you're going through. Hang tight."
   • Link: "You've been connected! You're both here because you're feeling stressed..."

3. Phone 1: "Hello?"

   • Phone 2 sees: "Stranger: Hello?"

4. Phone 2: "Hi! Yeah work is crazy"

   • Phone 1 sees: "Stranger: Hi! Yeah work is crazy"

5. Continue chatting anonymously, type /stop to disconnect

Requirements

• Python 3.7+
• Series API account and credentials
• Kafka access (provided by Series)
• Optional: Gemini or Claude API key for enhanced responses