> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/narrative-design-api.md).

# 叙事设计 API

本页列出了与叙事设计交互所需的所有 API

## 切换叙事设计

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/toggle-is-narrative-driven`

为你的角色启用/禁用叙事图。

#### 请求头

<table><thead><tr><th width="211">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称                    | 类型  | 说明                           |
| --------------------- | --- | ---------------------------- |
| character\_id         | 字符串 | 角色的 ID。                      |
| is\_narrative\_driven | 布尔值 | 将其设为 true 或 false，以启用或禁用叙事图。 |

{% tabs %}
{% tab title="200：成功 " %}

```json
{"STATUS": "Successful"}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/toggle-is-narrative-driven"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id": "<Your-Character-Id>",
    "is_narrative_driven": True
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/toggle-is-narrative-driven" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{"character_id": "<Your-Character-Id>", "is_narrative_driven": true}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 创建章节

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/create-section`

为你的角色创建新章节。

#### 请求头

<table><thead><tr><th width="211">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称                       | 类型   | 说明             |
| ------------------------ | ---- | -------------- |
| character\_id            | 字符串  | 角色的 ID。        |
| objective                | 字符串  | 章节目标           |
| section\_name            | 字符串  | 章节名称。          |
| updated\_character\_data | JSON | \*忽略\* 此字段未使用。 |
| behavior\_tree\_code     | 字符串  | \*忽略\* 此字段未使用。 |
| bt\_constants            | 字符串  | \*忽略\* 此字段未使用。 |

{% tabs %}
{% tab title="200：章节创建成功 " %}

```json
{
    "section_id": "<New-Section-Id>"
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/create-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "objective":"Section Objective",
    "section_name":"SectionName",
    "updated_character_data":{},
    "behavior_tree_code":"",
    "bt_constants":""
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/create-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "objective": "Section Objective",
         "section_name": "SectionName",
         "updated_character_data": {},
         "behavior_tree_code": "",
         "bt_constants": ""
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 编辑章节

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/edit-section`

编辑角色的章节。要更新某个章节，请在 updated\_character\_data JSON 中提供所有要更新的字段。以下是有效的键：

* "section\_name"
* "objective"
* "decisions": 这是一个 JSON 列表。列表中的每个条目都应采用以下格式：

  ```
  {
      "criteria":"决策条件",
      "next_section_id":"要转到的章节 ID"
  }
  ```

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称                       | 类型   | 说明         |
| ------------------------ | ---- | ---------- |
| character\_id            | 字符串  | 角色的 ID。    |
| updated\_character\_data | JSON | 包含已更新的字段。  |
| section\_id              | 字符串  | 要更新的章节 ID。 |

{% tabs %}
{% tab title="200：成功，章节已更新 " %}

```json
{
    "status": "success",
    "section_id": "<Section-Id>",
    "updated_data": {
        "objective": "Some new objective."
    }
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/edit-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->",
    "updated_data":{
        "decisions":[
            {"criteria":"User agrees to take tour.", "next_section_id":"b9d7f568-7d06-11ef-be6a-42010a7be011"}
        ],  
        "objective":"Offer user tour of a Museum.",
        "section_name":"Welcome Section"
    }   
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/edit-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->",
         "updated_data": {
             "decisions": [
                 {
                     "criteria": "User agrees to take tour.",
                     "next_section_id": "b9d7f568-7d06-11ef-be6a-42010a7be011"
                 }
             ],
             "objective": "Offer user tour of a Museum.",
             "section_name": "Welcome Section"
         }
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 获取章节

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/get-section`

获取角色某个叙事章节的详细信息。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明         |
| ------------- | --- | ---------- |
| character\_id | 字符串 | 角色的 ID。    |
| section\_id   | 字符串 | 要获取的章节 ID。 |

{% tabs %}
{% tab title="200：成功，章节详情 " %}

```json
{
   "character_id": "<Your-CharacterId>",
   "section_id": "<Your-SectionId>",
   "objective": "Offer user tour of History Museum.",
   "decisions": [{"criteria": "User agrees to take tour.", "next_section_id": "12345568-7890-1123-4456-424242424242"}],
   "parents": null,
   "updated_character_data": {},
   "bt_constants": "",
   "behavior_tree_code": "",
   "section_name": "Welcome Section",
   "triggers": null,
   "node_position": []
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/get-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/get-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>",
           "section_id": "<Section-Id->"
         }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 列出章节

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/list-sections`

列出指定角色的所有叙事章节详情。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明      |
| ------------- | --- | ------- |
| character\_id | 字符串 | 角色的 ID。 |

{% tabs %}
{% tab title="200：成功，章节详情列表 " %}

```json
[
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "123456789-7ddd-dddd-bbbb-424242424242",
    "objective": "",
    "decisions": null,
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "section 1",
    "triggers": null,
    "node_position": []
  },
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "100000789-7ddd-dddd-bbbb-42424242424",
    "objective": "Offer user tour of History Museum.",
    "decisions": [
      {
        "criteria": "User agrees to take tour.",
        "next_section_id": "123456789-7ddd-dddd-bbbb-424242424242"
      }
    ],
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "Welcome Section",
    "triggers": null,
    "node_position": []
  }
]
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/list-sections"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/list-sections" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>"
         }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 删除章节

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/delete-section`

删除角色的叙事章节。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明         |
| ------------- | --- | ---------- |
| character\_id | 字符串 | 角色的 ID。    |
| section\_id   | 字符串 | 要删除的章节 ID。 |

{% tabs %}
{% tab title="200：成功，章节已删除 " %}

```json
{"STATUS": "Successful"}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/delete-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/delete-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->"
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 创建触发器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/create-trigger`

为角色创建新的触发器。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称                   | 类型  | 说明                                    |
| -------------------- | --- | ------------------------------------- |
| character\_id        | 字符串 | 角色的 ID。                               |
| trigger\_name        | 字符串 | 触发器的名称。在同一角色中必须唯一。                    |
| trigger\_message     | 字符串 | 触发器的消息。通常用于说明触发器被调用的事件。例如：用户进入场景。     |
| desgination\_section | 字符串 | 此触发器的目标章节 ID。如果不想将触发器关联到任何章节，请勿传递此字段。 |

{% tabs %}
{% tab title="200：成功，触发器已创建 " %}

```json
{
    "character_id": "<Your-Character-Id>,
    "trigger_id": "<ID-Of-The-Newly-Created-Trigger>",
    "trigger_name": "StartTrigger",
    "trigger_message": "User has entered the museum.",
    "destination_section": "<Destination-Section-ID>",
    "node_position": []
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/create-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Your-Character-Id>",
    "trigger_message":"User has entered the museum.",
    "trigger_name":"StartTrigger",
    "destination_section": "<Destination-Section-ID-to-connect-to>"
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/create-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "trigger_message": "User has entered the museum.",
         "trigger_name": "StartTrigger",
         "destination_section": "<Destination-Section-ID-to-connect-to>"
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 更新触发器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/update-trigger`

编辑触发器。要更新触发器，请通过 updated\_data JSON 发送所有要修改的字段。以下是有效的键。

* "trigger\_name": 新触发器名称。必须唯一。
* "trigger\_message": 新触发器消息。
* "destination\_section": 触发器的新目标章节 ID。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型   | 说明          |
| ------------- | ---- | ----------- |
| character\_id | 字符串  | 角色的 ID。     |
| updated\_data | JSON | 包含已更新的字段。   |
| trigger\_id   | 字符串  | 要更新的触发器 ID。 |

{% tabs %}
{% tab title="200：OK，触发器已更新 " %}

```json
{
    "STATUS": "Successful",
    "message": "Trigger updated successfully"
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/update-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "updated_data": {
        "destination_section":"<New-Destination-Section-Id>",
        "trigger_message":"User has entered the Computer history museum"
    }   
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)                  
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/update-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Section-Id>",
         "updated_data": {
             "destination_section": "<New-Destination-Section-Id>",
             "trigger_message": "User has entered the Computer history museum"
         }
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 删除触发器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/delete-trigger`

删除现有触发器。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明          |
| ------------- | --- | ----------- |
| character\_id | 字符串 | 角色的 ID。     |
| trigger\_id   | 字符串 | 要删除的触发器 ID。 |

{% tabs %}
{% tab title="200：OK，触发器已删除 " %}

```json
{
    "STATUS": "Successful",
    "message": "Trigger deleted successfully"
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/delete-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)                 
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/delete-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Trigger-Id>"
     }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 获取触发器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/get-trigger`

获取现有触发器的详细信息。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明          |
| ------------- | --- | ----------- |
| character\_id | 字符串 | 角色的 ID。     |
| trigger\_id   | 字符串 | 要获取的触发器 ID。 |

{% tabs %}
{% tab title="200：OK，触发器详情 " %}

```json
{
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "trigger_name": "UserEntry",
    "trigger_message": "User has entered the museum.",
    "destination_section": null,
    "node_position": []
}
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/get-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)              
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/get-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Character-Id>",
           "trigger_id": "<Trigger-Id>"
         }'
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 列出触发器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/character/narrative/list-triggers`

列出某个角色的所有触发器。

#### 请求头

<table><thead><tr><th width="226">名称</th><th>类型</th><th>说明</th></tr></thead><tbody><tr><td>CONVAI-API-KEY<mark style="color:红色;">*</mark></td><td>字符串</td><td>为每位用户提供的唯一 API 密钥。登录 Convai 账户后，可在密钥图标下找到。</td></tr></tbody></table>

#### 请求正文

| 名称            | 类型  | 说明      |
| ------------- | --- | ------- |
| character\_id | 字符串 | 角色的 ID。 |

{% tabs %}
{% tab title="200：OK，触发器详情列表 " %}

```json
[
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID1>",
    "trigger_name": "trigger 1",
    "trigger_message": "",
    "destination_section": null,
    "node_position": []
  },
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID2>",
    "trigger_name": "UserEntry",
    "trigger_message": "User has entered the museum.",
    "destination_section": null,
    "node_position": [ ]
  }
]
```

{% endtab %}

{% tab title="401 API 密钥验证失败" %}

```json
{
    "ERROR": "Invalid API key provided."
}
```

{% endtab %}
{% endtabs %}

以下示例代码展示了此端点的请求格式 -->

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" %}

```python
import requests
import json

url = "https://api.convai.com/character/narrative/list-triggers"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# 为 JSON 载荷创建字典
payload = { 
    "character_id":"<Character-Id>", 
}

# 将载荷转换为 JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)              
```

{% endcode %}
{% endtab %}

{% tab title="cURL" %}
{% code overflow="wrap" %}

```shell
curl -X POST "https://api.convai.com/character/narrative/list-triggers" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{"character_id":"<Character-Id>"}'
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/narrative-design-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
