Create an automated AI assistant that responds to member questions through direct messages in your Heartbeat community.

What You'll Build

An AI-powered bot that:

• Receives direct messages from community members
• Processes questions through your chosen LLM (Large Language Model)
• Automatically responds with helpful answers
• Can proactively reach out to new members or students

Requirements

• A Heartbeat community on any plan
• Access to an LLM service (ChatGPT, Claude, or similar)
• Basic understanding of webhooks and API calls
• A server or service to handle webhook events (like Zapier, Make, or custom code)

Step-by-Step Setup

Step 1: Create Your Bot Admin Account

Your bot needs its own admin account in your community:

1. Create a new admin invitation link in your community
2. Use this link to invite a new admin with:
   • The name you want your bot to have (e.g., "Support Bot" or "Community Assistant")
   • A profile picture that represents your bot
3. Complete the onboarding for this admin account

Tip: This admin account will appear to members as any other admin would, so choose a name and profile picture that clearly indicate it's an automated assistant.

Step 2: Generate an API Key

You'll need an API key to authenticate your webhook and automation setup:

1. Go to Settings > API Keys in your Heartbeat admin panel
2. Click Create New API Key
3. Give it a descriptive name (e.g., "Bot Webhook Key")
4. Save the key securely—you'll need it for your webhook configuration

Step 3: Set Up the Direct Message Webhook

Configure Heartbeat to notify your service whenever the bot receives a DM:

1. Reference the Heartbeat API documentation for webhook setup
2. Create a webhook with these settings:
   • Action Type: DIRECT_MESSAGE
   • Filter: Set userID to the bot admin account you created in Step 1
   • URL: Your endpoint that will process incoming messages

The webhook payload will include:

• senderUserID - Who sent the message
• receiverUserID - Your bot's user ID
• chatID - The conversation ID
• chatMessageID - The specific message ID

Step 4: Connect Your LLM

When your webhook receives a message:

1. Extract the message content from the payload
2. Send it to your LLM service (ChatGPT API, Claude API, etc.)
3. Include relevant context like:
   • Community guidelines
   • Common questions and answers
   • Member information if applicable
4. Receive the AI-generated response

Step 5: Send the Response Back

Use the Heartbeat API to send the bot's response:

• Endpoint: PUT /directMessages
• Required fields:
  • text - The AI-generated response
  • to - The senderUserID from the webhook payload
  • from - Your bot's user ID (optional, for admin-sent messages)

The member will receive the response in their DM conversation with the bot.

Advanced Enhancements

Proactive Welcome Messages

Set up a "user join" webhook to have your bot automatically greet new members:

1. Create a webhook with action type USER_JOIN
2. When triggered, use the /directChats endpoint to create a conversation
3. Send a welcome message with helpful getting-started information

Course-Specific Assistance

Help students when they start a course:

1. Create a "group join" webhook filtered by your course access group
2. When a student joins, trigger a DM with course resources and tips
3. Customize messages based on which course they enrolled in

Context-Aware Responses

Make your bot more helpful by:

• Storing conversation history for each member
• Including member profile information in LLM prompts
• Referencing help center articles or community resources
• Escalating complex questions to human admins when needed

Common Use Cases

• 24/7 support for common questions
• Onboarding assistance for new members
• Course navigation help for students
• Community guideline reminders
• Resource recommendations based on member interests

Related Resources

• Heartbeat API Documentation
• How to Create Automated Welcome Emails
• Workflows Overview