> ## 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.

# Mensagens

> Envie um histórico de conversa para o Canvas junto com as suas variáveis

Um Canvas pode receber uma conversa além das suas variáveis. O array `messages` carrega esse histórico: o que o usuário disse e o que o assistente respondeu antes, em ordem. Use-o para construir experiências de chat em cima de um Canvas, ou para dar ao modelo um contexto que não cabe em uma variável.

`messages` é opcional e funciona junto com `variables`: o prompt do Canvas continua sendo renderizado com as variáveis, e as mensagens são acrescentadas à conversa.

## Formato da mensagem

Cada mensagem tem um `role` e um `content`:

* `role` é `user` ou `assistant`.
* `content` é o texto da mensagem. Também pode ser um arquivo; veja [Arquivos e imagens nas mensagens](#arquivos-e-imagens-nas-mensagens).

A ordem importa. O array é o fluxo cronológico da conversa, então coloque a mensagem mais antiga primeiro. Um histórico típico alterna mensagens `user` e `assistant`.

```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?" }
        ]
    }'
```

A resposta volta como sempre em `choices[0].message.content`. Para continuar a conversa, acrescente a resposta do assistente e a próxima mensagem do usuário ao array e chame de novo: a API não guarda a conversa entre chamadas.

## Arquivos e imagens nas mensagens

Além de uma string, `content` aceita uma referência de arquivo com `file_url`, nos mesmos formatos aceitos pelas [variáveis de arquivo](https://docs.tela.com/pt/completion-api/variables-and-files.md#arquivos):

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

O conteúdo também pode ser escrito como partes de conteúdo, o formato usado quando uma execução é registrada: uma parte de texto `{ "type": "text", "text": "…" }` ou uma parte de imagem `{ "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?",
        },
    },
],
```

Arquivos enviados em mensagens aparecem na execução registrada em `input_content.files` com `used_at: "messages"` e um `name` como `message-0`, em que o número é a posição da mensagem no array.

> [!TIP]
>
> Tanto as `messages` quanto as `variables` de uma execução ficam guardadas em `input_content` e `raw_input`, então você pode inspecionar exatamente o que foi enviado ao [consultar ou listar execuções](https://docs.tela.com/pt/completion-api/async-and-webhooks.md#listando-execucoes-anteriores).


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