カスタムチャネル

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

カスタムチャネルとは？

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

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

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

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

仕組み

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

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

受信メッセージ: 外部プラットフォームからWebアドレス（URL）へメッセージが送信されます。これは、プラットフォームが「メールボックス」にメッセージを「投稿」するようなものだと考えてください。
処理: プラットフォームは連絡先を作成または更新し、メッセージを保存します。また、（有効な場合は）AIエージェントが応答を生成します。
送信メッセージ: プラットフォームが返信を送信する際（AIによるものか、ユーザーが入力したものかにかかわらず）、そのメッセージはプラットフォーム上のURLに送信され、そこからシステムがエンドユーザーに配信します。返信にはファイルを含めることもできます。AIエージェントがメディアライブラリから送信するアイテム、インボックスからの添付ファイルやボイスメモ、あるいはAPI経由で送信されたファイルが、テキストの横にダウンロードリンクとして届きます。

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

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

メッセージの送信先

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

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

スコープ付きキーも使用できますが、読み取り専用ではなく、そのエリアに Messages が含まれている必要があります。メッセージはキーが属するアカウントに届くため、受信トレイで受け取る必要があるアカウント（またはサブアカウント）のキーを使用してください。

メッセージ形式

以下の形式（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`	いいえ	送信元のラベル（例: `"Facebook DMs"`, `"live-chat"`, `"my-crm"`）。チャットヘッダー、連絡先詳細、チャットリストのチャネルアイコン、通知メールにおいて、その連絡先のチャネル名として表示されます。これにより、1つのアカウントで複数のカスタムチャネルを簡単に区別できます。指定しない場合、連絡先は「Custom Channel」と表示されます。このラベルは連絡先が最初に作成されたときに保存され、アウトバウンドWebhookでは `channel` として返されるため、後から変更しても新しい連絡先にのみ適用されます。
`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 には絵文字のみを含めます。

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

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

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

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

返される内容

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

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

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

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

ステータスコード

コード	意味
`200`	成功 - メッセージを受信し、処理中です
`400`	リクエストに問題があります - 必須フィールドの欠落やメッセージ本文が空になっていないか確認してください
`401`	無効なAPIキー - Settings → Integrations → API Key でキーを再確認してください（取り消し済みまたは期限切れのスコープ付きキーも `401` になります）
`403`	スコープ付きキーが読み取り専用であるか、Messages が含まれていません
`405`	間違ったリクエストメソッド - GETではなくPOSTを使用していることを確認してください
`500`	プラットフォーム側で問題が発生しました - しばらくしてから再試行してください

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

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

このセクションでは、受信ファイル（プラットフォームからアプリへ）について説明します。返信とともに送信されるファイルについては、「ファイル付きの返信」を参照してください。

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

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

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

{
  "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形式）としてメッセージに直接埋め込むことができます。これは、システムがオンザフライでファイルを生成する技術的な統合において一般的です。プラットフォームは自動的にファイルをデコードして保存します。

{
  "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"
}

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

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

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

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

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

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

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

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

{
  "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",
  "mediaUrl": null,
  "mediaContentType": null,
  "mediaFileName": null,
  "isVoiceNote": false
}

各フィールドの意味

フィールド	内容
`contactId`	この連絡先に対するプラットフォームの内部ID
`messageId`	アプリ内でのこのメッセージの一意のID
`userId`	ユーザーID
`body`	返信テキスト。ファイルが添付されている場合はキャプションとなり、空の場合もあります。
`toId`	プラットフォーム上の連絡先ID（受信メッセージで送信した `fromId` と一致します）
`channel`	割り当てたカスタムチャネルラベル
`mediaUrl`	添付ファイルのダウンロードリンク。返信がテキストのみの場合は `null` となります。このリンクは1時間有効です。リンクを保存するのではなく、すぐにファイルをダウンロードしてください。
`mediaContentType`	添付ファイルのファイルタイプ（例: `"image/jpeg"`, `"application/pdf"`, `"audio/ogg"`）、または `null`。
`mediaFileName`	元のファイル名（例: `"Pricing.pdf"`）、または `null`。チャネルでドキュメントを名前で表示する場合に、表示名として使用してください。
`isVoiceNote`	添付ファイルがボイスメモとして記録された場合は `true` となり、チャネルが対応していればボイスメモとして配信できます。それ以外の場合は `false` です。

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

ファイル付きの返信

返信にファイルが含まれるのは、次のような場合です。

AIエージェントがメディアライブラリからアイテム（パンフレット、価格表、写真など）を送信したとき
インボックスで誰かがファイルを添付したり、ボイスメモを録音したりしたとき
API経由で mediaUrl および mediaContentType を含むメッセージが送信されたとき

ファイルはテキストと同じWebhook呼び出しで、上記の4つの media… フィールドに含まれて届きます。テキストのみの返信では、これらすべてが null に設定されます（また isVoiceNote は false になります）。そのため、body のみを読み取る受信側はそのまま動作し続けます。

{
  "contactId": "abc123",
  "messageId": "msg-789",
  "userId": "your-user-id",
  "body": "Here is our pricing breakdown.",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": "https://storage.googleapis.com/.../Pricing.pdf?X-Goog-Signature=...",
  "mediaContentType": "application/pdf",
  "mediaFileName": "Pricing.pdf",
  "isVoiceNote": false
}

mediaUrl を通常のGETリクエスト（ログインや追加ヘッダーは不要）で取得し、独自のチャネルを通じてエンドユーザーにファイルを渡してください。チャネルがサポートしている形式に合わせて、body をキャプションとして、または別のテキストメッセージとして配信してください。

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

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

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

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

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

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

送信先

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

メッセージ形式

{
  "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）は、受信メッセージの場合と同様に機能し、本プラットフォームが連絡先レコードを作成または更新するのに役立ちます。

返される内容

{
  "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エージェントが訪問者の質問に回答できるようにします：

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

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

メール

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

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

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

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

CRM統合

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

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

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

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

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

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

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

トラブルシューティング

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

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

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

「チャネル」ページの「カスタムチャネル」カードに、プラットフォームのURLが入力されていることを確認してください。URLが保存されていない場合、返信は生成・保存されますが送信されません。また、その状態では「失敗」とマークされないため、まずここを確認してください。
URLがパブリックにアクセス可能（ログインやファイアウォールの背後にない）であり、成功レスポンスを返すことを確認してください。
返信（送信メッセージ）のみがURLに送信されます。受信メッセージはこれをトリガーしません。
インボックスのメッセージでエラーの詳細を確認してください。
ファイル付きの返信は同じ呼び出しで届き、ダウンロードリンクは mediaUrl に含まれます。受信側が body のみを転送する場合、ファイルは破棄されます。media… フィールドも読み取るようにしてください（「ファイル付きの返信」を参照）。
mediaUrl のリンクは1時間後に期限切れになります。Webhookが届いたときにダウンロードし、後からキュー経由で取得しようとしないでください。

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

同じユーザーからのすべてのメッセージで、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の応答がすべて正しく機能することを確認してください。

カスタムチャネル #