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 > System > 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

Does Heartbeat have an MCP server or MCP connector?

Not at the moment. You can connect Heartbeat to an AI tool using the API and webhooks described above, but there is no Model Context Protocol connector. If you would like one, upvote the MCP Connector request to get updates when it changes.

Related Resources

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