# AI Message

An AI Message is one turn of an [AI Chat](https://docs.starkinfra.com/api/v2/ai-chat.md). Posting a message is how you talk to an agent: you send the user's text and the same call returns both the message you sent and the agent's answer.

Every answer carries three payloads. `text` is the full reply, in Markdown. `speech` is a short spoken version of it, ready for [AI Speech](https://docs.starkinfra.com/api/v2/ai-speech.md), and is only filled when the agent has a voice. `metadata` holds the structured fields declared in the agent's `metadataSchema`.

The agent reads the last 20 messages of the chat, and the chat's `context` when one was set, before answering. When the agent has knowledge bases attached, it also retrieves the passages most relevant to the question and answers from them.

### The AI Message object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the AI Message. |
| `chatId` | STRING | Id of the AI Chat this message belongs to. |
| `sender` | STRING | Who wrote the message. Options: "user", "system". The agent's answers are sent by "system". |
| `text` | STRING | Full content of the message. Agent replies may contain Markdown. |
| `speech` | STRING | Short spoken version of `text`: plain conversational text, no Markdown, no URLs, at most two sentences. Empty string when the agent has no voice. For user messages, it mirrors `text`. |
| `metadata` | OBJECT | Structured fields extracted by the agent, following its `metadataSchema`. Empty object when the agent declares no schema. |
| `model` | STRING | AI model that produced this turn. Options: "bender-1.0", "prime-1.0". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Send an AI Message

`POST /v2/ai-message`

Post the user's text to a chat and get the agent's answer back in the same response. The `messages` array holds two entries in order: the message you sent and the reply the agent produced.

This call is synchronous and runs the model, so it is slower than the rest of the API. Size your client timeouts accordingly.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `chatId` | REQUIRED | Id of the AI Chat to post to. |
| `text` | REQUIRED | Content of the user's message. Between 1 and 50000 characters. |
| `model` | OPTIONAL | AI model to use for this turn only. Options: `bender-1.0`, `prime-1.0`. Defaults to the agent's own model. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `chatName`, which returns the chat title alongside the messages — useful on the first turn, when the title is generated. |

**Request**

```python
import starkinfra

messages = starkinfra.aimessage.create(
    starkinfra.AiMessage(
        chat_id="3131313131313131",
        text="My order 1234 was supposed to arrive yesterday and it did not. What can I do?"
    ),
    expand=["chat_name"]
)

for message in messages:
    print(message)
```

**Response**

```python
AiMessage(
    chat_id=3131313131313131,
    chat_name=Order 1234 not delivered,
    created=2022-01-01 00:00:00,
    id=2020202020202020,
    metadata={},
    model=bender-1.0,
    sender=user,
    speech=My order 1234 was supposed to arrive yesterday and it did not. What can I do?,
    text=My order 1234 was supposed to arrive yesterday and it did not. What can I do?
)
AiMessage(
    chat_id=3131313131313131,
    chat_name=Order 1234 not delivered,
    created=2022-01-01 00:00:00.001000,
    id=2121212121212121,
    metadata={'intent': 'shipping', 'isEscalation': False},
    model=bender-1.0,
    sender=system,
    speech=I am sorry about the delay. I can open a delivery check for order 1234 right now.,
    text=I am sorry about the delay on order **1234**.

    Here is what we can do:

    - Open a delivery check with the carrier, which takes up to 2 business days.
    - Reship the order at no cost if the carrier confirms the package was lost.

    Would you like me to open the delivery check now?
)
```

### List AI Messages

`GET /v2/ai-message`

Get messages, newest first, in chunks of at most 100, from a single chat when `chatId` is sent or from every chat in your workspace when it is omitted.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `chatId` | OPTIONAL | Id of the AI Chat whose messages you want. An unknown or deleted chat returns `invalidChatId`. |
| `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

messages = starkinfra.aimessage.query(
    chat_id="3131313131313131",
    limit=10
)

for message in messages:
    print(message)
```

**Response**

```python
AiMessage(
    chat_id=3131313131313131,
    chat_name=None,
    created=2022-01-01 00:00:00.001000,
    id=2121212121212121,
    metadata={'intent': 'shipping', 'isEscalation': False},
    model=bender-1.0,
    sender=system,
    speech=I am sorry about the delay. I can open a delivery check for order 1234 right now.,
    text=I am sorry about the delay on order **1234**.
)
AiMessage(
    chat_id=3131313131313131,
    chat_name=None,
    created=2022-01-01 00:00:00,
    id=2020202020202020,
    metadata={},
    model=bender-1.0,
    sender=user,
    speech=My order 1234 was supposed to arrive yesterday and it did not. What can I do?,
    text=My order 1234 was supposed to arrive yesterday and it did not. What can I do?
)
```

## 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-message-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ai-message-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ai-message-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ai-message-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ai-message-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ai-message-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ai-message-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ai-message-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ai-message-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ai-message-curl.md)