Requirements:

​
Get your canvas data

We need two things to start using our canvas:
  1. API Key
  2. The canvas ID
We can find both in the same place.
1

Open deploy options

First click on deploy button at the right top corner of the application interface. This will open the deploy options.Deploy
2

Open Connect via API

There you will find how to deploy apps and how to connect to the API, click on “Or connect directly via API” at the bottom of the modal.Deploy
3

Get your canvas data

Here you will find all the necessary info to start integrating! Choose your preferred language to get started.Deploy

​
Constructing the Canvas Call Body

To achieve the desired behavior for your business and integration, your canvas call can include variables, historical messages, streaming, and webhook responses for asynchronous integrations.
Check out API Reference for further details on our SDK and API specifications.

​
Using Variables

Variables are a key concept in prompt building with Tela. They are used to store and reuse data throughout your prompts and can be either a manual input or a file.
For information on supported file formats, visit Supported files.
When we have defined variables at our prompt the connect modal will generate the code snippets for us already filled with the variables keys. Deploy Fill the keys with the values you want, it can be a text, a file url or a file base64 string. 
variables: {
    document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'), // It is possible to pass a URL, Buffer, Blob, etc.
},
Check out file usage details with our SDK

​
Using Messages

The Tela API allows you to include messages in your requests by extending the request body with the messages key. This feature enables you to provide context or additional information to the model, enhancing the interaction and output quality. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    messages: [
        {
            role: 'user',
            content: {
                type: 'text',
                text: 'Hello, how can I assist you today?'
            }
        },
        {
            role: 'assistant',
            content: {
                type: 'image_url',
                image_url: {
                    url: 'https://example.com/image.png',
                    detail: 'high'
                }
            }
        }
    ]
})
The sequence of messages in the array is crucial as it represents the chronological flow of the conversation. Each cycle begins with a user’s message and is followed by the assistant’s response, maintaining the dialogue’s context and coherence.
Check out Running a Canvas API Reference body for further details on the message schema.

​
Streaming

To enable streaming for the canvas call, simply include the stream key set to true in the request body. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    stream: true
})
See Streaming API Reference for more details consuming the stream.

​
Async

To achieve asynchronous behavior, you have two options:
  • Using the async flag
  • Using a webhook

​
Using Async flag

Extending the body with an async key set to true is the easiest way to achieve asynchronous behavior, allowing you to continue with other tasks while waiting for the completion. An id will be returned so you can monitor the status of the call. 
curl -XPOST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer API-KEY' \
    -d '{
        ...,
        "async": true
    }'
See Get completion API Reference for how to consume the completion with the received id

​
Using Webhook

You can pass a webhook url to our API extending the body with an webhook_url key, this will make the completion asynchronous, and you will receive the response when the completion is finished with a POST request on the url you provided. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    webhook_url: "https://example.com/webhook"
})
When the webhook_url key is used, the call becomes asynchronous automatically, eliminating the need to include the async flag.