Session Link

開発者向け API

自社システムから顧客の会話への直接リンクを取得できます。顧客や会話がまだ存在しない場合は作成されます。

WhatsApp
Instagram
REST API

MonoStore からインストール monochat.ai で見る

概要

チャネルと顧客の電話番号またはメールアドレスを指定した 1 回の API 呼び出しで、MonoChat 内のその顧客の会話を開くリンクが返されます。顧客や会話がまだ存在しない場合は、作成されます。

このリンクを CRM、ヘルプデスク、注文画面に配置すると、チームはそこからチャットへ直接移動できます。

主な特長

開く、または作成。 特定の WhatsApp、Instagram などのチャネル上の顧客に対して、電話番号またはメールアドレスで利用できます。
通過中にルーティング。 同じ呼び出しで、会話を ID またはメールアドレスで担当者に、またはワークグループに割り当てます。
同じ顧客、同じ会話。 同じ顧客とチャネルで再度呼び出すと、既存の会話が返されます。

インストールと設定

設定 › MonoStore › アプリ から Session Link をインストールするか、インストールリンク app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA を開きます。MonoChat アカウントをお持ちでない場合は、リンクから先にサインアップすると、アプリが自動的にインストールされます。
プロフィール › APIトークン で API トークンを作成します。トークンは一度しか表示されないため、すぐにコピーしてください。APIトークンをご覧ください。
設定 › Session Link API を開きます。そこのドキュメントに、お客様のワークスペース固有のエンドポイントアドレスと、そのままコピーできるリクエスト例が表示されます。お客様のチャネルのいずれかで例を試します。
CRM、ヘルプデスク、注文画面に、API を呼び出して返された url を開く「WhatsApp でチャット」ボタンを追加します。

注記

このリンクは、ログイン済みでその会話の閲覧が許可されているユーザーに対して MonoChat を開きます。
この呼び出しは会話を開くだけで、顧客にメッセージは送信されません。先にメッセージを送る場合は WhatsApp Template API を使用してください。

機能

会話リンク

レスポンスには、MonoChat で会話を開くリンクと会話の ID が含まれます。

必要に応じて顧客を作成

送信した姓名で新しい顧客が作成され、その顧客がすでに登録済みだったかどうかもレスポンスで確認できます。

割り当て

ID またはメールアドレスで担当者に、またはワークグループに割り当てます。

ドキュメント画面

お客様のワークスペース固有のエンドポイントアドレスと、そのままコピーできるリクエスト例を含む API リファレンスです。

API リファレンス

この呼び出しは、JSON ボディを持つ POST リクエストで、API トークンで認証します。

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

<slug> はワークスペースのテナントスラッグで、MonoChat のアドレスのうち /tenants/ の後ろの部分です。
<app-folder> はアプリがインストールされたフォルダーです。設定 › Session Link API 画面に、両方が入力された完全なアドレスが表示されます。
トークンは プロフィール › APIトークン で作成します。APIトークンをご覧ください。

リクエストフィールド

フィールド	必須	説明
`connectorBrand`	はい	チャネルの種類（例：`whatsapp`、`instagram`）。
`channelUsername`	はい	MonoChat 内のチャネルのユーザー名（例：`+` を除いた WhatsApp 番号）。
`customer.identityType`	はい	`phoneNumber` または `email`。
`customer.identity`	はい	顧客の電話番号（国番号付き、`+` なし）またはメールアドレス。
`customer.firstname`, `customer.lastname`	いいえ	顧客が MonoChat に未登録の場合に使用されます。デフォルトは `-`。
`assignment.type`	いいえ	`agent`（担当者のユーザー ID）、`agentIdentity`（担当者のメールアドレス）、`workgroup`（ワークグループ ID）。
`assignment.value`	`assignment.type` を指定する場合は必須	会話の割り当て先の ID またはメールアドレス。

リクエスト例

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

レスポンス

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

フィールド	説明
`url`	MonoChat で会話を開きます。
`sessionId`	会話の ID。同じチャネル上の同じ顧客には、常に同じ会話が使われます。
`isOldUser`	この呼び出しで顧客が作成された場合は `false`。

エラー

呼び出しが失敗すると、エラーステータスとメッセージが返されます。

メッセージ	原因
`connectorBrand, channelUsername and customer fields are required`	必須の最上位フィールドが不足しています。
`customer.identityType must be one of: phoneNumber, email`	`identityType` が未指定、または別の値です。
`customer.identity field is required`	顧客の電話番号またはメールアドレスが指定されていません。
`Channel not found`	ワークスペースに、その種類とユーザー名のチャネルが存在しません。
`Customer Channel not found`	顧客をチャネル上の ID に対応付けできませんでした。
`Agent user not found`	`assignment.value` に指定されたメールアドレスの担当者が存在しません。
`401`	`Authorization` ヘッダーがないか、トークンが無効です。