Titanmind Whatsapp MCP

🚀 Titanmind WhatsApp MCP

Titanmind WhatsApp MCP 是一款基於 Titanmind 的 WhatsApp 營銷與消息服務工具，採用了模型控制協議（MCP）。它能夠自動處理自由格式消息（24 小時窗口期）和模板工作流。

🚀 快速開始

本服務藉助 Titanmind 提供了所有 WhatsApp 營銷和消息功能，包括模板創建、模板註冊（涵蓋標題、正文、CTA 等所有組件）、向大量電話號碼批量廣播模板，以及在活躍對話中讀取和發送消息。

此 MCP 服務依賴於 Titanmind。使用該 MCP 必須擁有 Titanmind 賬戶。

Titanmind 提供了強大的功能，如對話管理、日程安排、智能對話、內容生成等，可增強 WhatsApp 的通信能力。

✨ 主要特性

對話管理

獲取最近對話

• 檢索過去 24 小時內有消息收發的所有對話。
• 返回包含最近活動的對話數據。

獲取對話消息

• 從特定對話中獲取所有消息。
• 需要參數：conversation_id（字母數字組成的對話標識符）。

發送 WhatsApp 消息

• 向現有的 WhatsApp 對話發送消息。
• 需要參數：conversation_id 和 message 內容。

模板管理

創建消息模板

• 註冊新的 WhatsApp 消息模板以獲得審批。
• 配置模板名稱（只能為單個單詞，允許使用下劃線）。
• 設置語言（默認：“en”）和類別（營銷、實用、認證）。
• 構建消息組件，包括：
  • 正文（必填）：主要文本內容。
  • 標題（可選）：支持文本、視頻、圖像或文檔格式。
  • 頁腳（可選）：頁腳文本。
  • 按鈕（可選）：支持快速回復、URL 或電話號碼操作。

獲取模板

• 檢索所有已創建模板及其審批狀態。
• 可根據模板名稱進行可選過濾。

批量發送消息

• 使用已批准的模板向多個電話號碼發送消息。
• 需要參數：template_id 和聯繫人列表。
• 聯繫人格式：國家代碼縮寫（如“IN”）、國家代碼（如“91”）和電話號碼。

📦 安裝指南

前提條件

• Python 3.10 或更高版本。
• 從 Titanmind 獲取的 API 密鑰和業務代碼。

使用 MCP 客戶端

在任何 MCP 客戶端（如 Claude 或 Cursor）中，可以通過以下方式添加 Titanmind WhatsApp MCP 配置：

使用 Titanmind WhatsApp MCP Python 包

1. 安裝 pipx 以全局安裝 Python 包：

# 終端命令

# 首先安裝 pipx
brew install pipx  # 在 macOS 上
# 或者
sudo apt install pipx  # 在 Ubuntu/Debian 上

# 然後安裝 Titanmind WhatsApp MCP Python 包 
pipx install titanmind-whatsapp-mcp

# 確保 '/[HOME_DIR_OR_USER_PRFILE]/.local/bin' 在您的 PATH 環境變量中。使用 pipx ensurepath 進行設置。
pipx ensurepath 

2. 在 MCP 客戶端的 MCP 配置 Json 文件中設置 MCP 配置腳本：

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "/[HOME_DIR_OR_USER_PRFILE]/.local/bin/titan-mind-mcp",
      "args": [
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

使用遠程 Titanmind MCP 服務器配置

1. 確保系統中已安裝 npx。
2. 添加 MCP 配置：

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.titanmind.so/whatsapp/mcp/",
        "--header",
        "api-key:XXXXXXXXXXXXXXXXXXXXXXX",
        "--header",
        "bus-code:XXXXXX"
      ]
    }
  }
}

使用本地 Python 項目配置

1. 首先按照“設置項目”部分的說明設置項目。
2. 添加 MCP 配置：

{
  "mcpServers": {
    "TitanMindMCP": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/[PATH_TO_THE_PROJECT]",
        "python",
        "main.py"
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

自定義或開發的手動安裝

從 PyPI 安裝包以供使用

pip install titanmind-whatsapp-mcp

或者使用 uv：

uv pip install titanmind-whatsapp-mcp

設置項目以供開發使用

1. 克隆倉庫：

git clone https://github.com/TitanmindAGI/titanmind-whatsapp-mcp
cd titanmind-whatsapp-mcp

2. 安裝依賴項：

pip install -e .
# 或者
uv pip install -e .

3. 設置認證密鑰：

export api-key="your-titanmind-api-key"
export bus-code="your-titanmind-business-code"

🔧 技術細節

TitanMind 的 WhatsApp 消息系統基於時間和對話狀態，採用兩種不同的消息模式：

自由格式消息（24 小時窗口期）

• 可用時間：僅在用戶在過去 24 小時內發送過消息之後。
• 內容自由度：允許任何內容，無需預先審批。
• 使用場景：正在進行的對話和即時回覆。

模板消息（超出 24 小時窗口期）

• 使用時機：用於新對話或 24 小時窗口期已過的情況。
• 內容結構：僅允許使用預先批准的結構化消息模板。
• 使用場景：初始推廣和重新互動活動。

消息工作流流程

1. 檢查消息窗口期狀態
   • 驗證接收方電話號碼是否處於自由格式消息窗口期內。
   • 若滿足以下條件，接收方有資格使用自由格式消息：
     • 與該電話號碼的對話已經存在。
     • 接收方在過去 24 小時內發送過消息。
2. 選擇消息發送方法
   • 自由格式：若在 24 小時窗口期內，直接發送。
   • 模板：若超出窗口期，註冊並使用已批准的模板。
3. 模板審批流程（如有需要）
   • 提交模板以供 WhatsApp 審批。
   • 等待審批確認。
   • 模板獲批後可用於批量消息發送。
4. 發送消息
   • 使用適當的方法執行消息發送。
   • 監控發送狀態。
5. 驗證發送結果
   • 檢查對話以確認接收方是否成功收到消息。
   • 跟蹤消息狀態和參與度。

📚 詳細文檔

• 所有工具均與 Titanmind 的 WhatsApp 頻道消息功能集成。
• 模板在用於批量消息發送之前需要獲得批准。
• 如需更多幫助，請通過 https://www.titanmind.so/ 聯繫我們。

📄 許可證

本項目採用 MIT 許可證。詳情請參閱 LICENSE 文件。