# Start by API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

เพิ่มชุดผู้ใช้เข้าไปใน **API entry point** ของ Journey ใช้เพื่อขับเคลื่อน Journey จากแบ็กเอนด์ของคุณเอง ตัวอย่างเช่น เริ่มโฟลว์การเริ่มต้นใช้งานเมื่อผู้ใช้ลงทะเบียนบนเซิร์ฟเวอร์ของคุณเสร็จสิ้น

<Aside type="tip">
อย่าสับสนระหว่างการเรียกนี้กับ [Lifecycle start](/th/developer/api-reference/customer-journey-api/lifecycle/#endpoints) ซึ่งจะเปิดใช้งาน Journey และย้ายไปที่สถานะ **Running** การเริ่มต้นด้วย API จะเพิ่มผู้ใช้เข้าไปใน Journey ที่กำลังทำงานอยู่แล้ว ดู [ตารางเปรียบเทียบ](/th/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api)
</Aside>

## ข้อกำหนดเบื้องต้น

- Journey อยู่ในสถานะ **Running**
- Journey มี API entry point เพียงหนึ่งจุดเท่านั้น (องค์ประกอบ "Start by API") และองค์ประกอบนั้นไม่ได้ถูกปิดใช้งาน
- ชื่อแอตทริบิวต์ที่คุณส่งต้องตรงกับแอตทริบิวต์ที่กำหนดค่าไว้ใน API entry point นั้น

<Aside type="caution" title="ขีดจำกัดอัตรา">
แต่ละ API entry point รับ **หนึ่งคำขอต่อนาที** คำขอที่สองภายในกรอบเวลานั้นจะส่งคืนข้อผิดพลาด (`Enhance your calm! only one request per minute is allowed`) รวมผู้รับของคุณไว้ในคำขอเดียวแทนที่จะส่งคำขอเล็กๆ หลายรายการ
</Aside>

## พารามิเตอร์ของ Path

| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| `id` | string | [Journey ID](/th/developer/api-reference/api-identifiers/#journey-id) ของ Journey ที่กำลังทำงานอยู่ |

## ส่วนหัวของคำขอ (Request headers)

| ชื่อ | จำเป็น | ค่า |
|---|---|---|
| `Content-Type` | ใช่ | `application/json` |
| `Authorization` | ใช่ | `Api <server_api_token>` ดู [Server API token](/th/developer/api-reference/api-access-token/#server-api-token) |

## เนื้อหาของคำขอ (Request body)

เนื้อหาของคำขอมีอ็อบเจ็กต์ `payload` เพียงหนึ่งรายการ คุณต้องระบุ **เพียงหนึ่งอย่างเท่านั้น** จาก `users`, `hwids` หรือ `filter` เพื่อเลือกผู้ที่จะเข้าสู่ Journey

| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| `payload.users` | string[] | [User IDs](/th/developer/api-reference/api-identifiers/#user-id) ที่จะเข้าสู่ระบบ ไม่สามารถใช้ร่วมกับ `hwids` และ `filter` ได้ |
| `payload.hwids` | string[] | [HWIDs](/th/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) ที่จะเข้าสู่ระบบ ไม่สามารถใช้ร่วมกับ `users` และ `filter` ได้ |
| `payload.filter` | string | นิพจน์ [seglang](/th/developer/api-reference/segmentation-filters-api/segmentation-language/) ที่เลือกกลุ่มเป้าหมาย ไม่สามารถใช้ร่วมกับ `users` และ `hwids` ได้ |
| `payload.attribute_values` | map&lt;string, string&gt; | ไม่บังคับ ค่าสำหรับแอตทริบิวต์ที่กำหนดเองที่กำหนดไว้ใน API entry point แต่ละคีย์ต้องตรงกับชื่อแอตทริบิวต์ที่กำหนดค่าไว้ |

### ตัวอย่างคำขอ

##### เพิ่มผู้ใช้ที่ระบุ

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### เพิ่มผู้ใช้ที่ระบุพร้อมแอตทริบิวต์

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### เพิ่มกลุ่มเป้าหมายโดยใช้ตัวกรอง

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## การตอบกลับ (Response)

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| `request_uuid` | string | ตัวระบุของคำขอเข้าที่ยอมรับ คำขอจะถูกประมวลผลแบบอะซิงโครนัส |

</TabItem>
<TabItem label="400">

ข้อผิดพลาดในการตรวจสอบความถูกต้องจะส่งคืน HTTP `400` พร้อมข้อความอธิบาย กรณีทั่วไป:

| ข้อความ | สาเหตุ |
|---|---|
| `one of users, hwids or filter must be provided` | ไม่มีการตั้งค่าตัวเลือกใดๆ ในสามตัวเลือก |
| `only one of users, hwids or filter must be provided` | มีการตั้งค่าตัวเลือกมากกว่าหนึ่งตัว |
| `Journey is not running` | Journey ไม่ได้อยู่ในสถานะ Running |
| `zero api start points` | Journey ไม่มี API entry point |
| `there is more then one api start point` | Journey มี API entry point มากกว่าหนึ่งจุด |
| `point is deactivated` | API entry point ถูกปิดใช้งาน |
| `unknown attribute: <name>` | คีย์ `attribute_values` ไม่ได้ถูกกำหนดค่าใน API entry point |
| `Enhance your calm! only one request per minute is allowed` | ถึงขีดจำกัดอัตรา (หนึ่งคำขอต่อนาทีต่อ entry point) |

</TabItem>
</Tabs>

## หัวข้อที่เกี่ยวข้อง

<CardGrid>
  <LinkCard title="Lifecycle" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="รับสถิติ Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="ภาษา Segmentation" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>