# Tasks API

タスクは、アカウントに紐付けられたToDoやフォローアップであり、必要に応じて連絡先、取引、またはキャンペーンにリンクできます。タスクはタスクボードの**ステージ**（カンバン形式の列）を移動し、**タイプ**と**優先度**を持ちます。このガイドでは、APIを介したタスクの管理方法について説明します。

- **ベースURL** — `https://api.youraiconnector.com/v1`
- **認証** — APIキー（[認証](authentication.md)を参照）
- **エラーとページネーション** — [エラーとページネーション](errors-and-pagination.md)を参照

以下のすべての例では、cURLでの `?apiKey=` クエリ形式と、JavaScriptおよびPythonでの `X-API-Key` ヘッダーを示しています。どちらの方法もすべてのエンドポイントで使用可能です。

---

## タスクオブジェクト

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`、`faq_update`、または設定済みのタスクタイプ（[タスクタイプの一覧](#list-task-types)を参照）。
- **`priority`** — `none`、`low`、`normal`、`high`、または`urgent`。
- **`stage`** — タスクボード上のステージのID（[タスクステージの一覧](#list-task-stages)を参照）。作成時に省略した場合、タスクは最初のステージに配置されます。
- **`remind_before_minutes`** — `due_date`の何分前にリマインダーを送信するかを指定します。`0`は期限時刻を意味します。省略するか`null`を送信するとリマインダーは送信されません。`0`から`1440`（1日）までの整数である必要があります。これより大きい値は拒否されます。リマインダーを送信するには`due_date`が必要であり、タスクのスケジュールを変更するとリマインダーもそれに合わせて移動します。

---

## タスクの作成

`POST /tasks` — `title` のみが必須です。

::: note
**注:** `due_date`は、時刻を含むISO 8601タイムスタンプを受け付けます。`remind_before_minutes`と組み合わせて、**タスク**の通知設定に基づいてリマインダーを配信します。`contact_id`、`deal_id`、および`campaign_id`は、タスクをそれらのレコードにリンクします。`assigned_to`はチームメンバーのユーザーIDです。
:::


> **`assigned_to` を正しく設定してください。** アカウント所有者、または同じアカウントに所属するアクティブなチームメンバーのユーザーIDである必要があります。このエンドポイントでは現在そのチェックを行っていないため、存在しないIDであっても送信された通りに受け入れられ、保存されます。その場合でも `201` が返されます。IDは手入力せず、コピーしてください。これらのIDには `l` と `L`、あるいは文字の `O` と数字の `0` が混在しており、1文字でも間違えると正しく機能しません。実際に送信された内容を確認するには、ダッシュボードでタスクを開いてください。タスクレコードの **Assignee**（担当者）フィールドは、一致するユーザーがいない場合、未加工のIDを表示するようフォールバックし、**Edit task**（タスクの編集）の担当者ピッカーには **Unassigned**（未割り当て）と表示されます。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**レスポンス** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## タスクの一覧表示

`GET /tasks` — アカウントのタスクを返します（オプションのフィルター指定が可能）。

**クエリパラメータ** (すべて任意): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (ISOタイムスタンプ)。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**レスポンス** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## タスクの検索

`POST /tasks/search` — タイトルと説明に対する全文一致検索。リスト取得時と同じオプションのフィルタを使用できます。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});
```

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## タスクの取得

`GET /tasks/{taskId}`

```bash
curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

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

---

## タスクの更新

`PUT /tasks/{taskId}` — 変更したいフィールドのみを送信します（`title`、`description`、`type`、`priority`、`stage`、`due_date`、`remind_before_minutes`、`contact_id`、`deal_id`、`assigned_to`、`tags`、`notes`）。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## タスクの完了

`POST /tasks/{taskId}/complete` — タスクをボードの完了ステージに移動します。オプションの `notes` フィールドに終了時のメモを記録できます。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## 移動と並べ替え (かんばん)

**タスクを別のステージに移動する** — `POST /tasks/{taskId}/move` を使用して、`new_stage_id`（移動先のステージ）と `new_position`（そのステージ内での0から始まるスロット位置。必須、0以上の整数である必要があります）を指定します：

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**ステージ内のタスクを並べ替える** — `POST /tasks/reorder` を使用して、`stage_id` と新しい順序のタスクIDを指定します：

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## コンタクトのタスク

`GET /tasks/contact/{contactId}` — 1つのコンタクトに紐付けられたすべてのタスク。

```bash
curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## タスクボードの設定

### タスクステージの一覧表示

`GET /tasks/stages` — ボードの列を順序通りに表示します。タスクの作成や移動を行う際は、ステージの `id` を `stage` フィールドとして使用してください。

```bash
curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"
```

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### タスクステージの更新

`PUT /tasks/stages` — ボードのステージ設定を置き換えます。順序付けられた完全な `stages` 配列を送信してください。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### タスクタイプの一覧表示

`GET /tasks/types` — アカウントに設定されているタスクタイプ（ `type` フィールドとして使用されます）。

```bash
curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"
```

---

## FAQ提案の承認

AIボットが新しいFAQを提案すると、`faq_update`タイプのタスクが作成されます。`POST /tasks/{taskId}/approve-faq`は、その提案を、提案元のAIエージェントのナレッジベース内の実際のFAQに変換し、タスクを完了させます。本文内の質問/回答は上書き可能です。

`"send_follow_up": true`を追加すると、AIがタスクに関連付けられた連絡先に対して、そのチャット内の自然なメッセージとして回答を即座に送信するようになります（アプリ内の**今すぐ連絡先に回答を送信する**トグルと同じ動作です）。返信は、その連絡先を担当するAIエージェントを通じて送信されます。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status`は、メッセージがどうなったかを示します：`not_requested`（フラグが設定されていない）、`published`（送信済み）、`queued`（ボットがその連絡先に返信中であり、完了次第回答が送信される）、`skipped_no_contact`（タスクに関連付けられた連絡先がない）、`skipped_no_campaign`（その連絡先に対して回答できるエージェントやキャンペーンがない）、または`skipped_error`。いずれの場合もFAQは作成されます。

作成されたFAQを管理するには、 [FAQs API](faqs.md) を参照してください。

---

## タスクの削除

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## 次のステップ

- [Contacts API](contacts.md) — タスクを適切な連絡先にリンクする
- [Webhooks API](webhooks.md) — `Task Created`、`Task Updated`、`Task Completed` に関する通知を受け取る
- [API Reference](reference.md) — インタラクティブなエンドポイントエクスプローラーの全機能