freshdesk-automation

Rube MCP を使った Freshdesk の自動化

Composio の Freshdesk ツールキットを通じて、チケット管理、連絡先と会社の操作、メモ、返信、チケット検索など、Freshdesk のカスタマーサポートのワークフローを自動化します。

ツールキットのドキュメント：composio.dev/toolkits/freshdesk

前提条件

• Rube MCP が接続されている必要があります（RUBE_SEARCH_TOOLS が利用可能）
• RUBE_MANAGE_CONNECTIONS を通じて、ツールキット freshdesk の有効な Freshdesk 接続が必要です
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP を入手する：クライアント設定で https://rube.app/mcp を MCP サーバーとして追加します。API キーは不要です。エンドポイントを追加するだけで動作します。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確かめます
2. ツールキット freshdesk を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って Freshdesk の認証を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

主なワークフロー

1. チケットの作成と管理

使用する場面：ユーザーが新しいサポートチケットの作成、既存チケットの更新、またはチケットの詳細表示を希望する場合。

ツールの実行順序：

1. FRESHDESK_SEARCH_CONTACTS - メールアドレスで依頼者を検索し、requester_id を取得します［任意］
2. FRESHDESK_LIST_TICKET_FIELDS - 利用可能なカスタムフィールドとステータスを確認します［任意］
3. FRESHDESK_CREATE_TICKET - 件名、説明、依頼者情報を指定して新しいチケットを作成します［必須］
4. FRESHDESK_UPDATE_TICKET - チケットのステータス、優先度、担当者、またはその他のフィールドを変更します［任意］
5. FRESHDESK_VIEW_TICKET - ID でチケットの詳細をすべて取得します［任意］

FRESHDESK_CREATE_TICKET の主なパラメーター：

• subject：チケットの件名（必須）
• description：チケットの HTML コンテンツ（必須）
• email：依頼者のメールアドレス（依頼者を識別する情報を少なくとも 1 つ指定する必要があります）
• requester_id：依頼者のユーザー ID（email の代わりに指定できます）
• status：2=オープン、3=保留中、4=解決済み、5=クローズ（デフォルトは 2）
• priority：1=低、2=中、3=高、4=緊急（デフォルトは 1）
• source：1=メール、2=ポータル、3=電話、7=チャット（デフォルトは 2）
• responder_id：チケットの割り当て先となるエージェント ID
• group_id：チケットの割り当て先となるグループ
• tags：タグ文字列の配列
• custom_fields：cf_<field_name> 形式のキーを持つオブジェクト

注意事項：

• 依頼者を識別する情報として、requester_id、email、phone、facebook_id、twitter_id、unique_external_id のいずれかを少なくとも 1 つ指定する必要があります
• email を指定せずに phone を指定する場合、name が必須になります
• description は HTML 形式に対応しています
• attachments フィールドには multipart/form-data 形式が必要です。ファイルパスや URL は指定できません
• カスタムフィールドのキーには cf_ を付ける必要があります（例：cf_reference_number）
• ステータスと優先度は文字列ではなく整数です

2. チケットを検索して絞り込む

使用する場面：ステータス、優先度、日付範囲、担当者、カスタムフィールドでチケットを検索したい場合です。

ツールの順序：

1. FRESHDESK_GET_TICKETS - シンプルなフィルター（ステータス、優先度、担当者）でチケットを一覧表示します［必須］
2. FRESHDESK_GET_SEARCH - クエリ構文を使って高度なチケット検索を行います［必須］
3. FRESHDESK_VIEW_TICKET - 検索結果に含まれる特定のチケットの詳細を取得します［任意］
4. FRESHDESK_LIST_TICKET_FIELDS - 検索クエリで使用できるフィールドを確認します［任意］

FRESHDESK_GET_TICKETS の主なパラメーター：

• status：ステータスの整数値で絞り込みます（2=Open、3=Pending、4=Resolved、5=Closed）
• priority：優先度の整数値で絞り込みます（1～4）
• agent_id：割り当てられた担当者で絞り込みます
• requester_id：依頼者で絞り込みます
• email：依頼者のメールアドレスで絞り込みます
• created_since：ISO 8601 のタイムスタンプ
• page / per_page：ページネーション（デフォルトは1ページあたり30件）
• sort_by / sort_order：並べ替えフィールドと順序

FRESHDESK_GET_SEARCH の主なパラメーター：

• query："status:2 AND priority:3" や "(created_at:>'2024-01-01' AND tag:'urgent')" のようなクエリ文字列
• page：ページ番号（1～10、合計最大300件）

注意点：

• FRESHDESK_GET_SEARCH のクエリは二重引用符で囲む必要があります
• クエリ文字列は512文字までです
• 検索エンドポイントでは最大10ページ（300件）まで取得できます
• クエリの日付フィールドには UTC 形式の YYYY-MM-DD を使用します
• 空のフィールドを持つチケットを検索するには、null キーワードを使用します（例："agent_id:null"）
• FRESHDESK_LIST_ALL_TICKETS はパラメーターを受け取らず、すべてのチケットを返します（絞り込みには GET_TICKETS を使用してください）

3. チケットに返信し、メモを追加する

使用する場面：顧客に返信を送信したり、内部メモを追加したり、会話履歴を確認したりする場合です。

ツールの順序：

1. FRESHDESK_VIEW_TICKET - チケットの存在を確認し、現在の状態を確認します［前提条件］
2. FRESHDESK_REPLY_TO_TICKET - 依頼者に公開返信を送信します［必須］
3. FRESHDESK_ADD_NOTE_TO_TICKET - 非公開または公開メモを追加します［必須］
4. FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS - チケットのすべてのメッセージとメモを確認します［任意］
5. FRESHDESK_UPDATE_CONVERSATIONS - 既存のメモを編集します［任意］

FRESHDESK_REPLY_TO_TICKET の主なパラメーター：

• ticket_id：チケット ID（整数、必須）
• body：返信内容。HTML をサポートします（必須）
• cc_emails / bcc_emails：追加の宛先（to/cc/bcc の合計で最大50件）
• from_email：複数のサポート用メールアドレスが設定されている場合、送信者のメールアドレスを上書きします
• user_id：代理で返信する担当者の ID

FRESHDESK_ADD_NOTE_TO_TICKET の主なパラメーター：

• ticket_id：チケット ID（整数、必須）
• body：メモの内容。HTML をサポートします（必須）
• private：担当者のみが閲覧できる場合は true、公開する場合は false（デフォルトは true）
• notify_emails：担当者のメールアドレスのみ受け付けます。外部連絡先は指定できません

注意点：

• 返信ツールは FRESHDESK_REPLY_TO_TICKET（機能が豊富）と FRESHDESK_REPLY_TICKET（シンプル）の2種類があります。どちらも使用できます
• FRESHDESK_ADD_NOTE_TO_TICKET はデフォルトで非公開（担当者のみ閲覧可能）です。メモを公開するには private: false を設定します
• メモの notify_emails で指定できるのは担当者のメールアドレスのみです。顧客のメールアドレスは指定できません
• FRESHDESK_UPDATE_CONVERSATIONS で編集できるのはメモのみです。受信した返信は編集できません

4. 連絡先と会社を管理する

使用する場面：顧客の連絡先や会社のレコードを作成、検索、または管理する場合。

ツールの順序：

1. FRESHDESK_SEARCH_CONTACTS - メールアドレス、電話番号、または会社名で連絡先を検索します［必須］
2. FRESHDESK_GET_CONTACTS - フィルターを指定して連絡先の一覧を取得します［任意］
3. FRESHDESK_IMPORT_CONTACT - CSV から連絡先を一括インポートします［任意］
4. FRESHDESK_SEARCH_COMPANIES - カスタムフィールドで会社を検索します［必須］
5. FRESHDESK_GET_COMPANIES - すべての会社の一覧を取得します［任意］
6. FRESHDESK_CREATE_COMPANIES - 新しい会社を作成します［任意］
7. FRESHDESK_UPDATE_COMPANIES - 会社の詳細を更新します［任意］
8. FRESHDESK_LIST_COMPANY_FIELDS - 利用可能な会社フィールドを確認します［任意］

FRESHDESK_SEARCH_CONTACTS の主なパラメーター：

• query："email:'[email protected]'" のような検索文字列（必須）
• page：ページネーション（1～10、1ページあたり最大30件）

FRESHDESK_CREATE_COMPANIES の主なパラメーター：

• name：会社名（必須）
• domains：連絡先と自動関連付けするためのドメイン文字列の配列
• health_score："Happy"、"Doing okay"、または "At risk"
• account_tier："Basic"、"Premium"、または "Enterprise"
• industry：標準的な業種分類

注意点：

• FRESHDESK_SEARCH_CONTACTS では完全一致が必要です。部分一致検索や正規表現検索はサポートされていません
• FRESHDESK_SEARCH_COMPANIES では標準の name フィールドで検索できません。カスタムフィールドまたは created_at を使用してください
• 会社のカスタムフィールドには cf_ プレフィックスを使用しません（チケットのカスタムフィールドとは異なります）
• 会社の domains を設定すると、メールドメインに基づいて連絡先と会社が自動的に関連付けられます
• 連絡先の検索クエリでは、文字列値を二重引用符で囲んだクエリ内で一重引用符で囲む必要があります

よく使われるパターン

ID の解決

操作の前に、表示値を必ず ID に解決してください。

• 依頼者のメールアドレス -> requester_id：FRESHDESK_SEARCH_CONTACTS で "email:'[email protected]'" を指定します
• 会社名 -> company_id：FRESHDESK_GET_COMPANIES を使用し、名前で照合します（名前での検索はサポートされていません）
• エージェント名 -> agent_id：直接取得する方法はありません。チケットの応答または管理者設定から agent_id を使用してください

ページネーション

Freshdesk ではページ単位のページネーションを使用します。

• FRESHDESK_GET_TICKETS：page（1 から開始）と per_page（最大100）
• FRESHDESK_GET_SEARCH：page（1～10、1ページあたり30件、合計最大300件）
• FRESHDESK_SEARCH_CONTACTS：page（1～10、1ページあたり30件）
• FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS：page と per_page（最大100）

既知の注意点

ID の形式

• チケット ID、連絡先 ID、会社 ID、エージェント ID、グループ ID はすべて整数です
• Freshdesk に文字列形式の ID はありません

レート制限

• Freshdesk では、プランの階層に応じたアカウントごとの API レート制限が適用されます
• 429 応答を避けるため、一括操作は間隔を空けて実行してください
• 検索エンドポイントで取得できる結果は合計300件（30件ずつ、最大10ページ）までです

パラメーターに関する注意点

• ステータス値：2=Open、3=Pending、4=Resolved、5=Closed（文字列ではなく整数）
• 優先度の値：1=Low、2=Medium、3=High、4=Urgent（文字列ではなく整数）
• ソース値：1=Email、2=Portal、3=Phone、7=Chat、9=Feedback Widget、10=Outbound Email
• チケットのカスタムフィールドには cf_ プレフィックスを使用しますが、会社のカスタムフィールドには使用しません
• チケットの description では HTML 形式を使用できます
• 検索クエリ文字列は二重引用符で囲み、文字列値は一重引用符で囲む必要があります
• FRESHDESK_LIST_ALL_TICKETS は、フィルターパラメーターを指定せずにすべてのチケットを返します

応答の構造

• チケットの詳細には、依頼者、担当者、会話データのネストされたオブジェクトが含まれます
• 検索結果はページ分割され、10ページにわたる合計300件が上限です
• 会話一覧には、返信とメモの両方が時系列順で含まれます

Quick Reference

Task	Tool Slug	Key Params
Create ticket	FRESHDESK_CREATE_TICKET	subject, description, email, priority
Update ticket	FRESHDESK_UPDATE_TICKET	ticket_id, status, priority
View ticket	FRESHDESK_VIEW_TICKET	ticket_id
List tickets	FRESHDESK_GET_TICKETS	status, priority, page, per_page
List all tickets	FRESHDESK_LIST_ALL_TICKETS	(none)
Search tickets	FRESHDESK_GET_SEARCH	query, page
Reply to ticket	FRESHDESK_REPLY_TO_TICKET	ticket_id, body, cc_emails
Reply (simple)	FRESHDESK_REPLY_TICKET	ticket_id, body
Add note	FRESHDESK_ADD_NOTE_TO_TICKET	ticket_id, body, private
List conversations	FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS	ticket_id, page
Update note	FRESHDESK_UPDATE_CONVERSATIONS	conversation_id, body
Search contacts	FRESHDESK_SEARCH_CONTACTS	query, page
List contacts	FRESHDESK_GET_CONTACTS	email, company_id, page
Import contacts	FRESHDESK_IMPORT_CONTACT	file, name_column_index, email_column_index
Create company	FRESHDESK_CREATE_COMPANIES	name, domains, industry
Update company	FRESHDESK_UPDATE_COMPANIES	company_id, name, domains
Search companies	FRESHDESK_SEARCH_COMPANIES	query, page
List companies	FRESHDESK_GET_COMPANIES	page
List ticket fields	FRESHDESK_LIST_TICKET_FIELDS	(none)
List company fields	FRESHDESK_LIST_COMPANY_FIELDS	(none)

---

Powered by Composio