連絡先識別子で会話を検索 | LiveDesk API 日本語

外部システムは、連絡先の業務識別子、メールアドレス、または完全な電話番号を使用して、その連絡先に関連付けられた通常会話の ID、作成時刻、および現在のステータスを検索できます。返された会話 ID は、会話の詳細やメッセージなど、既存の V2 API で直接使用できます。

リクエストメソッド

GET

リクエスト URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup

認証

この API は HTTP Basic 認証を使用します。リクエストヘッダーで Authorization を渡し、API キーをユーザー名、API シークレットをパスワードとして指定してください。認証情報に関連付けられたプロジェクトによって検索範囲が定義されるため、パスにプロジェクト ID を含める必要はありません。詳細は API Overview を参照してください。

リクエストに account_id が含まれる場合、その値は認証情報に関連付けられたプロジェクトと一致している必要があります。一致しない場合は 401 が返されます。

リクエスト

リクエスト例

curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

このコードブロックはフローティングウィンドウ内に表示されます

電話番号で検索する場合、+ は URL エンコードする必要があります。

GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

              
              GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

このコードブロックはフローティングウィンドウ内に表示されます

リクエストヘッダーパラメータ

フィールド	型	必須	説明
`Authorization`	string	Yes	`Authorization: Basic base64(API Key:API Secret)` を使用して認証します。API キーと API シークレットをコロンで連結し、その後 Base64 でエンコードします。

クエリパラメータ

フィールド	型	必須	説明
`type`	string	Yes	検索属性のタイプ。`identifier`、`email`、`phone` のみ使用できます。
`value`	string	Yes	`type` に対応する連絡先属性と完全一致する、空でない文字列です。
`page`	integer	No	正の整数です。デフォルトは `1` です。
`page_size`	integer	No	正の整数です。デフォルトは `20` です。`50` を超える値は `50` として扱われます。
`account_id`	integer	No	プロジェクト ID。通常は指定する必要はありません。指定する場合は、認証情報に関連付けられたプロジェクトと一致している必要があります。一致しない場合は `401` が返されます。

一致ルール

identifier: 大文字と小文字を区別します。元の値は保持され、部分一致やワイルドカード一致はサポートされません。
email: 前後の空白が削除され、メールアドレス形式が検証された後、大文字と小文字を区別しない完全一致が実行されます。
phone: まず前後の空白が削除されます。番号は完全な形式で、+ と国番号を含み、連絡先の phone_number の形式と一致している必要があります。API はデフォルトの国番号を補完せず、番号の下位桁による一致もサポートしません。
GET パラメータは正しく URL エンコードする必要があります。特に、電話番号内の + は %2B としてエンコードしてください。

検索範囲と並び順

連絡先および会話は、認証情報に関連付けられたプロジェクト内でのみ検索されます。API は、そのプロジェクト内のすべての受信トレイを対象に、連絡先に関連付けられたすべての通常会話（conversation_category=chat）を返します。チケット会話は除外され、現在のエージェント、担当者、または受信トレイによるフィルタリングは行われません。

すべてのステータスの通常会話が返されます（open、resolved、pending、snoozed、closed）。この API はステータスによるフィルタリングを提供しません。そのため、status が指定されても結果は絞り込まれません。

結果は、会話の作成時刻の降順で並べ替えられます。作成時刻が同じ場合は、内部の会話主キーの降順で並べ替えられます。データが変更されない限り、ページネーションの順序は安定しています。ページベースのページネーションでは、会話が同時に作成または削除されている間、一貫したスナップショットは保証されません。

レスポンス

成功レスポンス

HTTP 200:

{ "meta": { "count": 2, "current_page": 1, "page_size": 20, "total_pages": 1 }, "payload": [ { "id": 202609000000002, "created_at": 1788739200, "status": "closed", "inbox_id": 12, "contact_id": 901 }, { "id": 202609000000001, "created_at": 1788652800, "status": "open", "inbox_id": 10, "contact_id": 901 } ] }

              
              {
  "meta": {
    "count": 2,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1
  },
  "payload": [
    {
      "id": 202609000000002,
      "created_at": 1788739200,
      "status": "closed",
      "inbox_id": 12,
      "contact_id": 901
    },
    {
      "id": 202609000000001,
      "created_at": 1788652800,
      "status": "open",
      "inbox_id": 10,
      "contact_id": 901
    }
  ]
}

このコードブロックはフローティングウィンドウ内に表示されます

レスポンスパラメータ

フィールド	型	説明
`meta`	object	ページネーションのメタデータ。
`meta.count`	integer	一致した通常会話の総数です。すべてのステータスを含み、ページネーションの影響を受けません。
`meta.current_page`	integer	現在のページ番号。
`meta.page_size`	integer	1 ページあたりの実際の件数です。要求値が `50` を超える場合は `50` になります。
`meta.total_pages`	integer	総ページ数。結果がない場合は `0` です。
`payload`	array	現在のページの会話一覧。
`payload[].id`	integer	外部会話 ID、すなわち `conversations.display_id` です。会話の詳細やメッセージなど、既存の V2 API で直接使用できます。
`payload[].created_at`	integer	秒単位の Unix タイムスタンプで表した会話の作成時刻。
`payload[].status`	string	現在の会話ステータス。`open`、`resolved`、`pending`、`snoozed`、`closed` のいずれかです。
`payload[].inbox_id`	integer	関連する受信トレイの ID。
`payload[].contact_id`	integer	一致した連絡先の ID。

連絡先が存在しない場合、連絡先に通常会話がない場合、または要求されたページが総ページ数を超えている場合でも、HTTP 200 が返されます。いずれの場合も、payload は空の配列となり、meta.count には実際の総結果数が保持されます。

レスポンスには上記のフィールドのみが含まれ、メッセージ、添付ファイル、または個人の連絡先情報は返されません。

エラーレスポンス

エラーレスポンスは次の構造を使用します。エラーの説明には検索値は含まれません。

{ "error": "エラーの説明" }

              
              {
  "error": "エラーの説明"
}

このコードブロックはフローティングウィンドウ内に表示されます

HTTP ステータスコード	状況
`401`	認証情報が無効、無効化済み、または期限切れであるか、リクエスト内の `account_id` が認証情報に関連付けられたプロジェクトと一致していません。
`409`	履歴データにより、同一プロジェクト内で複数の連絡先が一致しました。API はそのうちの 1 件を任意に選択しないため、代わりに一意の `identifier` を使用して検索してください。
`422`	`type` が不足しているかサポートされていない、`value` が不足している、空白である、文字列ではない、または形式が正しくない、あるいはページネーションパラメータが正の整数ではありません。

使用上の注意

この API は検索機能のみを提供し、連絡先または会話データを変更しません。
API はあいまい一致による連絡先検索をサポートしていません。外部システムに保存されている identifier、メールアドレス、または電話番号が、LiveDesk 内の対応する連絡先属性と一致していることを確認してください。
検索結果内の会話を処理するには、対応する V2 API を呼び出す際に、レスポンス内の payload[].id を外部会話 ID として使用してください。