# AI Chat

An AI Chat is a conversation thread with one [AI Agent](https://docs.starkinfra.com/api/v2/ai-agent.md). It carries the message history the agent reads before answering, what the agent knows about your end user and the title shown in your interface.

Open a chat once per conversation and keep posting [AI Messages](https://docs.starkinfra.com/api/v2/ai-message.md) to it. The agent reads the last 20 messages of the thread as context, so the same chat gives you continuity and a new chat gives you a clean slate.

The first message you post names the chat automatically: the title is generated from what the user wrote, unless you set one yourself at creation time.

Send `context` with what the agent should know about your end user — their name, balance or contracted products — and the agent reads it before every reply. Send `tags`, such as your end user's id, to find their conversations later with `GET /v2/ai-chat?tags=customer-123`.

### The AI Chat object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the AI Chat. |
| `agentId` | STRING | Id of the AI Agent that answers in this chat. |
| `title` | STRING | Title of the conversation, set by you or generated from the first message. |
| `tags` | LIST OF STRINGS | Lowercase strings attached to the chat for future queries. Empty list when none was set. |
| `context` | OBJECT | Data about the person on the other side of the chat that the agent reads before every reply. Empty object when none was set. |
| `agentName` | STRING | Name of the agent that answers in this chat. Only returned when `expand=agentName` is sent. |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create an AI Chat

`POST /v2/ai-chat`

Open a conversation thread against an agent. Save the returned `id` — every message you post afterwards references it as `chatId`.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `agentId` | REQUIRED | Id of the AI Agent that will answer in this chat. |
| `title` | OPTIONAL | Title of the conversation. Up to 100 characters. When omitted, the first message posted to the chat generates one. |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the chat for future queries, such as the id of your end user. Each tag holds up to 100 characters and is stored in lowercase. Example: ["customer-123", "whatsapp"]. |
| `context` | OPTIONAL | Object with data about your end user that the agent should know before answering, such as their name, balance or contracted products. Up to 16384 bytes. The agent treats it as reference data, never as instructions. Example: {"name": "Ana", "balance": 1520.33, "products": ["pix", "card"]}. |

**Request**

```python
import starkinfra

chat = starkinfra.aichat.create(
    starkinfra.AiChat(
        agent_id="4242424242424242",
        title="Order 1234 not delivered",
        tags=["customer-123", "whatsapp"],
        context={
            "balance": 1520.33,
            "name": "Ana",
            "products": ["pix", "card"]
        }
    )
)

print(chat)
```

**Response**

```python
AiChat(
    agent_id=4242424242424242,
    agent_name=None,
    context={'balance': 1520.33, 'name': 'Ana', 'products': ['pix', 'card']},
    id=3131313131313131,
    tags=['customer-123', 'whatsapp'],
    title=Order 1234 not delivered,
    updated=2022-01-01 00:00:00
)
```

### List AI Chats

`GET /v2/ai-chat`

Get the chats in your workspace, newest first, in chunks of at most 100.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `tags` | OPTIONAL | Comma-separated list of up to 30 tags. Returns the chats that contain any of them. |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `agentName`. When `fields` is also sent, the expanded attribute must be listed there too. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results, returned by the previous call. |

**Request**

```python
import starkinfra

chats = starkinfra.aichat.query(expand=["agent_name"])

for chat in chats:
    print(chat)
```

**Response**

```python
AiChat(
    agent_id=4242424242424242,
    agent_name=Support Assistant,
    context={'balance': 1520.33, 'name': 'Ana', 'products': ['pix', 'card']},
    id=3131313131313131,
    tags=['customer-123', 'whatsapp'],
    title=Order 1234 not delivered,
    updated=2022-01-01 00:00:00
)
```

### Get an AI Chat

`GET /v2/ai-chat/:id`

Get a single chat by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the chat entity. |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `agentName`. |

**Request**

```python
import starkinfra

chat = starkinfra.aichat.get("3131313131313131")

print(chat)
```

**Response**

```python
AiChat(
    agent_id=4242424242424242,
    agent_name=None,
    context={'balance': 1520.33, 'name': 'Ana', 'products': ['pix', 'card']},
    id=3131313131313131,
    tags=['customer-123', 'whatsapp'],
    title=Order 1234 not delivered,
    updated=2022-01-01 00:00:00
)
```

### Update an AI Chat

`PATCH /v2/ai-chat/:id`

Rename a chat or hand it to another agent. Handing over keeps the message history, so the new agent reads everything that was said before.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the chat entity. |
| `title` | OPTIONAL | New title for the conversation. Up to 100 characters. |
| `agentId` | OPTIONAL | Id of the AI Agent that should answer from now on. |
| `tags` | OPTIONAL | New list of up to 100 strings to tag the chat. Replaces the stored list as a whole. Omit it to keep the current tags, or send an empty list to remove them. |
| `context` | OPTIONAL | New data about your end user. Replaces the stored object as a whole and is used from the next message on, so update it when the data changes, such as the balance after a payment. Omit it to keep the current context, or send an empty object to remove it. |

**Request**

```python
import starkinfra

chat = starkinfra.aichat.update(
    "3131313131313131",
    agent_id="5050505050505050"
)

print(chat)
```

**Response**

```python
AiChat(
    agent_id=5050505050505050,
    agent_name=None,
    context={'balance': 1520.33, 'name': 'Ana', 'products': ['pix', 'card']},
    id=3131313131313131,
    tags=['customer-123', 'whatsapp'],
    title=Order 1234 not delivered,
    updated=2022-01-02 00:00:00
)
```

### Delete AI Chats

`DELETE /v2/ai-chat`

Delete up to 100 chats at once. The ids travel in the query string, not in the body.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `ids` | REQUIRED | Comma-separated list of chat ids to delete. Between 1 and 100 ids. |

**Request**

```python
import starkinfra

chats = starkinfra.aichat.delete(ids=["3131313131313131"])

for chat in chats:
    print(chat)
```

**Response**

```python
AiChat(
    agent_id=4242424242424242,
    agent_name=None,
    context={'balance': 1520.33, 'name': 'Ana', 'products': ['pix', 'card']},
    id=3131313131313131,
    tags=['customer-123', 'whatsapp'],
    title=Order 1234 not delivered,
    updated=2022-01-02 00:00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/ai-chat-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ai-chat-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ai-chat-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ai-chat-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ai-chat-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ai-chat-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ai-chat-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ai-chat-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ai-chat-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ai-chat-curl.md)