Messages

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.

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.

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?',
        },
    ],
})

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?',
        },
    ],
})

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?",
        },
    ],
)

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:

HTTP body

"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" } }.

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

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.

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.

Get started

Build

Test

Operate

Integrate

Message shape

Files and images in messages

​Message shape

​Files and images in messages

Message shape

Files and images in messages