> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

> Send a chat history to the Canvas along with its variables

A Canvas can receive a conversation in addition to its variables. The `messages` array carries that history: what the user said and what the assistant answered before, in order. Use it to build chat experiences on top of a Canvas, or to give the model context that does not fit a variable.

`messages` is optional, and it works together with `variables`: the Canvas prompt is still rendered with the variables, and the messages are added to the conversation.

## Message shape

Each message has a `role` and a `content`:

* `role` is `user` or `assistant`.
* `content` is the text of the message. It can also be a file; see [Files and images in messages](#files-and-images-in-messages).

Order matters. The array is the chronological flow of the conversation, so put the oldest message first. A typical history alternates `user` and `assistant` messages.

```typescript TypeScript Tela SDK theme={null}
const completion = await tela.completions.create<{ document: TelaFile }, { answer: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
    },
    messages: [
        {
            role: 'user',
            content: 'What is the total amount of this invoice?',
        },
        {
            role: 'assistant',
            content: 'The total amount is 381.12 EUR.',
        },
        {
            role: 'user',
            content: 'And when is it due?',
        },
    ],
})
```

```javascript JavaScript Tela SDK theme={null}
const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
    },
    messages: [
        {
            role: 'user',
            content: 'What is the total amount of this invoice?',
        },
        {
            role: 'assistant',
            content: 'The total amount is 381.12 EUR.',
        },
        {
            role: 'user',
            content: 'And when is it due?',
        },
    ],
})
```

```python Python Tela SDK theme={null}
completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
    },
    messages=[
        {
            "role": "user",
            "content": "What is the total amount of this invoice?",
        },
        {
            "role": "assistant",
            "content": "The total amount is 381.12 EUR.",
        },
        {
            "role": "user",
            "content": "And when is it due?",
        },
    ],
)
```

```sh cURL theme={null}
curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
        "variables": {
            "document": { "file_url": "https://www.wmaccess.com/downloads/sample-invoice.pdf" }
        },
        "messages": [
            { "role": "user", "content": "What is the total amount of this invoice?" },
            { "role": "assistant", "content": "The total amount is 381.12 EUR." },
            { "role": "user", "content": "And when is it due?" }
        ]
    }'
```

The answer comes back as usual in `choices[0].message.content`. To continue the conversation, append the assistant answer and the next user message to the array and call again: the API does not keep the conversation between calls.

## Files and images in messages

Besides a string, `content` accepts a file reference with a `file_url`, in the same formats accepted by [file variables](https://docs.tela.com/en/completion-api/variables-and-files.md#files):

```json HTTP body theme={null}
"messages": [
    { "role": "user", "content": { "file_url": "https://example.com/contract.pdf" } },
    { "role": "user", "content": "Summarize the termination clause." }
]
```

Content can also be written as content parts, the format used when a run is recorded: a text part `{ "type": "text", "text": "…" }` or an image part `{ "type": "image_url", "image_url": { "url": "…", "detail": "auto" | "high" | "low" } }`.

```typescript TypeScript Tela SDK theme={null}
messages: [
    {
        role: 'user',
        content: {
            type: 'image_url',
            image_url: {
                url: 'https://example.com/image.png',
                detail: 'high',
            },
        },
    },
    {
        role: 'user',
        content: {
            type: 'text',
            text: 'What does this receipt say?',
        },
    },
],
```

```python Python Tela SDK theme={null}
messages=[
    {
        "role": "user",
        "content": {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/image.png",
                "detail": "high",
            },
        },
    },
    {
        "role": "user",
        "content": {
            "type": "text",
            "text": "What does this receipt say?",
        },
    },
],
```

Files sent in messages appear in the recorded run under `input_content.files` with `used_at: "messages"` and a `name` such as `message-0`, where the number is the position of the message in the array.

> [!TIP]
>
> Both the `messages` and the `variables` of a run are kept in `input_content` and `raw_input`, so you can inspect exactly what was sent when you [fetch or list runs](https://docs.tela.com/en/completion-api/async-and-webhooks.md#listing-past-runs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.