<!-- https://staircase.co/agents/roster/conversation-management -->
# Conversation management

# Conversation management

Platform

<!--source:agent-kits-->
Manages the fleet around the runtime: the queue a conversation waits in, the configuration each agent runs from, and the tasks raised for a person when a conversation needs one.
<!--/source-->

- **Used when**
<!--source:agent-kits-->
— Wherever a conversation has to wait, escalate, or be picked up by someone.
<!--/source-->

- **Collects**
<!--source:agent-kits-->
- The queue a conversation belongs to, and its state.
<!--/source-->
<!--source:agent-kits-->
- The configuration version each agent is running.
<!--/source-->

- **Returns**
<!--source:agent-kits-->
- The queue position and the state transitions.
<!--/source-->
<!--source:agent-kits-->
- The task raised for a person, and the answer that closed it.
<!--/source-->

- **Evidence**
- `chatbot-queues`
- `chatbot-asana-tasks`
- `chatbot-assistant-template`

## Operations

<!--source:api-specifications-->

### ChatMTG
<!--/source-->

`POST` `/functions`

<!--source:api-specifications-->

#### Create Function
<!--/source-->

`createFunction`

<!--source:api-specifications-->
Create a function that can be invoked by GPT in the conversation based on user input by calling a webhook URL with some values for the parameters defined in the function. Learn more about functions in the GPT documentation.

<!--/source-->

##### Request

<!--source:api-specifications-->
Execute SQL QueryGet Database Schema
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "name": "execute_sql_query",
 "description": "Use this to execute Trino SQL query using AWS Athena Engine version 3. In case of error you will get error message, you have to fix your query and try again. You can apply JOIN opperations. You should use only columns from get_database_schema function. You should use columns only for it's tables. You can join tables if needed using provided columns. You should check that column is not empty string before casting it to avoid errors like this INVALID_CAST_ARGUMENT: Cannot cast '' to BIGINT. You should never compare numbers with strings.You should NEVER call this function before get_database_schema has been called in the conversation. You should NEVER use columns names of the wrong table. You should NEVER cast comare number types to strings or char. You should ALWAYS limit query results by maximum 50. You should NEVER compare fields to NULL.",
 "parameters": {
 "type": "object",
 "properties": {
 "sql_query": {
 "type": "string",
 "description": "SQL query, that user asked. Table names has to be inside \"\". Subqueries are only supported for EXISTS, IN and Scalar subquery, A scalar subquery is a non-correlated subquery that returns zero or one row. It is an error for the subquery to produce more than one row. The returned value is NULL if the subquery produces no rows. Example: SELECT COUNT(*) FROM \"first-american-listings\" WHERE facalculateddaysonmarket != '' AND CAST(\"facalculateddaysonmarket\" as BIGINT) > 15. Example: {\"sql_query\": \"SELECT mtg1lender, COUNT(*) as count FROM \"table_09_fulllaunch-first-american-equity-broker-listings-assesor\" WHERE currentoriginallistingdate >= '2022-03-20' GROUP BY mtg1lender ORDER BY count DESC LIMIT 5\"}. To get current date use current_date constant"
 }
 },
 "required": [
 "sql_query"
 ]
 },
 "webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "name": "get_database_schema",
 "description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
 "parameters": {
 "type": "object",
 "properties": {
 "question": {
 "type": "string",
 "description": "what data should be retrived"
 }
 },
 "required": [
 "question"
 ]
 },
 "webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
201400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Function is created

```
{
 "function": {
 "name": "get_database_schema",
 "description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
 "parameters": {
 "type": "object",
 "properties": {
 "question": {
 "type": "string",
 "description": "what data should be retrived"
 }
 },
 "required": [
 "question"
 ]
 },
 "webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | <!--source:api-specifications-->Function name<!--/source--> |
| `description`required | `string` | <!--source:api-specifications-->Function description<!--/source--> |
| `parameters`required | `object` | <!--source:api-specifications-->Function arguments<!--/source--> |
| `webhook_url`required | `string` | <!--source:api-specifications-->Url for function invocation<!--/source--> |

##### Response `201``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Function is created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `function` | `object` | <!--source:api-specifications-->Function configuration<!--/source--> |
| `name`required | `string` | <!--source:api-specifications-->Function name<!--/source--> |
| `description`required | `string` | <!--source:api-specifications-->Function description<!--/source--> |
| `parameters`required | `object` | <!--source:api-specifications-->Function arguments<!--/source--> |
| `webhook_url`required | `string` | <!--source:api-specifications-->Url for function invocation<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`POST` `/system_prompt`

<!--source:api-specifications-->

#### Set System Prompt
<!--/source-->

`setSystemPrompt`

<!--source:api-specifications-->
Set a system prompt for a ChatBot.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "system_prompt": "You are ChatBot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy System prompt is created

```
{
 "system_prompt": "You are ChatBot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | <!--source:api-specifications-->System prompt content<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
System prompt is created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | <!--source:api-specifications-->System prompt content<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`POST` `/temperature`

<!--source:api-specifications-->

#### Set Temperature
<!--/source-->

`setTemperature`

<!--source:api-specifications-->
Set a GPT temperature for a chatbot. The temperature controls the randomness of the text generated by GPT model. Lower temperatures make the model more deterministic and repetitive, while higher temperatures make the model more varied. You can learn more about temperature in the GPT documentation.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "temperature": 0.55
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy System prompt is created

```
{
 "temperature": 0.55
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | <!--source:api-specifications-->GPT Temperature.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
System prompt is created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | <!--source:api-specifications-->GPT Temperature.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`GET` `/functions`

<!--source:api-specifications-->

#### List Functions
<!--/source-->

`listFunction`

<!--source:api-specifications-->
Provides a list of registered functions.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Functions

```
{
 "functions": [
 {
 "name": "get_database_schema",
 "description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
 "parameters": {
 "type": "object",
 "properties": {
 "question": {
 "type": "string",
 "description": "what data should be retrived"
 }
 },
 "required": [
 "question"
 ]
 },
 "webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
 }
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Functions
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `functions` | `array` | <!--source:api-specifications-->Functions<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`GET` `/system_prompt`

<!--source:api-specifications-->

#### Get System Prompt
<!--/source-->

`getSystemPrompt`

<!--source:api-specifications-->
Get a configured system prompt for a ChatBot.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy System prompt

```
{
 "system_prompt": "You are chatbot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
System prompt
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | <!--source:api-specifications-->System prompt content<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`GET` `/temperature`

<!--source:api-specifications-->

#### Get Temperature
<!--/source-->

`getTemperature`

<!--source:api-specifications-->
Get a configured GPT temperature for a ChatBot.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Temperature

```
{
 "temperature": 0.55
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Temperature
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | <!--source:api-specifications-->GPT Temperature.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`GET` `/functions/{name}`

<!--source:api-specifications-->

#### Get Function
<!--/source-->

`getFunction`

<!--source:api-specifications-->
Provides a configuration of the registered function.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Function

```
{
 "function": {
 "name": "get_database_schema",
 "description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
 "parameters": {
 "type": "object",
 "properties": {
 "question": {
 "type": "string",
 "description": "what data should be retrived"
 }
 },
 "required": [
 "question"
 ]
 },
 "webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `get_database_schema` | <!--source:api-specifications-->Function name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Function
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `function` | `object` | <!--source:api-specifications-->Function configuration<!--/source--> |
| `name`required | `string` | <!--source:api-specifications-->Function name<!--/source--> |
| `description`required | `string` | <!--source:api-specifications-->Function description<!--/source--> |
| `parameters`required | `object` | <!--source:api-specifications-->Function arguments<!--/source--> |
| `webhook_url`required | `string` | <!--source:api-specifications-->Url for function invocation<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`DELETE` `/functions/{name}`

<!--source:api-specifications-->

#### Delete Function
<!--/source-->

`deleteFunction`

<!--source:api-specifications-->
Delete a registered function.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `get_database_schema` | <!--source:api-specifications-->Function name<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`204`

## Others in Platform

- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory