メッセージと会話 #

Messages APIを使用すると、受信トレイを開くことなく、連絡先へのメッセージ送信、会話の読み取り、送信済みメッセージの修正や削除、リアクションの追加、チャットセッションスレッド全体の取得、トランスクリプトのエクスポート、チャットの既読/未読設定を行うことができます。

このページのすべてのパスは、ベースURL https://api.youraiconnector.com/v1 からの相対パスです。すべてのリクエストにはAPIキーが必要です。送信方法の全リストについては認証を参照してください。以下の例では X-API-Key ヘッダーを使用しており、1つのcURL例では ?apiKey= クエリ形式も示しています。

配信の仕組み: メッセージを送信しても、その到着を待機するわけではありません。APIはメッセージを受け取ると、即座にメッセージIDを返して終了し、その後バックグラウンドで連絡先のチャネル（WhatsApp、SMS、Instagramなど）を通じて配信します。メッセージが実際に配信または既読されたかどうかを追跡するには、Webhooksを使用してステータス更新をリッスンしてください。ポーリングは行わないでください。送信レスポンスは、メッセージが受け付けられたことのみを確認するものです。

メッセージの送信 #

送信方法は2通りあります。連絡先の識別方法に合わせて選択してください。

• 連絡先IDで送信 — 連絡先IDがすでにわかっている場合（APIを通じて連絡先を作成した、またはWebhookから取得した場合など）。POST /contacts/{contactId}/send-messageを使用します。
• 連絡先識別情報で送信 — 電話番号やInstagram IDなどはわかっているが、内部IDが不明な場合。POST /contacts/sendを使用し、プラットフォームに適切な連絡先を検索させます。

どちらの方法でもメッセージは同じようにキューに入れられ、連絡先が利用しているチャネルで配信されます。トランスポートを選択する必要はありません。プラットフォームがWhatsAppの連絡先にはWhatsApp経由で、SMSの連絡先にはSMS経由でといったようにルーティングを行います。

どちらの呼び出しも、既存の連絡先のみを検索します。どちらの呼び出しも連絡先を作成することはありません。IDや識別情報が一致しない場合は 404 が返され、新しい連絡先として登録されることはありません。そのため、初めて誰かにメッセージを送る場合は、事前に POST /contacts で連絡先を作成するか、WhatsApp Webの場合は以下の WhatsApp Web番号へ直接送信 を使用してください。こちらを使用すると、同じ呼び出し内で連絡先が作成されます。

連絡先IDで送信 #

POST /contacts/{contactId}/send-message

LinkedInにおいて、この方法または受信トレイから送信されたメッセージは、相手がLinkedIn側でスレッドを操作している最中であっても配信されます。AI自身の返信やフォローアップは、そのようなスレッドでは保留されます。保留された返信は、送信されずクレジットも消費されないため、失敗として表示されるのではなく、チャットから削除されます。AIがスレッドを相手に引き継ぐ直前の最後の返信は、そのまま配信されます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

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

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

レスポンス (200 OK):

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

連絡先識別情報で送信 #

POST /contacts/send

連絡先の内部IDがない場合に使用します。メッセージの body に加えて、contact_id または channel のいずれかと、そのチャネルに一致する識別フィールドを指定してください。

識別情報によって解決可能なチャネル。 14チャネルのうち、contact_idの代わりに識別フィールドを受け入れるのは6つのみです。whatsapp、whatsapp_web、smsはphone_numberで検索され、instagramはinstagram_idで、messengerはmessenger_idで、telegramはtelegram_user_idで検索されます。その他の8つ（instagram_private、chat-widget、custom、email、line、imessage、linkedin、viber）には検索可能な公開識別情報がないため、これらのチャネルで送信するにはcontact_idが必要です。channelのみを渡すと、contact_idが必要であることを示す400が返されます。

cURL (?apiKey= クエリ形式を使用)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

レスポンス (201 Created):

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

メッセージが拒否される理由: おやすみモードやプライベートモードがオンになっている連絡先は、アウトバウンドメッセージを受信できません。その場合、リクエストは422で失敗します。指定したIDや識別情報に一致する連絡先がない場合は、404が返されます。

WhatsApp Webでの送信：バリエーションとバースト保護 #

連絡先がWhatsApp Webを使用している場合、bodyには2つの事項が適用されます。

スピントックス（Spintax）の波括弧は送信ごとに展開されます。 bodyの{Hi|Hello|Hey} there, quick questionは、その送信のために選択された3つの挨拶のうちの1つとして送信されます。波括弧が連絡先に届くことはありません。これを使用すると、同じ統合コードから各連絡先に異なる開始メッセージを送ることができます。波括弧のないテキストは、記述通りに送信されます。

同一の開始メッセージのバースト（連続送信）は拒否されます。 1つのWhatsApp Web番号から1時間以内に、一度もやり取りしたことのない連絡先へ、ほぼ同一の開始メッセージが10通送信されると、それ以降のメッセージは配信されません。送信自体は通常通り受け付けられます（messageIdは取得できます）が、メッセージはstatus: "failed"およびerror_code: "opener_burst"の状態となり、顧客が確認可能な理由が表示されます。同じテキストで再試行しても効果はありません。テキストを変更するか、1時間待ってから再度送信してください。既存の会話内での返信は影響を受けません。その理由は同一の開始メッセージによる番号の制限に記載されています。

WhatsApp Web番号へ直接送信 #

POST /whatsapp-web/send

連絡先を事前に検索することなく、WhatsApp Web上の電話番号にメッセージを送信します。その番号がまだ連絡先として登録されていない場合、同じ呼び出し内で連絡先が作成されます。その際、AIはオフに設定されるため、手動で送信したメッセージとして扱われ、その後アシスタントが会話を引き継ぐことはありません。既存の連絡先の場合は、そのまま再利用されます。

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

呼び出しが成功すると 202 が返されます：

{ "success": true, "queued": true, "contactId": "abc123" }

202 は「受け付け済み」を意味し、まだ配信は完了していません。ignoreActiveHours を指定しない限り、稼働時間外の送信は保留され、次に許可された時間帯に送信されます。メッセージ自体のステータスを確認するには、ここで取得した contactId を使用して 連絡先のメッセージ一覧を取得 してください。

送信が失敗した場合：

保留中の送信がある状態で同じ連絡先に対して2回目の呼び出しを行うと 409 が返されるため、特定の相手に対して送信待ちが積み重なることはありません。

会話にメモを記録する #

POST /contacts/notes

連絡先の会話に、送信することなく行を追加します。チームやAIが把握しておくべきだが、連絡先には決して見せてはいけないコンテキスト（音声エージェントが行った通話の要約、CRMからの備考、同僚からのメモなど）に使用してください。すべてのチャネル（WhatsApp、SMS、Instagram、Messenger、Telegram、チャットウィジェット、カスタムチャネルなど）で機能します。

メモの扱いについて:

• 受信トレイのチャット内には、黄色のメモカードとして表示されます（送信者が指定されている場合はその名前も表示されます）。
• AIはこれを会話履歴の一部として読み取ります（内部メモとしてマークされます）。そのため、AIの次回の返信にはこの内容が考慮されます。
• 連絡先には一切送信されず、メッセージクレジットも消費されません。また、AIの返信、自動化、Webhook、通知、未読バッジなどのトリガーも発生しません。AIを一時停止させることもなく、チームからの返信としてもカウントされません。

連絡先IDによる送信と同じ方法で連絡先を検索します。IDを使用するか、channelと一致する識別子を使用してください。メモは既存の連絡先にのみ送信されます。一致するものがない場合は404となります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

レスポンス (201、またはexternal_idが既に記録されている場合はduplicate: trueを含む200)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

メモは連絡先のメッセージ一覧を取得にtype: "note"と共に表示されます。

AIで返信ドラフトを生成する #

POST /contacts/{contactId}/draft-reply

会話を担当するAIエージェントに次の返信を作成させ、そのテキストを取得します。何も送信されません。 これは受信トレイの返信を生成ボタンが作成するドラフトと同じものです。エージェントは自身の設定、ナレッジベース、およびこれまでの会話内容を使用して、連絡先の言語で回答します。AIと連絡先の間に人間（または独自のアプリ）を介在させたい場合に使用します。ドラフトを取得して承認のために表示し、変更またはそのままの状態で連絡先IDで送信を使用して送信してください。

• ドラフトは、その連絡先に割り当てられたエージェントによって作成されます。まだエージェントが割り当てられていない連絡先には、次のメッセージに回答する予定のエージェントが割り当てられます。
• ドラフト作成中、エージェントはツールや関数を実行しないため、予約、タグ付け、引き継ぎなどのアクションは発生しません。
• 会話には何も保存されず、連絡先には何も表示されません。
• ドラフト作成には、その会話でそのエージェントがAI返信を行う場合と同じクレジットが消費されます。独自のAIキーが接続されている場合は無料です。
• 会話には少なくとも1つのメッセージが必要です。

すべてのボディフィールドはオプションです。ボディが空（または指定なし）の場合、次の返信がドラフトされます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

レスポンス (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

400は、会話にまだメッセージがない、クレジットが不足している、またはドラフトを作成するためのエージェントやキャンペーンが連絡先に設定されていない（errorに詳細が表示されます）ことを意味します。404は、連絡先が存在しないか、チームメンバーのキーが閲覧できない連絡先に制限されていることを意味します。キーまたはチームメンバーには、メッセージを編集する権限が必要です。

MCP経由でAIクライアントを使用していますか？ 同じアクションがgenerate_reply_draftツールとして利用可能です。

連絡先のメッセージを一覧表示する #

GET /contacts/{contactId}/messages

連絡先のメッセージを新しい順に返し、カーソルベースのページネーションを使用します。

フィルタリングとページネーションに関する注意: filterおよびdirectionフィルタは、各ページが読み込まれた後に適用されるため、フィルタリングされたページにはlimitより少ないアイテムが含まれる場合があります。next_cursorは会話全体を通じて進むため、next_cursorがnullになるまでページングを続けてください。

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

メッセージフィールド #

メッセージの添付ファイルをダウンロード #

POST /chat-exports/media/download-url

メッセージに添付されたファイル（画像、ボイスメモ、動画、ドキュメント）の新しいダウンロードリンクを取得します。リンクの有効期限は 1時間 です。添付ファイルを別の場所に保存したい場合（例：連絡先から送られてきた履歴書やボイスメモを整理する場合）や、メッセージ上の media_url または New Message webhook が開かなくなった場合に使用してください。

添付ファイル付きのメッセージを見つけるには、filter=mediaを使用して連絡先のメッセージを一覧表示します。各メッセージのidと連絡先のIDがmessagePathを構成します。

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

レスポンス (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

MCP経由でAIクライアントを使用していますか？ 同じアクションがget_chat_media_download_urlツールとして利用可能です。

チャットセッションの一覧表示 #

チャットセッションとは、連絡先との1つの会話ウィンドウのことです。セッションが開かれていない状態で最初のメッセージを受信すると開き、連絡先からの最後のメッセージ受信から48時間後に自動的に閉じます（新しいメッセージを受信するたびに、終了までの時間がさらに48時間延長されます）。AIがチャットを終了してもセッションは閉じず、「Chat Concluded（チャット終了）」Webhookが送信されるだけです。セッションは、終わりのないリストではなく、長い履歴を読みやすい会話としてページ分割するための仕組みです。

すべての連絡先の最近のセッション #

GET /chat-sessions/recent

アカウント内のすべての連絡先を対象に、過去X時間以内に開始されたセッションを新しい順に返します。

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

レスポンス (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

特定の連絡先のすべてのセッション #

GET /chat-sessions/{contactId}

特定の連絡先のすべてのチャットセッションを返します。上記の status、limit、includeMessages パラメータと同じですが、hours はここでは適用されません。

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス (200 OK):

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

セッションIDのフィールド名は、2つのエンドポイント間で異なります。 最近のセッションリストでは session_id と呼ばれます（セッションは多くの連絡先から取得されるため、連絡先の詳細も含まれます）。連絡先ごとのリストでは id と呼ばれます。どちらの値も、以下のスレッド全体を取得する際に {sessionId} として渡す値です。

includeMessages=true の場合、各セッションに messages 配列が追加され、そのエントリには id、body、direction、timestamp、type、channel、status が含まれます。

チャットセッションのスレッドを取得する #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

チャットセッションは、連絡先とのメッセージを1つの会話ウィンドウにグループ化します。このエンドポイントは、単一セッションの全スレッドを古い順に、セッションのメタデータとともに返します。連絡先のセッションIDは、チャットセッションのエンドポイントから取得できます。

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

session オブジェクトは、status（アクティブな間は ChatSessionOpened、終了後は ChatSessionClosed）、start_date_time、end_date_time、および人間が読み取れる tag を報告します。messages 配列は、リストエンドポイントと同じ メッセージフィールド を使用します。

メッセージの編集、削除、リアクション #

これらのエンドポイントは、送信後のメッセージを変更します。そのうち2つは、自分のコピーだけでなく連絡先のチャネルにも影響を与えるため、実装前にセクションの導入部をお読みください。何が可能かは、会話が行われているチャネルに完全に依存します。

各チャネルで可能な操作

その他のすべてのチャネル（WhatsApp Business API、SMS、Instagram、Messenger、メール、LINE、カスタムチャネル）では、削除を行うと受信トレイからはメッセージが削除されますが、連絡先側のコピーは保持されます。また、編集やリアクションは一切できません。

メッセージの編集 #

POST /contacts/{contactId}/messages/{messageId}/edit

すでに送信したメッセージを、連絡先のデバイス上および自分のコピーの両方で書き換えます。

削除とは異なり、チャネル側で拒否された場合、この操作は明確に失敗します。409が表示され、コピーは連絡先側の状態のまま変更されません。これは、相手が受け取っていない編集内容を表示すると、双方の同期が取れなくなるためです。edit_reasonフィールドにはその理由が表示されます。チャネルの編集可能時間が終了した、チャネルが切断されている、チャネルが編集できない添付ファイルが含まれている（media_not_editable: WhatsApp Webではテキストメッセージのみ編集可能で、写真、動画、ファイルの下にあるテキストは編集不可）、またはその他のエラーが発生した可能性があります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

チャネルが編集を受け付けない場合、代わりに 409 が返され、何も変更されません：

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

すでに削除済みのメッセージ、編集機能を持たないチャネル、チャネルの制限時間を過ぎたメッセージに対するリクエストはすべて 400 を返します。リクエストはチャネルに到達しません。

メッセージを1件削除する #

DELETE /contacts/{contactId}/messages/{messageId}

会話からメッセージを削除します。チャネルが許可している場合は、連絡先のコピーも削除します。リクエストボディは不要です。

メッセージが存在していた場合、連絡先のコピーを削除できなかったとしても、この操作は常に 200 を返します。自分のコピーは確実に削除されているため、エラーを返すと誤解を招く可能性があるからです。レスポンスに含まれる3つのフィールドを確認して、実際に何が起こったのかをユーザーに伝えてください：

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

削除されたメッセージは会話履歴から削除されません。それらは GET /contacts/{contactId}/messages に残り、is_deleted: true と空の body および media_url が保持されます。

複数のメッセージを一度に削除する #

POST /contacts/{contactId}/messages/bulk-delete

自分側のメッセージを一括で消去します。本文と添付ファイルは空になりますが、相手のデバイス上のメッセージは取り消されません。メッセージを相手側からも取り消すには、上記の単一メッセージ用エンドポイントを使用して1つずつ削除してください。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

レスポンス (200 OK):

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

メッセージにリアクションする #

POST /contacts/{contactId}/messages/{messageId}/react

メッセージに自分の絵文字リアクションを追加します。空の文字列を送信すると、リアクションを取り消すことができます。相手自身のリアクションには一切影響しません。

編集と同様に、相手に届かなかったリアクションを表示するのではなく失敗します。その際、再試行する価値があるかどうかがエラー内容からわかります：

• 422 — この会話では配信できません：チャンネルがリアクションをサポートしていない、メッセージにチャンネル側のIDがない、または絵文字がそのチャンネルで許可されているセットに含まれていません。
• 409 — チャンネルに一時的に接続できませんでした。再試行すれば成功する可能性があります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

reactions 配列は、自分と相手のものを含め、現在メッセージに付いているリアクションの完全なセットです。409 または 422 の場合、変更されずに返されるため、そこから直接レンダリングするクライアントは、配信されなかったリアクションを表示することはありません。

メッセージを評価またはスター付けする #

PATCH /contacts/{contactId}/messages/{messageId}

メッセージに高評価（サムズアップ）または低評価（サムズダウン）を付けたり、重要としてスターを付けたりします。これは自分側のみの記録であり、相手には何も送信されません。

少なくともどちらか一方を送信してください。そうしないと 400 が返されます。送信した内容のみが書き込まれるため、メッセージにスターを付けても評価がクリアされることはなく、その逆も同様です。また、レスポンスには送信したフィールドのみがエコーバックされます。

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

メッセージを既読にする #

未読状態は、特定のメッセージに対して、または会話全体に対してクリアできます。

特定のメッセージを既読にする #

POST /contacts/{contactId}/messages/mark-read

既読にするメッセージのIDを渡します。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

チャット全体を既読にする #

POST /contacts/{contactId}/mark-read

受信トレイ内の連絡先との会話全体の未読バッジをクリアします。リクエストボディは不要です。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

チャット全体を未読にする #

POST /contacts/{contactId}/mark-unread

会話に未読バッジを再度表示します。チームの誰かがチャットを開いたものの、対応を戻す場合に便利です。リクエストボディは不要です。

これは受信トレイ専用のフラグであり、会話が最後にいつ読まれたかは変更されません。そのため、既読通知をサポートしているチャネルであっても、連絡先には既読通知は送信されません。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

会話をエクスポートする #

エクスポート機能を使用すると、メッセージをページ送りするのではなく、会話全体を読み取り可能なトランスクリプトとして取得できます。すべてのエクスポートエンドポイントは、メッセージリストのフィルターと一致する filter（デフォルトは all、その他 text、media、tool_use）を受け付けます。

1人の連絡先とのチャットをエクスポートする #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

format=json を含むレスポンス (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

format=txt（デフォルト）の場合、data は生成されたトランスクリプトファイルへのダウンロードリンクになります：

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

ダウンロードリンクの有効期限は短いです。 リンクを取得したら保存せずにすぐにファイルをダウンロードしてください。トランスクリプトが再度必要な場合は、新しくエクスポートをリクエストしてください。

最近のすべての会話をエクスポートする #

GET /chat-exports/recent

過去X時間以内にアクティブだったすべての連絡先の会話を、1回の呼び出しでエクスポートします。

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

format=txtを使用すると、レスポンスはJSONではなく、ダウンロードとして送信されるテキストファイルそのものになります。

この1回の呼び出しで、一致するすべての連絡先の全履歴が取得されるため、アクティブなアカウントではhoursとlimitを控えめに設定してください。

連絡先にトランスクリプトをメールで送信する #

POST /chat-exports/{contactId}/email

連絡先自身の会話トランスクリプトをメールで送信します。これは、独自のシステムから実行される「このチャットをメールで送信」フローです。

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

レスポンス (200 OK):

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCountは、メールを適切な長さに保つために、古いメッセージがいくつ除外されたかを示します。200は、トランスクリプトが作成され送信待ち状態であることを意味し、まだ受信トレイに届いていないことを示します。

連絡先ごとのAIの一時停止または再開 #

PUT /contacts/{contactId}

is_bot_activeをfalseに設定すると、特定の連絡先に対するAIの返信が停止します。trueに戻すと、会話がボットに引き継がれます。人間が会話に介入する際に使用する引き継ぎスイッチです。ボットが一時停止している間も、API経由で送信したメッセージは相手に届きます。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

レスポンス

{
  "success": true,
  "contact_id": "contact123"
}

返信の一部として一時停止する

人間が返信を送って対応を引き継ぐ場合、2回目の呼び出しを行う代わりに、同じリクエスト内でボットを一時停止できます。POST /contacts/{contactId}/send-message は以下のオプションフラグを受け付けます：

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

一時停止が適用された場合、レスポンスには"botPaused": trueが含まれます。

連絡先をPOST /contacts/bulk-flagでプライベートに設定することでも、その連絡先に対するボットが一時停止されます。フィールドの全リストについては連絡先を参照してください。

独自のインボックスを構築する #

インボックスに必要なすべての情報は、このページおよび連絡先に記載されています。

ライブアップデートを取得するには、タイマーでこのAPIをポーリングするのではなく、Webhookを使用してNew Message、Replies、Human Alerted、Chat Concludedのイベントを購読してください。

Messages APIのエラー #

メッセージエンドポイントは、標準的なエラーエンベロープを返します：

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

すべてのエンドポイントが返す共通コード（401、403（プランにAPIアクセスが含まれていない）、429（レート制限）、500）については、再試行のガイダンスと共にエラーとページネーションに記載されています。

次のステップ #

• Webhooks — ポーリングの代わりに、配信ステータスの更新をプッシュで受け取ります。
• 連絡先 — メッセージを送信する連絡先を作成および検索します。
• 予約 — 連絡先の予約を登録および管理します。