Contacts API

コンタクトとは、メッセージをやり取りする個人のことで、名前、電話番号、メールアドレス、チャネル、タグ、カスタムフィールド、およびそのコンタクトが属するリストやキャンペーンなどが含まれます。Contacts APIを使用すると、ダッシュボードを使わずに、コンタクトの作成、検索、更新、タグ付け、一括インポート、削除を行うことができます。

このページのすべてのパスは、ベースURLからの相対パスです：

https://api.youraiconnector.com/v1

したがって、/contacts は https://api.youraiconnector.com/v1/contacts を意味します。

APIを初めてお使いですか？ まずAPIアクセスをお読みください。APIキーの生成方法、3つの認証方法、レート制限、エラー形式について説明しています。このページのすべての内容は、すでに有効なAPIキーをお持ちであることを前提としています。

コンタクトIDについて

すべてのコンタクトには一意のIDがあります。コンタクトを作成した際（data.contactId）に返されるIDは、他のすべての場所（コンタクトの取得、更新、タグ付け、メッセージ送信、削除など）で使用するIDと同じです。一度保存すれば、再利用可能です。

IDを取得するためにコンタクトを作成する必要はありません。電話番号やメールアドレスで検索する（コンタクトの取得を参照）、またはすべてのコンタクトをページ送りで確認する（コンタクトの一覧表示を参照）こともできます。いずれの場合も、同じIDが返されます。

コンタクトの作成

POST /contacts

アカウントに新しいコンタクトを追加します。国番号を含む電話番号が必須であり、メールアドレスのみでは不十分です。それ以外の項目はすべて任意です。

オプションとして、listId（単一のリスト）または listIds（配列）を使用して、新しいコンタクトを1つ以上のリストに直接追加できます。両方が送信された場合は、listIds が優先されます。

以下の連絡先の作成フィールドテーブルに記載されている標準的な作成フィールド（phoneNumber、firstName、lastName、email、channel、is_bot_active、is_private、lead_profile、listId、listIds、custom_fields）以外のフィールドを送信した場合、そのフィールドは自動的にカスタムフィールドとして保存されます。そのため、MakeやZapierのようなツールからのフラットなペイロードをネストせずにそのまま使用できます。明示的な custom_fields オブジェクトを渡すことも可能です。

フィールド	必須	説明
`phoneNumber`	はい	国番号を含むコンタクトの電話番号（例: `+15551234567`）。
`firstName`	いいえ	名。
`lastName`	いいえ	姓。
`email`	いいえ	メールアドレス。
`channel`	いいえ	メッセージングチャネル。`whatsapp`、`sms`、`whatsapp_web`のいずれか。デフォルトは `whatsapp`。
`is_bot_active`	いいえ	AIアシスタントがこのコンタクトに返信するかどうか。デフォルトは `true`。
`is_private`	いいえ	コンタクトをプライベートとしてマークします。`true`の場合、そのコンタクトに対してAIアシスタントはオフになります。デフォルトは `false`。
`lead_profile`	いいえ	リードに関する自由記述のメモ。
`listId`	いいえ	コンタクトを追加する単一のリストID。
`listIds`	いいえ	コンタクトを追加するリストIDの配列（`listId`よりも優先されます）。
`custom_fields`	いいえ	独自のキー/値フィールドのオブジェクト。これらはトップレベルのキーとして渡すこともできます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "is_bot_active": true,
    "listIds": ["list123", "list456"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+15551234567",
    firstName: "Jane",
    lastName: "Smith",
    email: "jane@example.com",
    is_bot_active: true,
    listIds: ["list123", "list456"],
  }),
});
const data = await res.json();
console.log(data.data.contactId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+15551234567",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "is_bot_active": True,
        "listIds": ["list123", "list456"],
    },
)
print(res.json()["data"]["contactId"])

レスポンス

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "contact_abc123",
    "listsAdded": ["list123", "list456"]
  }
}

新しい連絡先のIDは data.contactId にあります。追加されたリストは data.listsAdded にエコーバックされます。

重複は作成されません。 同じ電話番号を持つ連絡先が既に存在する場合、作成呼び出しによってその連絡先が作成されたり、返されたりすることはありません。レスポンスはHTTPステータス 200 とボディ内の error_code が 409 として返されるため、HTTPステータスではなく error_code で分岐処理を行ってください：
{ "success": false, "error_code": 409, "error": "A contact with this phone number already exists for the current user." }
error_code が 409 の場合に既存の連絡先を操作するには、電話番号またはメールアドレスによる連絡先の取得 — GET /contacts?phoneNumber=... — を使用して検索し、返されたIDを再利用してください。

WhatsAppの同等な表記は同一の番号としてカウントされます。 一部の国では、同じモバイル回線に対して2つの有効な表記が存在し、WhatsAppはいずれか一方を報告する場合があります。メキシコ（+52…およびレガシーな+521…）、ブラジル（9桁目の有無）、アルゼンチン（+54の後の9の有無）などがこれに該当します。作成時の重複チェックおよびGET /contacts?phoneNumber=は両方の表記で照合されるため、どちらの形式で送信しても既存の連絡先が返されます。連絡先に保存されているphone_numberが書き換えられることはありません。

電話番号またはメールアドレスによる連絡先の取得

GET /contacts?phoneNumber=... または GET /contacts?email=...

単一の連絡先を検索し、完全で詳細な連絡先オブジェクトを返します。これには、{ id, name } ペアに解決されたリスト、タグ、キャンペーン、および最後に行われたメッセージのやり取りが含まれます。

phoneNumber（国際形式）または email のいずれかを渡してください。どちらも渡さない場合、このエンドポイントは連絡先リストの取得モードに切り替わります。

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?phoneNumber=%2B15551234567&apiKey=YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551234567");
const res = await fetch(`https://api.youraiconnector.com/v1/contacts?phoneNumber=${phone}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"phoneNumber": "+15551234567"},
)
print(res.json()["contact"])

レスポンス

{
  "success": true,
  "contactId": "contact_abc123",
  "contact": {
    "id": "contact_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phoneNumber": "+15551234567",
    "channel": "whatsapp",
    "isBotActive": true,
    "isPrivate": false,
    "doNotDisturb": false,
    "lead_profile": null,
    "avatarUrl": "https://example.com/photo.jpg",
    "customFields": {},
    "lists": [{ "id": "list123", "name": "VIP customers" }],
    "tags": [{ "id": "tagHotLead", "name": "Hot lead" }],
    "campaigns": [{ "id": "campaign789", "name": "Spring promo" }],
    "currentCampaign": { "id": "campaign789", "name": "Spring promo" },
    "lastMessage": {
      "direction": "inbound",
      "body": "Sounds good, thanks!",
      "status": "received",
      "timestamp": "2026-06-09T10:21:00.000Z"
    }
  }
}

連絡先IDは、トップレベル (contactId) とオブジェクト内 (contact.id) の両方で返されます。一致するものがない場合は、{ "success": false, "message": "Contact not found" } を含む 404 が返されます。

avatarUrl は、連絡先がWhatsAppやMetaからメッセージを送信した際に取得されるプロフィール写真です。これは読み取り専用であり、設定することはできません。また、写真が設定されていない連絡先や、写真を共有しないチャネル経由で連絡してきた連絡先の場合は null となります。これらの写真リンクの一部は期限切れとなり自動的に更新されるため、リンクを保存するのではなく、一時的なものとして扱ってください。（以下のリストエンドポイントでは、同じ値が avatar_url と呼ばれます。）

URL内の電話番号について。 クエリ文字列内の + 記号は %2B としてURLエンコードする必要があります。そうしないとスペースとして読み取られます。上記の例ではこれを行っています。

IDで連絡先を取得する

GET /contacts/{contactId}

連絡先のIDがすでにわかっている場合は、直接取得できます。レスポンスの形式は上記の検索と同じです。

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["contact"])

アカウントに存在しない連絡先IDを指定すると、404が返されます。

コンタクトの統計を取得する

GET /contacts/{contactId}/stats

特定のコンタクトのメッセージ統計（合計、AI対人間の返信数、消費クレジット、最初/最後のメッセージのタイムスタンプ）を集計して返します。

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.totalMessages, data.creditsUsed);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["totalMessages"], data["creditsUsed"])

レスポンス

{
  "success": true,
  "totalMessages": 48,
  "sent": 21,
  "received": 27,
  "aiReplies": 18,
  "humanReplies": 3,
  "creditsUsed": 34,
  "botMessageCount": 18,
  "firstMessageAt": "2026-05-01T09:00:00.000Z",
  "lastMessageAt": "2026-06-09T10:21:00.000Z"
}

botMessageCount は、アプリ内の「リセット」ボタンでゼロにリセットされるAIメッセージカウンターと同じものです。creditsUsed は、この応答の数値だけでなく、そのコンタクトの累積クレジット合計です。アカウントに存在しないコンタクトIDを指定すると、404 が返されます。

連絡先を一覧表示する

GET /contacts

phoneNumberもemailも指定せずにGET /contactsを呼び出すと、すべての連絡先を新しい順にページングして取得できます。各ページには連絡先のコンパクトな概要（リスト、タグ、キャンペーンは完全なオブジェクトではなくID配列として返されます）とnext_cursorが含まれます。

クエリパラメータ	説明
`limit`	ページサイズ。デフォルトは50、最大100です。
`cursor`	前のページから取得した`next_cursor`の値。最初のページでは省略します。
`listId`	オプション。このリストに属する連絡先のみを返します。

すべてのページを順に取得するには、最初の呼び出しをカーソルなしで行い、その後は返されたnext_cursorをcursorとして渡し続けます。next_cursorがnullになったら停止してください。それが結果の終わりを意味します。

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&apiKey=YOUR_API_KEY"

# next page:
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&cursor=contact_abc123&apiKey=YOUR_API_KEY"

JavaScript

async function listAllContacts() {
  const all = [];
  let cursor = null;
  do {
    const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
    const data = await res.json();
    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);
  return all;
}

Python

import requests

def list_all_contacts():
    all_contacts = []
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
            headers={"X-API-Key": "YOUR_API_KEY"},
            params=params,
        )
        data = res.json()
        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]
        if not cursor:
            break
    return all_contacts

レスポンス

{
  "success": true,
  "contacts": [
    {
      "id": "contact_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "channel": "whatsapp",
      "is_bot_active": true,
      "is_private": false,
      "do_not_disturb": false,
      "avatar_url": "https://example.com/photo.jpg",
      "custom_fields": {},
      "created_at": "2026-06-01T09:00:00.000Z",
      "list_ids": ["list123"],
      "tag_ids": ["tagHotLead"],
      "campaign_ids": ["campaign789"],
      "current_campaign_id": "campaign789"
    }
  ],
  "next_cursor": "contact_abc123"
}

注: アカウントに存在しない listId でフィルタリングすると、404 が返されます。無効な cursor は 400 を返します。

コンタクトのカウント

GET /contacts/count

フィルタに一致するコンタクトの数と、チャネルごとの内訳を、ページングなしで取得します。ダッシュボードのタイル、自動化、Champへの問い合わせなど、「いくつあるか」を知りたいあらゆる場面でこの呼び出しを使用してください。すべてのフィルタはオプションであり、複数を組み合わせるとカウントが絞り込まれます（コンタクトは指定したすべての条件に一致する必要があります）。

クエリパラメータ	説明
`agentId`	このAIエージェントに割り当てられたコンタクトのみ。割り当てられたエージェントがいないコンタクト（チャネルのデフォルトエージェントが対応するもの）には `none` を渡します。
`channel`	このチャネル上のコンタクトのみ（例: `whatsapp`, `messenger`, `instagram`, `sms`, `email`, `chat_widget`）。
`tag`	このタグを持つコンタクトのみ（タグの名前で指定、大文字・小文字は区別されません）。存在しないタグ名を指定すると `404` が返されます。
`listId`	このリスト上のコンタクトのみ。
`botActive`	`true` または `false` — AIアシスタントがオン、またはオフになっているコンタクトのみ。
`status`	このステータスのコンタクトのみ（例: `Lead`）。
`rules`	スマートリストと同じ形式のURLエンコードされたJSONルールオブジェクト（後述の「`smart_rules`の形式」を参照）。他のフィルタと組み合わせることはできません。

フィルタを何も送信しない場合、アカウント上のコンタクトの総数が返されます。

cURL

# everything
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?apiKey=YOUR_API_KEY"

# only the contacts one agent handles on Messenger
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?agentId=agent_xyz789&channel=messenger&apiKey=YOUR_API_KEY"

JavaScript

const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count");
url.searchParams.set("agentId", "agent_xyz789");
url.searchParams.set("channel", "messenger");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await res.json();
console.log(data.total);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agentId": "agent_xyz789", "channel": "messenger"},
)
data = res.json()
print(data["total"])

レスポンス

{
  "success": true,
  "total": 3423,
  "by_channel": { "messenger": 2744, "instagram": 667, "none": 12 },
  "filters": { "agentId": "agent_xyz789" }
}

by_channel は同じ合計数をチャネルごとに分割します。どのチャネルにも属さないコンタクトは none にカウントされます。filters は適用されたフィルタをそのまま返すため、呼び出しが意図通りに行われたかを確認できます。

注意: rules を他のフィルタと一緒に送信したり、有効なJSONではない rules 値を送信したりすると、400 が返されます。アカウントに存在しないタグ名やリストIDを指定すると 404 が返されます。

連絡先の更新

PUT /contacts/{contactId}

既存の連絡先を更新します。含めたフィールドのみが変更されます。変更したくないフィールドは除外してください。少なくとも1つのフィールドを送信する必要があります。そうしないと、400（「更新するフィールドがありません」）が返されます。

フィールド	説明
`firstName`	名（ファーストネーム）。
`lastName`	姓（ラストネーム）。
`email`	メールアドレス。
`is_bot_active`	AIアシスタントがこの連絡先に返信するかどうか。
`is_private`	非公開に設定します。`true`に設定すると、AIアシスタントもオフになります。
`do_not_disturb`	この連絡先への自動アウトリーチを一時停止します。AIの返信も停止します。
`follow_ups_disabled`	この連絡先に対するすべての自動フォローアップ（クイック、サイクル、コールドリード）を停止します。ただし、相手から送信されたメッセージへのAIによる返信は継続されます。購入済みの場合などに便利です。`false`に戻すまでオフのままになります。
`lead_profile`	リードに関する自由記述のメモ。
`custom_fields`	カスタムフィールドのオブジェクト。キーごとにマージされます。送信したキーのみが書き込まれ、既存のカスタムフィールドの残りは保持されます。カスタムフィールドのキーをトップレベルで渡すことも可能です。

cURL

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Jane", "do_not_disturb": true }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ firstName: "Jane", do_not_disturb: true }),
});
const data = await res.json();
console.log(data.message);

Python

import requests

res = requests.put(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"firstName": "Jane", "do_not_disturb": True},
)
print(res.json()["message"])

レスポンス

{
  "success": true,
  "message": "Contact updated successfully"
}

カスタムフィールドは置換ではなくマージされます。 { "custom_fields": { "tier": "gold" } } を送信すると tier のみが設定され、連絡先の他のカスタムフィールドはそのまま維持されます。すべての連絡先からカスタムフィールドを完全に削除するには、カスタムフィールドの削除を使用してください。

タグの追加または削除

POST /contacts/{contactId}/tags

1回の呼び出しで、単一の連絡先に対してタグの追加や削除を行います。addTagIds と removeTagIds にタグの ID を渡します。両方のうち少なくとも1つは空であってはなりません。

タグはあらかじめアカウントに存在している必要があります。タグエンドポイントから先に作成してください。連絡先または参照されたタグが存在しない場合、404 が返されます。

フィールド	説明
`addTagIds`	コンタクトに追加するタグIDの配列。
`removeTagIds`	コンタクトから削除するタグIDの配列。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    addTagIds: ["tagHotLead"],
    removeTagIds: ["tagColdLead"],
  }),
});
const data = await res.json();
console.log(data.added, data.removed);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"]},
)
data = res.json()
print(data["added"], data["removed"])

レスポンス

{
  "success": true,
  "contact_id": "contact_abc123",
  "added": 1,
  "removed": 1
}

タグライブラリを管理する

これらのエンドポイントは、コンタクトへのタグの適用や削除（上記のタグの追加または削除を参照）とは異なり、アカウント上のタグそのものの名前変更や削除を行います。アカウント上のすべてのタグにはID（tagId）があります。これはダッシュボードのタグマネージャーに表示されるIDであり、POST /tags と { "name": "..." } のJSONボディ（phoneNumber、email、または contactId は不要）を使用してタグを作成した際に data.tag_id として返されるIDです。

タグを更新する

PUT /tags/{tagId}

変更するフィールドのみを送信してください。

フィールド	説明
`name`	タグの名前。

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagHotLead?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot lead (Q3)" }'

レスポンス

{ "success": true, "tag_id": "tagHotLead" }

アカウントに存在しない tagId を指定すると、404 が返されます。

タグを削除する

DELETE /tags/{tagId}

IDを指定してタグを1つ削除します。この操作は取り消せません。そのタグが付与されていたコンタクトからはタグが削除されます。すでに存在しない（または最初から存在しなかった）タグを削除しようとした場合、列挙するものがないため、404 ではなく deleted: 0 を含む 200 が返されます。

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagColdLead?apiKey=YOUR_API_KEY"

レスポンス

{ "success": true, "deleted": 1 }

複数のタグを一度に削除する

DELETE /tags

フィールド	説明
`tagIds`	削除するタグIDの配列（最大1000個）。

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagIds": ["tagColdLead", "tagUnsubscribed"] }'

レスポンス

{ "success": true, "deleted": 2 }

存在しないIDや別のアカウントに属するIDは、エラーにならずにスキップされ、deletedにはカウントされません。

フラグの一括設定

POST /contacts/bulk-flag

一度に多数のコンタクトに対して1つのブール値フラグを設定します。リクエストごとに最大500件のコンタクトIDを指定できます。アカウントに存在しないIDはスキップされ、skipped にカウントされます。

フィールド	説明
`contactIds`	更新するコンタクトIDの配列（最大500件）。
`field`	設定するフラグ。`bot_active`（AIアシスタントのオン/オフ）、`dnd`（自動アウトリーチの一時停止）、`spam`、`private` のいずれか。
`value`	フラグに設定するブール値。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["contactId1", "contactId2"],
    "field": "bot_active",
    "value": false
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactIds: ["contactId1", "contactId2"],
    field: "bot_active",
    value: false,
  }),
});
const data = await res.json();
console.log(data.updated, data.skipped);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactIds": ["contactId1", "contactId2"],
        "field": "bot_active",
        "value": False,
    },
)
data = res.json()
print(data["updated"], data["skipped"])

レスポンス

{
  "success": true,
  "updated": 2,
  "skipped": 0
}

コンタクトの一括インポート

POST /contacts/import

JSON配列から1回の呼び出しで最大500件の連絡先を作成します。各レコードには国際形式の phone_number が必要です。それ以外の項目は任意です。電話番号が無効なレコードやサポートされていないチャネルのレコードはスキップ（作成されません）されます。スキップされたすべてのレコードは、インデックスと理由とともに報告されるため、失敗したレコードのみを修正して再試行できます。

アカウントに既に存在する電話番号は、デフォルトで duplicate としてスキップされます。updateExisting: true を送信すると、代わりにそれらの連絡先を更新できます。レコードに存在するフィールドが連絡先の情報を上書きし（first_name、last_name、email、lead_profile、および custom_fields はキーごとにマージされます）、tags が追加され、連絡先が listId に追加されます。既存の連絡先のチャネル、電話番号、ボットフラグは変更されません。

オプションで、インポート（または更新）されたすべての連絡先を listId を使用してリストに追加したり、指定のないレコードに対して defaultChannel を設定したり、tags を使用してレコードにタグ付けしたりできます（タグ名。存在しないタグは作成され、既存のタグは大文字と小文字を区別せずに照合されます）。

トップレベルフィールド

フィールド	必須	説明
`contacts`	はい	連絡先レコードの配列（最大500件）。
`listId`	いいえ	インポート（および更新）されたすべての連絡先を追加するリスト。アカウント上のリストである必要があります。
`defaultChannel`	いいえ	`channel` を省略したレコードに適用されるチャネル。`whatsapp`、`sms`、`whatsapp_web` のいずれか。デフォルトは `whatsapp` です。
`updateExisting`	いいえ	電話番号が既に存在する場合に、`duplicate` としてスキップする代わりに連絡先を更新するには `true` を指定します。デフォルトは `false` です。

レコードごとのフィールド

フィールド	必須	説明
`phone_number`	はい	国際形式の電話番号（不足している場合は先頭に `+` が追加されます）。
`first_name`	いいえ	名。
`last_name`	いいえ	姓。
`email`	いいえ	メールアドレス。
`channel`	いいえ	`whatsapp`、`sms`、`whatsapp_web` のいずれか。`defaultChannel` にフォールバックします。
`is_bot_active`	いいえ	AIアシスタントが返信するかどうか。デフォルトは `true` です。
`is_private`	いいえ	非公開にするかどうか。デフォルトは `false` です。
`lead_profile`	いいえ	フリーテキストのリードメモ。
`custom_fields`	いいえ	カスタムフィールドのキーと値のオブジェクト。
`tags`	いいえ	タグ名の配列（単一の `"a; b"` 文字列も使用可能）。存在しないタグは作成され、既存のタグは大文字と小文字を区別せずに照合されます。1レコードにつき最大25個まで。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"] },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "listId": "list123",
    "defaultChannel": "whatsapp_web",
    "updateExisting": true
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee", tags: ["vip", "newsletter"] },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    listId: "list123",
    defaultChannel: "whatsapp_web",
    updateExisting: true,
  }),
});
const data = await res.json();
console.log(`Imported ${data.imported}, updated ${data.updated}, skipped ${data.skipped.length}`);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"]},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "listId": "list123",
        "defaultChannel": "whatsapp_web",
        "updateExisting": True,
    },
)
data = res.json()
print(f"Imported {data['imported']}, updated {data['updated']}, skipped {len(data['skipped'])}")

レスポンス

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contact_abc123", "contact_def456"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": []
}

一部のレコードが作成できない場合、その理由とともに skipped に表示されます（ここでは updateExisting がないため、既存の番号はスキップされます）。

{
  "success": true,
  "imported": 1,
  "contact_ids": ["contact_abc123"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": [
    { "index": 1, "phone_number": "+12025551235", "reason": "duplicate" }
  ]
}

updateExisting: true を使用すると、同じリクエストで既存の連絡先が updated / updated_contact_ids として報告されます。

スキップされる理由：invalid_record、missing_phone_number、invalid_phone_number、invalid_channel、duplicate_in_request、duplicate、contact_limit_reached、create_failed。

プランの制限。 プランの連絡先上限によりこれほど多くの新規連絡先を作成できない場合、リクエスト全体が事前に403で拒否されます。途中で上限に達した場合、残りのレコードは理由contact_limit_reachedとしてスキップされた状態で返されます。

CSVファイルから連絡先をインポートする

一括インポートでサポートされている件数（最大約50,000行）を超えるインポートを行う場合は、アカウントのストレージに保存済みのCSVファイルに対して非同期インポートジョブをキューに入れ、完了するまでポーリングしてください。

インポートを開始する

POST /contacts/import-csv

フィールド	必須	説明
`csvStoragePath`	はい	`users/{your account id}/imports/`配下にある、`.csv`で終わるCSVファイルのストレージパス。
`listName`	はい	この名前のリストを作成（または再利用）し、インポートされたすべての連絡先を追加します。
`existingListRefs`	いいえ	インポートされたすべての連絡先を追加する既存のリストIDの配列。
`defaultChannel`	いいえ	指定がない行に適用されるチャネル。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csvStoragePath": "users/abc123/imports/leads.csv",
    "listName": "Webinar signups"
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    csvStoragePath: "users/abc123/imports/leads.csv",
    listName: "Webinar signups",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "csvStoragePath": "users/abc123/imports/leads.csv",
        "listName": "Webinar signups",
    },
)
job_id = res.json()["job_id"]

レスポンス (202 — インポートはキューに入れられましたが、まだ完了していません)

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "queued"
}

ストレージへのファイル配置について。 このエンドポイントはインポートジョブを開始および追跡するものであり、アップロード自体を受け付けるものではありません。このエンドポイントを呼び出す前に、CSVファイルがすでにcsvStoragePathに配置されている必要があります。ダッシュボードのCSVインポーターは、最初のステップとしてこれを行います。

インポートジョブをポーリングする

GET /contacts/import-csv/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv/csvimp_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "completed",
  "imported": 812,
  "updated": 0,
  "skipped": 14,
  "errors": [],
  "error_message": null
}

statusは、queued → processing → completedの順に遷移するか、error_messageに理由が示されてfailedとなります。アカウントに存在しないjobIdを指定すると、404が返されます。

連絡先をエクスポートする

連絡先の非同期CSVエクスポートを開始し、完了までポーリングするためのジョブを返します。

エクスポートを開始する

POST /contacts/export

フィールド	必須	説明
`listId`	いいえ	このリストに属する連絡先のみをエクスポートします。
`contactIds`	いいえ	指定した特定の連絡先IDのみをエクスポートします。

両方を指定しない場合は、アカウント上のすべての連絡先がエクスポートされます。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": "list123" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ listId: "list123" }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"listId": "list123"},
)
job_id = res.json()["job_id"]

レスポンス (202 — エクスポートがキューに入れられました)

{
  "success": true,
  "job_id": "export_abc123",
  "status": "queued"
}

エクスポートジョブをポーリングする

GET /contacts/export/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export/export_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "job_id": "export_abc123",
  "status": "completed",
  "export_id": "exp_xyz789",
  "contact_count": 812,
  "error_message": null
}

status が "completed" になると、export_id と contact_count が送信されます。生成されたCSVファイルのダウンロードは、ダッシュボードの「エクスポート」ページから行います。

連絡先にメッセージを送信する

POST /contacts/{contactId}/send-message

既存の連絡先が現在利用しているチャネルに対してメッセージを送信します。メッセージはキューに入れられ、バックグラウンドで配信されます。レスポンスはメッセージが受け付けられたことを示すものであり、配信が完了したことを示すものではありません。

フィールド	必須	説明
`body`	はい	送信するメッセージのテキスト。
`mediaUrl`	いいえ	添付するメディアファイルのURL。
`mediaContentType`	いいえ	添付メディアのMIMEタイプ（例: `image/jpeg`）。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hi! Your appointment is confirmed." }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Hi! Your appointment is confirmed." }),
});
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"body": "Hi! Your appointment is confirmed."},
)
print(res.json()["messageId"])

レスポンス

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact_abc123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

今すぐ送信できませんか？ 連絡先が「おやすみモード」や「プライベートモード」を有効にしている場合、またはアウトバウンドメッセージを受信できないチャネルを使用している場合、リクエストは 422 と説明用の error を伴って拒否されます。

連絡先IDではなく、電話番号、Instagram ID、またはその他のチャネル識別子を使用して送信する場合、およびメッセージング全般の詳細については、Messages API を参照してください。

AIエージェントを連絡先に割り当てる

POST /contacts/{contactId}/assign-agent

既存の会話を、次のメッセージから別のAIエージェントに引き継ぎます。これはチャットメニューの AIエージェントを割り当てる と同じ機能であり、オートメーションの AIエージェントまたはキャンペーンを割り当てる アクションで使用されるステップと同じです。

フィールド	必須	説明
`agentId`	はい	引き継ぎを行うAIエージェントのID、または割り当てを解除して会話をチームの受信トレイに戻すための `null` を指定します。
`triggerAIResponse`	いいえ	`true` を指定すると、新しく割り当てられたエージェントが連絡先の未回答の最新メッセージに即座に返信します。デフォルトは `false` です。

triggerAIResponse: true には注意してください — コンタクトに対してその場でメッセージを送信するため、今すぐメッセージを送りたい場合にのみ使用してください。MessengerやInstagramでは、コンタクトからの最後のメッセージから24時間以上経過している場合、メッセージの送信は失敗します。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "agent_xyz789" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agentId: "agent_xyz789" }),
});
const data = await res.json();
console.log(data.data.agentId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agentId": "agent_xyz789"},
)
print(res.json()["data"]["agentId"])

レスポンス

{
  "success": true,
  "data": {
    "contactId": "contact_abc123",
    "agentId": "agent_xyz789",
    "aiResponseTriggered": false
  }
}

エージェントは連絡先と同じアカウントに属している必要があります。そうでない場合、リクエストは 404 または 403 で拒否されます。エージェントIDは「AIエージェント」ページで確認できます（各エージェントのURLの末尾がIDになっています）。

多数のコンタクトへのAIエージェントの割り当て

POST /contacts/bulk-assign-agent

1回の呼び出しで多数の会話を別のAIエージェントに移動するか、null を使用してすべての割り当てを解除します。これは純粋なルーティングの変更であり、メッセージは送信されず、エージェントが誰かに返信することもありません。各コンタクトは、次にメッセージを送信した際に新しいエージェントが割り当てられます（そのため、ここには triggerAIResponse がありません）。

フィールド	必須	説明
`agentId`	はい	引き継ぐAIエージェント、または割り当てを解除するための `null`。
`contactIds`	3つのうち1つ	移動する最大500件のコンタクトID。
`filter`	3つのうち1つ	コンタクトをリストアップする代わりに、サーバー上で新しい順に選択します。カウントエンドポイントのフィルタと同じキーを使用します: `agentId` (または `none`), `channel`, `tag`, `listId`, `botActive`, `status`。
`rules`	3つのうち1つ	スマートリストのルールオブジェクト — 「`smart_rules`の形式」を参照してください。
`limit`	いいえ	`filter` または `rules` で選択した際に、この呼び出しで移動するコンタクトの数。1〜500で、デフォルトは500です。

contactIds、filter、rules のいずれか1つを正確に送信してください。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "filter": { "agentId": "agent_abc123", "channel": "messenger" }
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "agent_xyz789",
    filter: { agentId: "agent_abc123", channel: "messenger" },
  }),
});
const data = await res.json();
console.log(data.updated, data.remaining);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agentId": "agent_xyz789",
        "filter": {"agentId": "agent_abc123", "channel": "messenger"},
    },
)
data = res.json()
print(data["updated"], data["remaining"])

レスポンス

{
  "success": true,
  "agentId": "agent_xyz789",
  "matched": 3415,
  "updated": 500,
  "skipped": 0,
  "remaining": 2915,
  "filters": { "agentId": "agent_abc123" }
}

matched は選択によって見つかったコンタクトの総数、updated はこの呼び出しで移動された数、skipped は送信したIDのうちアカウントで見つからなかった数、remaining はこの呼び出し完了時点で条件に一致している残りの数です。

全員の移動について。 1回の呼び出しで移動できるのは最大500件のコンタクトであるため、大規模なグループの場合は数回の呼び出しが必要です。移動したコンタクトが条件に一致しなくなるようなフィルタ（例: agent_xyz789 に割り当てながら filter: { "agentId": "agent_abc123" } を使用するなど）を使用し、remaining が 0 として返されるまで全く同じ呼び出しを繰り返してください。contactIds を渡した場合、remaining は常に 0 になります。

連絡先を部門に割り当てる

POST /contacts/{contactId}/department

「このリードを営業に割り当てる」は、連絡先を指定した部門に登録し、デフォルトではその部門内で現在最も連絡先が少ない担当者に割り当てます。これはAIエージェントの割り当てとは別物です。部門は「どのチームが担当するか」を決定し、エージェントは「どのAIが対応するか」を決定します。一方を設定しても、もう一方がクリアされることはありません。

フィールド	必須	説明
`department_id`	はい	連絡先を登録する部門。クリアするには `null` を渡します。
`hand_to_member`	いいえ	その部門で最も負荷の低い担当者にも連絡先を割り当てます。デフォルトは `true` です。すでに担当者がいる連絡先を再割り当てすることはありません。

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department_id": "dept_sales" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ department_id: "dept_sales" }),
});
const data = await res.json();
console.log(data.assigned_to);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"department_id": "dept_sales"},
)
print(res.json()["assigned_to"])

レスポンス

{
  "success": true,
  "department_id": "dept_sales",
  "assigned_to": "member_uid_123"
}

連絡先がすでに誰かに割り当てられている場合、または hand_to_member: false を渡した場合、assigned_to は null になります。

チャネル間で連絡先をリンクする

「WhatsAppで継続」（またはSMS）は、別の電話ベースのチャネルでその人物の連絡先を検索または作成し、両者をリンクします。これにより、アプリの他の部分で同一人物として認識されるようになります。

別のチャネルへのリンク

POST /contacts/{contactId}/link-channel

フィールド	必須	説明
`channel`	はい	リンク先のチャネル。`whatsapp`、`whatsapp_web`、`sms` のいずれか。
`phoneNumber`	いいえ	新しいチャネルで使用する電話番号。デフォルトはソース連絡先自身の番号です。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link-channel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms" }'

レスポンス

{
  "success": true,
  "data": {
    "contact_id": "contact_def456",
    "person_id": "person_xyz789",
    "created": true
  }
}

created は、ターゲットチャネル用に新しい連絡先が作成されたか、既存の連絡先が見つかってリンクされたかを示します。これを2回呼び出しても安全です。重複を作成するのではなく、同じ contact_id を created: false とともに返します。

422 は、現在アカウントがこのリンクを実行できないことを意味します。連絡先がすでにそのチャネルファミリーに存在している、使用する電話番号がない、またはターゲットチャネルに接続された送信者が存在しない場合です。 409 は、2つの連絡先がすでに別々の人物にリンクされていることを意味します。先に一方のリンクを解除してください。

連絡先のリンク済み会話を一覧表示する

GET /contacts/{contactId}/linked

この連絡先と同一人物である他の会話を返します。リンクされていない連絡先は 404 ではなく空の配列を返します。「この人物には他のチャネルがない」というのは正常な状態です。

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/linked?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "data": [
    {
      "contact_id": "contact_def456",
      "channel": "sms",
      "custom_channel": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+15551234567",
      "last_message": "Sounds good, thanks!",
      "last_message_timestamp": "2026-06-09T10:21:00.000Z",
      "linked_from": {
        "contact_id": "contact_abc123",
        "channel": "whatsapp",
        "linked_at": "2026-06-01T09:00:00.000Z",
        "reason": "continue_on_channel"
      }
    }
  ]
}

連絡先のリンクを解除する

DELETE /contacts/{contactId}/link

この連絡先をその人物から一方的に削除します。その人物にリンクされている他の連絡先はリンクを維持するため、3つのうち1つのリンクを解除してもグループが解散されることはありません。

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link?apiKey=YOUR_API_KEY"

レスポンス

{ "success": true }

連絡先のプロフィール画像を取得する

POST /contacts/{contactId}/profile-pic

連絡先のWhatsAppまたはMetaのプロフィール写真をオンデマンドで取得（およびキャッシュ）します。これは連絡先の取得でavatarUrlとして返される写真と同じもので、更新された状態のものです。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/profile-pic?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "avatar_url": "https://example.com/photo.jpg",
  "cached": false
}

cached: true は、URLがプロバイダーへの新規ルックアップではなく、最近の取得から得られたものであることを意味します。写真は7日間キャッシュされ、プロバイダーが到達可能な写真がないと報告した連絡先は、24時間「利用不可」としてキャッシュされます。取得する写真がない場合、avatar_url は省略され、message にその理由が説明されます。

AIによる連絡先の自動タグ付け

アカウントのタグ付けルールを1つ以上の連絡先の全会話履歴に対して実行し、ライブチャット中に実行されるリアルタイムのタグ付けとまったく同じようにタグを適用（または削除）します。ルールやタグごとのクレジットコストも同様です。

実行を開始する

POST /contacts/auto-tag

フィールド	必須	説明
`scope`	はい	特定の連絡先にタグを付ける場合は `"contacts"` を、1つのAIエージェントが現在処理しているすべての会話にタグを付ける場合は `"agent"` を指定します。
`contact_ids`	`scope` が `"contacts"` の場合に必須	連絡先IDの配列（1〜500個）。
`agent_id`	`scope` が `"agent"` の場合に必須	タグ付け対象の会話を持つAIエージェント。`scope` が `"contacts"` の場合、これはオプションとなり、実行するエージェントのタグ付けルールを絞り込むために使用されます。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "contacts", "contact_ids": ["contact_abc123", "contact_def456"] }'

単一の連絡先はインラインで実行され、結果がすぐに返されます：

{ "success": true, "result": { "tags_applied": 2, "tags_removed": 0 } }

2つ以上の連絡先（または scope: "agent"）はバックグラウンドジョブとして実行され、すぐに 202 が返されます：

{ "success": true, "run_id": "m1x2y3-a1b2c3d4", "total": 214 }

実行状況をポーリングする

GET /contacts/auto-tag/run

アカウントの現在（または最新）の実行状況を返します。これにより、run_id を自分で追跡することなく進捗状況をポーリングできます。

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag/run?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "run": {
    "run_id": "m1x2y3-a1b2c3d4",
    "status": "running",
    "total": 214,
    "processed": 58,
    "tagged_contacts": 12,
    "tags_applied": 15,
    "tags_removed": 2,
    "credits_charged": 15
  }
}

アカウントで一度も実行が開始されていない場合、run は null になります。status は "running" から "completed" または "failed" へと移行します。

アカウントごとに一度に実行できるバルク実行は1つだけです。別の実行中に2つ目を開始すると、409 とともに error_code: "auto_tag_run_in_progress" が返されます。単一連絡先の実行でクレジットが不足すると、402 とともに error_code: "insufficient_credits" が返されます。一方、バルク実行の場合は途中で停止し、run にどこまで完了したかが報告されます。

連絡先を削除する

DELETE /contacts/{contactId}

IDを指定して連絡先を1件、メッセージ履歴とともに完全に削除します。この操作は取り消せません。 複数の連絡先を1回の呼び出しで削除するには、以下の連絡先を削除を使用してください。

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

レスポンス

{
  "success": true
}

アカウントに存在しない、または別のアカウントに属するコンタクトIDは、404を返します。

連絡先の削除

DELETE /contacts

1回の呼び出しで、IDを指定して1つ以上の連絡先を完全に削除します（最大500件まで）。アカウントに存在しないIDはスキップされ、skipped にカウントされます。この操作は元に戻せません。

フィールド	説明
`contactIds`	削除する連絡先IDの配列（最大500件）。

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contactId1", "contactId2"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ contactIds: ["contactId1", "contactId2"] }),
});
const data = await res.json();
console.log(`Deleted ${data.deleted}, skipped ${data.skipped}`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contactId1", "contactId2"]},
)
data = res.json()
print(f"Deleted {data['deleted']}, skipped {data['skipped']}")

レスポンス

{
  "success": true,
  "deleted": 2,
  "skipped": 0
}

カスタムフィールドの削除

DELETE /contacts/custom-fields/{fieldKey}

アカウント内のすべての連絡先から、指定したカスタムフィールドキーを削除します。カスタムフィールドの名前変更や廃止後の整理にご利用ください。キーには英数字、アンダースコア、ハイフンのみを使用できます。更新された連絡先の数が返されます。この操作は取り消せません。

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(`Removed from ${data.updated} contacts`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(f"Removed from {res.json()['updated']} contacts")

レスポンス

{
  "success": true,
  "updated": 42
}

注: サポートされていない文字を含むフィールドキーは、400 を返します。

リストは連絡先をグループ化するものです。リストには静的（ユーザーがメンバーを決定する）なものと、スマート（ルールに基づいてメンバーが計算され、自動的に最新の状態に保たれるもの。詳細はリストと連絡先の整理を参照）なものがあります。

フィールド	説明
`name`	作成時に必須。最大100文字。
`status`	`live`（デフォルト）または `draft`。小文字。
`contact_ids`	リストに追加する連絡先IDの配列。静的リストのみ。
`type`	`static`（デフォルト）または `smart`。
`smart_rules`	ルールセット。`type` が `smart` の場合に必須。以下を参照。

リストを作成する

POST /lists

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Hot leads (active)",
        "type": "smart",
        "smart_rules": {
          "match": "all",
          "conditions": [
            { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
            { "field": "last_activity_at", "op": "within_last", "value": { "amount": 90, "unit": "days" } }
          ]
        }
      }'

レスポンス

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 3, "removed": 0, "total": 3 }
}

スマートリストは同じリクエスト内でインラインで評価されるため、evaluation によって最終的に誰がリストに含まれたかを正確に把握できます。静的リストの場合、evaluation は null となります。

リストを更新する

PUT /lists/{listId}

変更するフィールドのみを送信してください。smart_rules を変更すると、リストが即座に再評価され、同じ evaluation オブジェクトが返されます。

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/list_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "any", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead", "tagWebinar"] } ] } }'

リストの種類は以下のように切り替えることができます：

静的 → スマート: { "type": "smart", "smart_rules": { … } } を送信します。その場でルールが適用されます。
スマート → 静的: { "type": "static" } を送信します。ルールは破棄され、その時点でリストに存在するメンバーはそのまま維持されます。

`smart_rules` の形式

{
  "match": "all",
  "conditions": [
    { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
    { "field": "channel", "op": "is_any", "value": ["whatsapp", "sms"] },
    { "field": "last_incoming_message_at", "op": "not_within_last", "value": { "amount": 7, "unit": "days" } },
    { "field": "created_at", "op": "after", "value": "2026-01-01" },
    { "field": "is_bot_active", "op": "is", "value": true },
    { "field": "email", "op": "is_set" },
    { "field": "custom_field", "key": "Plan", "op": "eq", "value": "pro" }
  ]
}

match — all（すべての条件が真である必要がある）または any（少なくとも1つが真である必要がある）。
conditions — 1〜20個の条件。各条件は最大100個の値、文字列は最大200文字まで。

`field`	`op`	`value`
`tags`	`has_any`, `has_all`, `has_none`	タグIDの配列
`lists`	`in_any`, `not_in_any`	リストIDの配列 (静的リストのみ — スマートリストからスマートリストを作成することはできません)
`channel`	`is_any`, `is_none`	チャネルの配列
`status`	`is_any`, `is_none`	コンタクトステータスの配列
`created_at`, `last_activity_at`, `last_incoming_message_at`, `last_outgoing_message_at`, `first_ai_interaction_at`, `last_ai_interaction_at`	`within_last`, `not_within_last`	`{ "amount": 1–3650, "unit": "hours" \| "days" }`
同一の日付フィールド	`before`, `after`	ISO日付 (`"2026-01-01"`、日単位で比較) または完全なISO日時 (`"2026-01-01T14:30:00Z"`、正確な時刻で比較)
同一の日付フィールド	`is_set`, `not_set`	—
`has_interacted_with_ai`	`is`	`true` / `false` — `true` AIが少なくとも1回（これまでに）メッセージを送信したコンタクトに一致します
`is_bot_active`, `do_not_disturb`, `is_private`, `has_ever_responded`	`is`	`true` / `false`
`email`, `phone_number`, `first_name`, `last_name`	`is_set`, `not_set`, `contains`, `not_contains`	`contains` フォーム用の文字列
`current_campaign_id`, `assigned_agent`	`is_any`, `is_none`, `is_set`, `not_set`	`is_any` / `is_none` フォーム用のID配列
`custom_field` (および `key`)	`eq`, `neq`, `contains`, `not_contains`, `is_set`, `not_set`	値フォーム用の文字列

not_within_last は、日付が設定されていない連絡先（「N日以上前、または未設定」）にも一致し、テキスト比較では大文字と小文字が区別されません。

AIエンゲージメント。 has_interacted_with_ai はライフタイムフラグです。AIが少なくとも1通のメッセージを送信したすべてのコンタクトには true が、それ以外のすべてのコンタクト（チームのみが対応したコンタクトを含む）には false が付与されます。これはAIがコンタクトに最初のメッセージを送信した時点でスタンプされ、消去されることはありません。そのため、コンタクトのAI返信をオフにしたり、別のキャンペーンに移動したりしてもリセットされません。課金に関する一般的な質問である「今月AIが対応したコンタクト」のような期間については、代わりに last_ai_interaction_at の範囲を使用してください：

{ "field": "last_ai_interaction_at", "op": "within_last", "value": { "amount": 30, "unit": "days" } }

is_bot_active（AIに返信の許可があるかどうか、実際に返信したかどうかではない）や has_ever_responded（コンタクトが誰かに対して返信したかどうか）と混同しないでください。これら2つのスタンプは、すべてのコンタクトに対して first_ai_interaction_at / last_ai_interaction_at として返され、ルールセット全体は GET /contacts?rules= でも機能するため、リストを作成せずに一致数をカウントできます。

ルールセットをプレビューする

POST /lists/preview

ルールセットが一致する連絡先をカウントおよびサンプリングします。何も作成したり変更したりすることはありません。ルールを保存する前に、ルールが正しいか確認するために使用してください。

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/preview?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "all", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead"] } ] } }'

レスポンス

{
  "success": true,
  "count": 3,
  "sample": [
    {
      "id": "contact_abc123",
      "first_name": "Sofia",
      "last_name": "Martinez",
      "phone_number": "+31600000000",
      "email": "sofia@example.com",
      "channel": "whatsapp"
    }
  ]
}

sample には最大10件の連絡先が保持され、最近アクティブになった順に表示されます。

スマートリストを今すぐ再実行する

POST /lists/{listId}/evaluate

強制的に即時再評価を行います（ダッシュボードの [今すぐ更新] と同じ動作です）。スマートリストは、連絡先が変更された際や、時間ベースのルールの場合は15分ごとに自動的に更新されるため、この操作が必要になるのは、今すぐ結果を確認したい場合のみです。

レスポンス

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 2, "removed": 1, "total": 4 }
}

evaluation.skipped: true は、同じリストの別の評価がすでに実行中であり、この呼び出しでは何も行われなかったことを意味します。

スマートリストは手動で選択されたメンバーを受け付けません

ターゲットリストがスマートリストである場合、メンバーシップエンドポイントは "This is a smart list — its members are computed from its rules. Edit the rules instead." を伴う 409 を返します。これには POST /contacts/lists、DELETE /contacts/lists、POST /contacts/lists/batch、contact_ids の POST /lists および PUT /lists/{listId}、そしてCSVインポートのターゲットとしてスマートリストを選択することが含まれます。代わりにルールを変更してください。

静的リストに対して POST /lists/{listId}/evaluate を呼び出すことも 409 となります。実行すべきルールが存在しないためです。

連絡先APIエラー

連絡先エンドポイントは、標準のエラーエンベロープを返します。

{
  "success": false,
  "error": "Contact not found"
}

一部のエンドポイントには error_code も含まれており、通常はHTTPステータスと一致します。唯一の例外は以下の連絡先の重複ケースで、HTTPステータスは 200 ですが、error_code のみが 409 を保持します。連絡先エンドポイント固有のコードは以下の通りです：

コード	コンタクトエンドポイントで発生する場合
`400`	不正なリクエスト — フィールドの欠落/無効、空のボディ、不正なカーソル、またはバッチ内で500個を超えるID。
`402`	1件のコンタクトに対するAIタグ付け実行を完了するためのクレジットが不足しています (`error_code: "insufficient_credits"`)。
`404`	コンタクト、リスト、またはタグがアカウントで見つかりませんでした。
`409`	その電話番号を持つコンタクトが既に存在します（作成時）。HTTPステータス`200`のボディ内で`error_code`として返されるため、ここで`error_code`に基づいて分岐してください。また、一括自動タグ付けが既に進行中の場合（`error_code: "auto_tag_run_in_progress"`）、またはコンタクトを別のチャネルにリンクすることで、既に異なる2人にリンクされている2つのコンタクトが結合されてしまう場合にも返されます。
`422`	コンタクトが現在メッセージを受信できません（おやすみモード、非公開、またはサポートされていないチャネル）。チャネルリンクエンドポイントでは、電話番号がない、サポートされていないチャネルの組み合わせ、またはターゲットチャネルに接続された送信者がいない場合も含まれます。

連絡先エンドポイントでの 403 は、プランのアクセス権限ではなく、連絡先制限やリストの権限に関する問題を示している可能性もあります。すべてのエンドポイントが返す共通コード（401、403（プランにAPIアクセスが含まれていない）、429（レート制限）、500）については、再試行のガイダンスとともにエラーとページネーションに記載されています。

次のステップ

メッセージAPI — チャネルIDによるメッセージの送信と会話の管理。
APIリファレンス — タグやリストを含むエンドポイントの完全なリスト。
APIアクセス — 認証、レート制限、エラー処理。

Contacts API #

コンタクトIDについて #

コンタクトの作成 #

電話番号またはメールアドレスによる連絡先の取得 #

IDで連絡先を取得する #

コンタクトの統計を取得する #

連絡先を一覧表示する #

コンタクトのカウント #

連絡先の更新 #

タグの追加または削除 #

タグライブラリを管理する #

タグを更新する #

タグを削除する #

複数のタグを一度に削除する #

フラグの一括設定 #

コンタクトの一括インポート #

CSVファイルから連絡先をインポートする #

インポートを開始する #

インポートジョブをポーリングする #

連絡先をエクスポートする #

エクスポートを開始する #

エクスポートジョブをポーリングする #

連絡先にメッセージを送信する #

AIエージェントを連絡先に割り当てる #

多数のコンタクトへのAIエージェントの割り当て #

連絡先を部門に割り当てる #

チャネル間で連絡先をリンクする #

別のチャネルへのリンク #

連絡先のリンク済み会話を一覧表示する #

連絡先のリンクを解除する #

連絡先のプロフィール画像を取得する #

AIによる連絡先の自動タグ付け #

実行を開始する #

実行状況をポーリングする #

連絡先を削除する #

連絡先の削除 #

カスタムフィールドの削除 #

リスト #

リストを作成する #

リストを更新する #

smart_rules の形式 #

ルールセットをプレビューする #

スマートリストを今すぐ再実行する #

スマートリストは手動で選択されたメンバーを受け付けません #

連絡先APIエラー #

次のステップ #

Contacts API

コンタクトIDについて

コンタクトの作成

電話番号またはメールアドレスによる連絡先の取得

IDで連絡先を取得する

コンタクトの統計を取得する

連絡先を一覧表示する

コンタクトのカウント

連絡先の更新

タグの追加または削除

タグライブラリを管理する

タグを更新する

タグを削除する

複数のタグを一度に削除する

フラグの一括設定

コンタクトの一括インポート

CSVファイルから連絡先をインポートする

インポートを開始する

インポートジョブをポーリングする

連絡先をエクスポートする

エクスポートを開始する

エクスポートジョブをポーリングする

連絡先にメッセージを送信する

AIエージェントを連絡先に割り当てる

多数のコンタクトへのAIエージェントの割り当て

連絡先を部門に割り当てる

チャネル間で連絡先をリンクする

別のチャネルへのリンク

連絡先のリンク済み会話を一覧表示する

連絡先のリンクを解除する

連絡先のプロフィール画像を取得する

AIによる連絡先の自動タグ付け

実行を開始する

実行状況をポーリングする

連絡先を削除する

連絡先の削除

カスタムフィールドの削除

リスト

リストを作成する

リストを更新する

`smart_rules` の形式

ルールセットをプレビューする

スマートリストを今すぐ再実行する

スマートリストは手動で選択されたメンバーを受け付けません

連絡先APIエラー

次のステップ