# カスタムチャネル

カスタムチャネルを使用して、あらゆるメッセージングプラットフォームやコミュニケーションツールを本プラットフォームに接続できます。これにより、Webサイトのライブチャットウィジェット、メールシステム、CRM、その他のサービスからのメッセージをインボックスに集約し、AIエージェントでそれらに応答できるようになります。


---

## カスタムチャネルとは？

カスタムチャネルは、本プラットフォームの組み込みメッセージングプラットフォーム（[WhatsApp](whatsapp-business.md)、[SMS](sms.md)、[Instagram](instagram-dms.md)、[Messenger](facebook-messenger.md)）の枠を超えて機能を拡張します。カスタムチャネルを使用すると、以下のことが可能になります。

- **メッセージの受信:** 外部プラットフォームからのメッセージを、本プラットフォームの統合インボックスで受信します。
- **返信の送信:** アプリから外部プラットフォームへ自動的に返信を送信します。
- **AIエージェントの活用:** あらゆるソースからのメッセージに対してAIエージェントが応答します。
- **会話の追跡:** すべての会話を他のチャネルと並べて、単一のインボックスで管理します。

これは、専門的なコミュニケーションツールを使用している企業や、独自に構築したプラットフォームを持っている企業、あるいはすべての顧客メッセージを一元管理したい企業に最適です。

::: note
**注:** カスタムチャネルには技術的な設定が必要です。技術的な統合に不安がある場合は、Web開発者やITチームにこのセクションのサポートを依頼することをお勧めします。
:::


---

## 仕組み

カスタムチャネルは、**Webhook**（インターネット経由でシステム間で自動送信されるメッセージ）を使用して、外部プラットフォームと本プラットフォーム間でメッセージをやり取りする仕組みです。流れは以下の通りです。

```
Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform
```

1. **受信メッセージ:** 外部プラットフォームがWebアドレス（URL）にメッセージを送信します。これは、外部プラットフォームが本プラットフォームのメールボックスにメッセージを「投稿」するようなものだと考えてください。
2. **処理:** 本プラットフォームが連絡先を作成または更新し、メッセージを保存します。また、（有効な場合）AIエージェントが応答を生成します。
3. **送信メッセージ:** 本プラットフォームが返信を送信する際（AIによるものか、ユーザー自身が入力したものかにかかわらず）、そのメッセージはユーザー側のURLに送信され、そこからシステムがエンドユーザーに配信します。

---

## 受信メッセージの設定（お客様のプラットフォームからアプリへ）

外部プラットフォームからアプリへメッセージを送信するには、以下のURLにデータを送信する必要があります。開発者はこれを標準的なPOSTリクエスト（インターネット経由でシステム間でデータを送信する一般的な方法）として認識します。

### メッセージの送信先

```
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
```

`YOUR_API_KEY`をAPIキー（本プラットフォームに対して、メッセージ送信の許可があることを証明するプライベートコード）に置き換えてください。APIキーは**設定 → インテグレーション → APIキー**から確認または生成できます。

### メッセージ形式

以下の形式（JSON）でメッセージデータを送信してください：

```json
{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}
```

**各項目の意味：**
- `messageSid` - この特定のメッセージに対する一意のID（貴社のシステムで作成してください）。同じメッセージが二重に処理されるのを防ぐために使用されます。
- `fromId` - メッセージの送信者（貴社システムのユーザーID、メールアドレス、電話番号など）。
- `toId` - 貴社のビジネス識別子（任意のラベルを指定可能）。
- `body` - 実際のメッセージ本文。
- `channel` - メッセージの送信元を識別するために選択するラベル（例：「website-chat」、「email」）。

### フィールド詳細リファレンス

| フィールド | 必須 | 説明 |
|---|---|---|
| `customData.messageSid` または `customData.id` | はい | このメッセージの一意のID（重複を防止） |
| `customData.fromId` | はい | 送信者を識別（例：システム内のユーザーID、メールアドレス、電話番号） |
| `customData.toId` | はい | 受信側（貴社）を識別。任意のテキストを指定可能 |
| `customData.body` | はい | メッセージ本文。空にはできません |
| `customData.status` | いいえ | メッセージステータス。省略するとデフォルト（`"received"`）が使用されます |
| `customData.channel` | いいえ | ソースのラベル（例：`"live-chat"`、`"email"`、`"my-crm"`）。インボックスでメッセージの出所を識別するのに役立ちます |
| `customData.campaignId` | いいえ | キャンペーン/エージェントID。特定のAI設定にメッセージをルーティングするために使用します |
| `customData.firstName` | いいえ | 連絡先の名前（名）。新しい連絡先レコードを作成する際に含めます |
| `customData.lastName` | いいえ | 連絡先の名前（姓）。新しい連絡先レコードを作成する際に含めます |
| `customData.email` | いいえ | 連絡先のメールアドレス。新しい連絡先レコードを作成する際に含めます |
| `customData.mediaUrl` | いいえ | 添付ファイル（画像、動画、音声、ドキュメント）へのリンク。Base64エンコードされたファイルも指定可能です（下記参照） |
| `customData.mediaContentType` | いいえ | ファイルタイプ（例：`"image/jpeg"`、`"video/mp4"`、`"audio/ogg"`、`"application/pdf"`）。`mediaUrl`を含める場合は必須です |
| `messageType` | いいえ | メッセージタイプ。通常のテキストの場合は省略してください。絵文字リアクションの場合は`"reaction"`に設定します |

### 絵文字リアクション

プラットフォームが絵文字リアクション（メッセージへの「いいね」など）をサポートしている場合は、テキストメッセージとしてではなく、リアクションとして送信してください。`messageType` を `"reaction"` に設定し、`customData.body` には絵文字のみを含めます。

```json
{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}
```

アシスタントは、期待通りにそれを処理します：

- アシスタントが尋ねた質問（例：「木曜日はどうですか？」）に対するリアクションは回答として扱われ、アシスタントが返信します。
- 終了メッセージ（例：「また後で！」）に対するリアクションは、会話を静かに終了させます。返信は送信されません。

プラットフォームがリアクションを「Reacted with: 👍」のようなテキストに変換する場合、アシスタントは通常のテキストメッセージとして認識し、返信するかどうかを独自に判断します。リアクションタイプを送信することで、それを回避できます。

### 返される内容

リクエストが成功すると、以下が返されます：

```json
{
  "success": true,
  "messageId": "1234567890"
}
```

問題が発生した場合は、原因を説明するエラーメッセージが返されます：

```json
{
  "error": "Message body cannot be empty"
}
```

### ステータスコード

| コード | 意味 |
|---|---|
| `200` | 成功 - メッセージを受信し、処理中です |
| `400` | リクエストに問題があります - 必須フィールドの欠落やメッセージ本文が空になっていないか確認してください |
| `401` | 無効なAPIキー - **設定 → 統合 → APIキー** でキーを再確認してください |
| `405` | 間違ったリクエストメソッド - GETではなくPOSTを使用していることを確認してください |
| `500` | プラットフォーム側で問題が発生しました - しばらくしてから再試行してください |

> `customData.status` を設定する場合、受け入れられる値は `"received"` のみです。それ以外の値を送信すると `400` が返されるため、デフォルトを使用する場合はこの設定を完全に省略してください。

---

## メディア添付ファイルの送信（画像、動画、ファイル）

メッセージにファイル（画像、動画、音声、ドキュメント）を添付できます。方法は2通りあります：

### オプション1：ファイルへのリンク

ファイルがすでにオンラインでホストされている場合は、プラットフォームがダウンロード可能なURL（Webアドレス）を指定してください：

```json
{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}
```

### オプション2：ファイルを直接埋め込む（Base64）

ファイルがオンラインでホストされていない場合は、エンコードされたテキスト（base64形式）としてメッセージに直接埋め込むことができます。これは、システムがオンザフライでファイルを生成する技術的な統合において一般的です。プラットフォームは自動的にファイルをデコードして保存します。

```json
{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}
```

::: note
**注:** ファイルを直接埋め込むと、メッセージデータが大幅に大きくなります。大きなファイルの場合は、オンラインでホストし、リンクを送信する（オプション1）方が適しています。
:::


---

## 送信メッセージの設定（プラットフォームからお客様のプラットフォームへ）

本プラットフォームがカスタムチャネルで返信を送信する際（AIによるものか、ユーザー自身が入力したものかにかかわらず）、その返信は自動的にユーザー側のURLに送信され、システムがエンドユーザーに配信できるようになります。

> **最初にWebhook URLを設定してください。** 返信が配信される前に、カスタムチャネルのWebhook URLを保存する必要があります。URLが保存されていない場合、返信は生成・保存されますが、外部には送信されません。また、「失敗」ステータスも表示されないため、インボックスで問題に気づくことができません。本番環境で使用する前に、必ずWebhook URLを設定してください。

### 返信の送信先をアプリに指定する

1. 左側のサイドバーで、下部付近にある **設定** をクリックします。
2. 設定の左側のレールにある **チャネル** の下で、**チャネル** をクリックします。
3. ページの一番下（Android SMSゲートウェイ、iMessage、ウェブサイトチャットウィジェット、Twilioアカウント、規制コンプライアンスよりも下）にある **カスタムチャネル** カードを見つけます。
4. **Webhook URL** を入力します。これは、AIが送信メッセージを送る先のプラットフォーム上のURLです（開発者が返信を受信・処理するように設定します）。これは **公開されているHTTPS URL** である必要があります。`http://` アドレスや非公開ホストは拒否されます。
5. **保存** をクリックします。



### プラットフォームからお客様のプラットフォームへ送信されるデータ

プラットフォームが返信を送信すると、お客様のプラットフォームは以下のデータを受信します。

```json
{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}
```

### 各フィールドの意味

| フィールド | 内容 |
|---|---|
| `contactId` | この連絡先に対するプラットフォームの内部ID |
| `messageId` | アプリ内でのこのメッセージの一意のID |
| `userId` | お客様のユーザーID |
| `body` | 返信テキスト |
| `toId` | お客様のプラットフォーム上での連絡先ID（これは、着信メッセージで送信した `fromId` と一致します） |
| `channel` | 割り当てたカスタムチャネルラベル |

お客様のプラットフォームはこのデータを受信し、それを使用して独自のシステムを通じてエンドユーザーに返信を配信します。

### プラットフォームによる配信追跡方法

お客様のプラットフォームに返信を送信した後、プラットフォームはメッセージのステータスを更新します。

- **送信済み** - お客様のプラットフォームがメッセージを正常に受信しました。
- **失敗** - お客様のプラットフォームがエラーを返したか、到達できませんでした。プラットフォームはエラーの詳細をメッセージとともに保存するため、トラブルシューティングを行うことができます。

---

## システムからアプリへのメッセージ送信

メッセージの受信に加え、独自のシステムからカスタムチャネルを通じて送信メッセージを送ることも可能です。これは、会話を開始したり、プロアクティブなメッセージを送信したりする場合に便利です。

> **プラン要件:** API経由でのメッセージ送信および同期には、APIアクセスと少なくとも1つのメッセージングチャネルが含まれるプランが必要です。`403` 「permission denied / feature not enabled（権限がない、または機能が有効になっていません）」というエラーが表示される場合は、現在のプランにこの機能が含まれていません。プランをアップグレードするか、サポートにお問い合わせください。

### 送信先

```
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
```

### メッセージ形式

```json
{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}
```

### 必須フィールド

| フィールド | 説明 |
|---|---|
| `customData.fromId` | お客様のプラットフォーム上の連絡先ID |
| `customData.customChannel` | カスタムチャネルの名前（例: "my-live-chat"） |
| `customData.body` | 送信するメッセージテキスト |

オプションのフィールド（`campaignId`、`firstName`、`lastName`、`email`）は、受信メッセージの場合と同様に機能し、本プラットフォームが連絡先レコードを作成または更新するのに役立ちます。

### 返される内容

```json
{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}
```

---

## 他のシステムから送信されたメッセージの記録

すでに別のツール（別のプラットフォームのワークフローなど）から連絡先にメッセージを送信済みで、AIに完全なコンテキストを持たせるために本プラットフォームにその情報を記録させたい場合があります。これは送信とは異なり、本プラットフォームはメッセージを記録しますが、連絡先へ再配信は**しません**。

### 送信先

```
POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY
```

`customData.fromId`（お客様のプラットフォーム上の連絡先ID）と`customData.body`（すでに送信済みのメッセージテキスト）を含めてください。

### 動作について

- **メッセージは記録されますが、再送信はされません。** 本プラットフォームはコンテキスト目的でのみ会話に保存します。
- **デフォルトでは、その連絡先に対してAIは一時停止されます。** これは、人間がすでに対応したメッセージに対してボットが重複して返信することを防ぐためです。ボットをアクティブに保つには、`customData.pauseAi: false`を渡してください。
- **新しい連絡先は自動的に作成可能です。** `customData.customChannel`を含めると、連絡先が存在しない場合に作成されます。
- **重複は無視されます。** 同じ`messageSid`を再利用した場合、本プラットフォームはメッセージがすでに記録済みであることを認識し、変更を加えません。

> **プランの要件:** 送信と同様に、API経由でメッセージを記録するには、APIアクセスと少なくとも1つのメッセージングチャネルを含むプランが必要です。`403` 「permission denied / feature not enabled（権限が拒否されました / 機能が有効になっていません）」というエラーは、現在のプランにこの機能が含まれていないことを意味します。

---

## 実践的な例

### ウェブサイトのライブチャット

Webサイトのライブチャットウィジェットを本プラットフォームに接続し、AIエージェントが訪問者の質問に回答できるようにします：

1. 訪問者がウェブサイトのチャットウィジェットにメッセージを入力します。
2. チャットウィジェットがそのメッセージをプラットフォームに送信します。
3. AIエージェントが応答を生成します。
4. 応答がチャットウィジェットに送り返され、訪問者に表示されます。

**この利点:** ウェブサイトの訪問者は、あなたがオンラインでなくても、AIによる即時の回答を得ることができます。

### メール

メールのやり取りをプラットフォーム経由にすることで、AIエージェントがメールに応答できるようになります：

1. 受信メールをプラットフォームに転送するシステムを設定します（メール送信者のアドレスを`fromId`として、メールの件名と本文を`body`として、そして`"email"`を`channel`として使用します）。
2. AIエージェントがメールを読み取り、返信を生成します。
3. 返信がメールシステムに送り返され、通常のメール応答として送信されます。

**これが役立つ理由:** よくあるメールでの質問（価格、営業時間、在庫状況など）に、AIエージェントが即座に応答できるようになります。

> お使いのメールシステムがIMAP/SMTPまたはOAuthに対応している場合は、カスタム統合よりも組み込みの[メールチャネル](email.md)の方が簡単に設定できる可能性があります。

### CRM統合

既存のCRM（顧客関係管理）システムをプラットフォームに接続します。

1. リードがCRMを通じてメッセージを送信した際、それをプラットフォームに転送します。
2. AIエージェントが応答し、会話を追跡します。
3. AIの応答がCRMに送り返され、配信されます。
4. 完全な会話履歴が、プラットフォームとCRMの両方で利用可能になります。

**この利点:** 営業チームはCRMから離れることなく、AIによるリードへの回答支援を受けることができます。

### サポートチケットシステム

AIを活用した一次対応窓口としてプラットフォームを利用します：

1. チケット管理システムが新しいサポートチケットをプラットフォームに転送します。
2. AIエージェントが最初の応答を送信します（例：チケットの受領確認や、詳細を確認するための質問など）。
3. 応答がサポートシステムのチケットに添付されます。
4. サポートチームはAIの回答内容を確認し、必要に応じて対応を引き継ぐことができます。

**この機能の利点：** 営業時間外であっても、顧客は即座に受領確認と初期サポートを受けることができます。

---

## トラブルシューティング

### プラットフォームでメッセージが受信されない場合

- APIキーが正しく、有効であることを確認してください（**設定 → 統合 → APIキー**を確認）。
- GETではなく、POSTリクエストを送信していることを確認してください。開発者であればその違いを理解しているはずです。
- `customData.body`フィールドが空でないか、空白のみでないことを確認してください。
- `customData.fromId`フィールドが含まれていることを確認してください。
- 応答メッセージを読み、具体的なエラーの詳細を確認してください。

### 返信がプラットフォームに届かない場合

- Channelsページの**カスタムチャネル**カードに、プラットフォームのURLが入力されていることを確認してください。URLが保存されていない場合、返信は生成・保存されますが送信はされません。また、その場合「失敗」とはマークされないため、まずここを確認してください。
- URLが公開されており（ログインやファイアウォールの背後にない）、成功の応答を返すことを確認してください。
- 返信（送信メッセージ）のみがURLに送信されます。受信メッセージはこれをトリガーしません。
- 受信トレイのメッセージでエラーの詳細を確認してください。

### 連絡先が作成されない場合

- 同じユーザーからのすべてのメッセージで、`fromId`の値が一貫していることを確認してください。プラットフォームはこの値を使用して連絡先を識別します。メッセージ間で値が変わると、プラットフォームは毎回新しい連絡先を作成してしまいます。
- 新しい連絡先からの最初のメッセージには、完全な連絡先レコードを作成するために`firstName`、`lastName`、`email`を含めてください。

### メディアの添付が機能しない場合

- ファイルリンク（URL）の場合、ファイルが公開されていること（アクセスにログインが不要であること）を確認してください。
- `mediaUrl` を含める場合は、必ず `mediaContentType` も含めてください。
- 埋め込みファイル（base64）の場合、形式が `data:MIME_TYPE;base64,ENCODED_DATA` であることを確認してください。
- 指定するファイルタイプが実際のファイル内容と一致していることを確認してください。

---

## ベストプラクティス

- **一貫した`fromId`値を使用する。** プラットフォーム上の各ユーザーは、常に同じ`fromId`を持つ必要があります。これにより、プラットフォームは重複した連絡先を作成することなく、すべてのメッセージを単一の会話にグループ化できます。
- **明確な`channel`名を選択する。** 受信トレイを表示したときにメッセージの送信元が簡単にわかるよう、`"website-chat"`、`"email"`、`"zendesk"`のような説明的な名前を選んでください。
- **連絡先詳細を含める。** 新しい連絡先からの最初のメッセージに連絡先詳細（`firstName`、`lastName`、`email`）を含めることで、すぐに完全で有用な連絡先レコードが作成されます。
- **リトライロジックを組み込む。** 最初の試行でプラットフォームが応答しない場合に備えて、メッセージの再送を行うようにプラットフォームを設定してください（ネットワークの一時的な不具合は発生し得るため）。
- **すべてのメッセージに一意の`messageSid`値を使用する。** これにより、システムが同じメッセージを複数回送信した場合でも、二重に処理されるのを防ぐことができます。
- **`campaignId`を使用してメッセージをルーティングする。** 複数のユースケース（例：販売に関する問い合わせとサポートに関する質問など）がある場合は、これを使用して異なるAIエージェントにメッセージを振り分けてください。
- **本番稼働前にテストする。** 実際のユーザーに公開する前に、双方向でテストメッセージを送信し、連絡先、会話、AIの応答がすべて正しく機能することを確認してください。