Customers and memory

以下のすべてのパスは Public API base URL に追加します。X-Api-Key を付け、JSON の書き込みには Content-Type: application/json も指定してください。スコープのない旧キーは拒否されます。これらのエンドポイントは Shopify customer ではなく Chatty の連絡先を管理します。

プロフィール一覧と詳細を取得する

どちらも customers:read、Pro / Plus が必要で、成功時は 200 を返します。リクエストボディはありません。

一覧のパラメーターは limit（既定 20）、after（前のページで最後に返った顧客の ID）、type、search（保存された email の前方一致）です。会話 API の paging.nextCursor ではなく pagination.hasNext を使います。次のページには最後の行の id を after で渡してください。検索は全プロフィール項目や旧メールフィールドを対象にせず、大文字・小文字の正規化も行いません。

一覧は少数の項目だけを返します。保存されている id、email（旧フィールドへのフォールバックあり）、firstName、lastName、shopifyId が対象です。他の項目は詳細を取得してください。詳細・作成・更新では id、shopifyId、name、firstName、lastName、email、phone、note、tags、type、createdAt、updatedAt を返せますが、未保存の項目は省略される場合があります。例では一部の項目だけを示しています。

顧客が存在しない、または別のストアに属する場合は 404 NOT_FOUND を返します。両方の読み取りに、認証、スコープ、バージョン、レート制限のエラーも適用されます。既存の GET /chat/customers/{customerUuid} はより多くの項目を持つ別の 顧客プロフィール を返します。両者のペイロードが同じだと仮定しないでください。

guest の連絡先を作成する

POST /customers — customers:write、Pro / Plus。

未知のフィールドは拒否します。name、type、Shopify ID は作成時の入力ではありません。表示用の name は名と姓から生成し、両方が空なら null、type は guest になります。

curl -X POST 'https://app.chatty.net/v1/customers' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","firstName":"Example","lastName":"Customer","tags":["vip"]}'

201 レスポンスの抜粋例：

{"data":{"id":"customer_123","email":"[email protected]","firstName":"Example","lastName":"Customer","name":"Example Customer","type":"guest","tags":["vip"]}}

タグはストアの顧客タグカタログにも登録します。通常の顧客作成トリガーから customer.created が発生します。Shopify への書き込みは行いません。

連絡先情報が不正または不足している場合は 400 VALIDATION_FAILED を返します。メールか電話が重複している場合は、error.existingId を含む 409 CUSTOMER_EXISTS を返します。

{"error":{"code":"CUSTOMER_EXISTS","message":"Customer already exists","existingId":"customer_123"}}

メールの重複確認は、入力をトリミングした元の値と小文字の値で検索します。大文字・小文字の組み合わせが異なる旧レコードは検出できない場合があります。既存 ID が返ったら再利用し、作成をむやみに繰り返さないでください。

プロフィールを更新する

PATCH /customers/{id} — customers:write、Pro / Plus。

書き込めるのは name、email、phone、note、tags だけです。変更する項目だけを送信してください。tags 配列は追加ではなく、その連絡先の保存済みタグを置き換えます。新しいカタログ項目が必要なら、別途 /customer-tags で登録してください。作成時の正規化、重複確認、検証が PATCH にも適用されるとは限りません。

curl -X PATCH 'https://app.chatty.net/v1/customers/customer_123' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example Customer","note":"Prefers email","tags":["vip","email-contact"]}'

200 の data に更新後の公開プロフィールを返します。例：{"data":{"id":"customer_123","name":"Example Customer","note":"Prefers email","tags":["vip","email-contact"]}}。未知または読み取り専用の項目は 403 FIELD_NOT_PERMITTED、連絡先が存在しないか別のストアに属する場合は 404 NOT_FOUND です。

監視対象のプロフィール変更では customer.updated が発生します。タグだけ、またはメモだけの変更では発生しません。

顧客を削除する

DELETE /customers/{id} — customers:write と conversations:delete の両方、Pro / Plus が必要です。ボディは不要です。

curl -X DELETE 'https://app.chatty.net/v1/customers/customer_123' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{"data":{"success":true}}

成功時は 200 です。どちらかのスコープが不足すると 403 FORBIDDEN、顧客が存在しないか別のストアに属する場合は 404 NOT_FOUND を返します。関連する会話の削除では空の data を持つ conversation.removed が発生します。customer.deleted Webhook はありません。削除完了後に繰り返すと 404 になります。

顧客タグ

顧客タグは、会話の /tags カタログとは別です。どちらのエンドポイントも Pro / Plus が必要です。

titles は配列で指定します。タイトルはトリミングと重複排除を行い、各 1–50 文字、1 リクエストで最大 100 種類です。不正なタイトルは 400 VALIDATION_FAILED を返します。カタログへの登録だけでは顧客に付きません。顧客に付けるにはプロフィールを PATCH してください。両方のエンドポイントに共通の認証、スコープ、レート制限エラーが適用されます。

顧客メモリを読み取る

GET /customers/{id}/memory — customers:read、Pro / Plus。ボディやページ分割パラメーターはありません。200 でプロフィールと、期限切れでない直近 20 件までの facts を新しい順に返します。会話要約の一覧は返しません。

curl 'https://app.chatty.net/v1/customers/customer_123/memory' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{
  "data": {
    "profile": null,
    "facts": [
      {"id":123,"fact":"Prefers email","factType":"preference","source":"manual","sourceConvoId":null,"expiresAt":null,"createdAt":"2026-10-01T12:00:00.000Z"}
    ]
  }
}

profile がある場合は summary、tags、avgSentiment、totalConversations、firstSeenAt、lastSeenAt を含みます。プロフィールがなければ null、facts がなければ facts: [] です。顧客が存在しないか別のストアに属する場合は 404 NOT_FOUND を返します。

fact を追加・更新・削除する

3 つとも customers:write、Pro / Plus が必要です。fact はストアと URL 内の顧客の両方に属している必要があり、別の顧客の fact は 404 NOT_FOUND になります。

fact は空白以外の内容を持ち、トリミング前で最大 500 文字です。factType は preference、size、behavior、demographic、issue、contact のいずれかです。POST で type を省略すると behavior になりますが、PUT では両方の項目が必須です。追加した fact の source は source: "manual" です。

作成時の ID、またはメモリの読み取りで返された ID を使ってください。fact ID は JavaScript の安全な整数範囲内の正の 10 進整数で、数字に他の文字を付けた値は拒否されます。不正な ID、テキスト、type は 400 VALIDATION_FAILED、顧客または fact がなければ 404 NOT_FOUND を返します。

会話の要約を削除する

DELETE /customers/{id}/memory/summaries/{conversationId} — customers:write、Pro / Plus。ボディは不要です。

curl -X DELETE 'https://app.chatty.net/v1/customers/customer_123/memory/summaries/conv_123' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

200 と {"data":{"id":"conv_123"}} を返します。削除するのは保存済みの要約で、会話やメッセージではありません。会話が同じ顧客・ストアに属し、要約が存在する必要があります。それ以外は 404 NOT_FOUND です。削除を繰り返した場合も 404 を返します。

メモリプロフィールの要約を再生成する

POST /customers/{id}/memory/regenerate — customers:write、Pro / Plus。ボディは不要です。共通 API 制限に加え、キーごとに 1 時間 10 回までです。

curl -X POST 'https://app.chatty.net/v1/customers/customer_123/memory/regenerate' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

生成を試みた後の保存済みプロフィールを 200 で返します。存在しなければ、例えば {"data":{"profile":null}} になります。項目は前述のメモリ読み取りと同じです。再生成には顧客の facts と会話要約を使います。すべての会話について要約を新規作成する操作ではありません。

元になる facts や要約がない場合、または新しい生成結果が得られなかった場合、以前のプロフィールか null が返ることがあります。200 は要約が変わった保証ではありません。顧客が存在しないか別のストアに属する場合は 404 NOT_FOUND、毎時上限を超えた場合は 429 RATE_LIMITED です。

顧客データをエクスポートする

どちらのルートにも customers:export、Pro / Plus が必要です。このスコープは独立しており、customers:write では付与されません。顧客データを Chatty の外に送る必要がある連携にだけ付与してください。

エクスポートはバックグラウンドで実行され、ストアのメールアドレスにメールで送信されます。宛先は選べません。ボディにフィールドがあると 400 VALIDATION_FAILED を返し、有効なメールアドレスがないストアは 400 VALIDATION_FAILED と Shop email is required を返します。レスポンスの宛先はマスクされて表示されます。queued: true はジョブがキューに登録されたことを示し、メールが送信されたことではありません。

• POST /customers/export は、すべての連絡先を 1 つの CSV で送信します。列は Type、First name、Last name、Email、Phone、Address、Customer since、Total order、Total spent、Total conversation、Conversation IDs、Tag、Note、Last updated です。ダウンロードリンクの有効期間は 1 日です。
• POST /customers/{id}/export は、1 人の顧客のプロフィール項目と、その会話のすべてのメッセージを送信します。列は Section、Reference、Time、Field、Value です。ダウンロードリンクの有効期間は 7 日です。存在しない顧客や他のストアの顧客は 404 NOT_FOUND を返します。

各ストアは、両方のルートと MCP を合わせて 1 時間に 10 回まで顧客データのエクスポートをリクエストできます。404 を含む失敗したリクエストも回数に含まれます。上限を超えると 429 RATE_LIMITED を返します。各リクエストは、呼び出したキーとともに監査ログに記録されます。

顧客からの正式なデータリクエストについては、Data and privacy に従ってください。

共通エラー

15 個のすべてのエンドポイントで、処理前に認証、スコープ、バージョン、レート制限を確認します。エラーは error.code と error.message を使い、重複作成の場合は error.existingId も返します。

ここには、全メモリを一括削除したり、プロフィール要約を直接編集したりする公開操作はありません。書き込みは認証済み API の操作主体とともに監査用に記録されますが、同じリクエストを繰り返しても結果が変わらない保証にはなりません。