Integrations

What is the "Integration" block?

The "Integration" block allows your bot to interact with third-party services—such as OpenAI, Google Sheets, and others—directly within the scenario flow. The bot sends a request, receives a response, and saves the result into variables.

Connecting a service

Before using the integration block, you need to create a connection to the service:

1. Click the "Integrations" button in the builder's header.
2. Select the desired service from the list.
3. Enter the authorization details:

• API Key — for OpenAI and other services requiring a key.
• OAuth2 — for Google (authorization via Google account).
• Service Account — for Google (service account JSON file).

4. Click "Test" — the system will verify the connection.
5. Save the connection.

A single connection can be used in multiple blocks across the same bot or different bots.

Configuring the integration block

1. Add the "Integration" block to the desired node.
2. Select the service (e.g., OpenAI).
3. Select a connection from the list of created connections.
4. Select an operation (e.g., "Send message").
5. Fill in the operation parameters.
6. Specify the result variable prefix (default is result).

After the block executes, the result will be available as {{result.field}}.

Transition on integration error

At the bottom of every integration block, there is an "Error transition" section.

If the integration fails (e.g., service unavailable, quota exceeded, invalid response), the bot will:

1. Notify the bot owner about the issue (if notifications are enabled).
2. Halt the execution of any remaining blocks in the current node. 3. Proceeds to the error node specified in the "Integration error" field.

If the "Integration error" field is left blank, the bot continues executing the scenario as usual (following the standard path after the node), which may lead to incorrect behavior.

Recommendations

• Always specify an error node for integrations that are critical to the scenario (AI responses, TTS, database queries, etc.).
• In the error node, you can send a user-friendly message such as: "Service temporarily unavailable; please try again later."
• The "+ Create" button next to the field automatically creates a new node and links it to the integration block.
• The connection to the error node is displayed on the diagram as a yellow arrow labeled "Integration error".

Important: If a single node contains multiple integration blocks, and the first one fails, the remaining blocks will not execute—the bot immediately proceeds to the error node.

Testing the block

The block editor features a "Test" button; it executes the operation using the current parameters and displays which variables will be set. This is useful for verifying requests before publishing.

OpenAI

Send Message (Chat)

Sends a request to ChatGPT and receives a text response.

Remember dialogue

Allows saving the conversation history and passing it to each subsequent request to the model, creating a "memory" effect. The history is stored in the database.

When "Display preliminary message" is enabled, two additional fields appear:

Typical scenario using a preliminary message:

1. "Integration" block → enable "Show preliminary message" → variable "message_id".
2. AI response is saved to "{{result.text}}".
3. Next "Text" block with "{{result.text}}" → in "Advanced" settings, enable "Edit message" → specify variable "{{message_id}}".
4. The bot edits the preliminary message, replacing the placeholder with the AI ​​response.

Generate image

Creates an image based on a text description (DALL·E 3, GPT-image-1, etc.).

Result variables:

Analyze image (Vision)

Ask a question about an image — the model answers based on the image content.

Result: {{result.text}} — the model's text response.

Transcribe audio (Whisper)

Converts a voice message or audio file into text.

Result: {{result.text}} — the transcribed text.

Typical scenario: the user sends a voice message → the "Data Input" block saves the file_id → the Whisper integration block transcribes it → the variable {{result.text}} becomes available in subsequent blocks.

Get Model List (OpenAI)

Queries the OpenAI API and saves the array of models available in your account to the specified variable.

No parameters are required—simply specify the variable where the result will be stored.

Result: {{result}} — an array of objects. Available properties for each element (where N is the index starting at 0):

Click Test in the editor to verify functionality and view the list of models. The data will be accessible via {{result.0.id}}, {{result.1.id}}, etc.

React to Message (OpenAI)

The AI ​​analyzes the user's message text and selects one emoji from an allowed list; the bot then applies this reaction to the specified message via the Telegram API.

Result variables (using the result prefix):

Behavior when no reaction is returned: If the AI ​​returns "null", an empty string, or an emoji not on the allowed list, no reaction is set, the "selected_emoji" variable remains an empty string, and scenario execution continues.

Anthropic Claude

Send Message

Sends a request to Claude and receives a text response. Supports the same conversation memory and pre-message capabilities as OpenAI Chat.

Result variables (using the result prefix):

Remember Dialogue

Similar to the OpenAI → Remember Dialogue section, all settings (memory duration, maximum messages, dialogue name, title generation, dialogue ID, ID variable, initial message) function the same way for Claude.

Get Model List (Anthropic)

Queries the Anthropic API and saves the array of available Claude models to the specified variable.

No parameters are required—simply specify the variable where the result will be stored.

Result: {{result}} — an array of objects (sorted by created_at descending). Available properties for each element (where N is the index starting at 0):

Click Test in the editor to verify functionality. After testing, autocomplete options such as {{result.0.id}}, {{result.1.id}}, etc., will become available in the editor.

React to Message (Claude)

Identical to the OpenAI → React to Message operation: The Claude AI analyzes the message text and selects a reaction from an allowed list, after which the bot applies it via the Telegram API.

Result variable: {{result.selected_emoji}} — the selected emoji (empty if the AI ​​could not make a selection).

Google Sheets

Connection

Two authorization methods are supported:

• OAuth2 — authorization via Google account. Create an OAuth2 client in the Google Cloud Console (type: Web application), enable the Google Sheets API and Google Drive API, and add the redirect URI.
• Service account — service account JSON key. After creating the account, open the relevant spreadsheets and grant the service account email access (Editor role).

The connection type is selected upon creation and cannot be changed later. To switch authorization methods, create a new connection.

Get Row

Searches for a row in a Google Sheet based on a value in a specified column.

Result variable names correspond to the spreadsheet's column headers:

{{result.Email}} → value of the "Email" column in the found row {{result.Имя}} → value of the "Имя" (Name) column {{result.Телефон}} → value of the "Телефон" (Phone) column

If the row is not found, the variables will be empty.

Add Row

Adds a new row to the end of the sheet.

Does not return variables. Use this to save submissions, user responses, or logs.

Add or Update Record

Searches for a row based on a value in a specified column. If the row is found, it updates it. If not, it adds a new row to the end of the sheet.

Does not return variables.

Update Record

Finds a row based on a value in a specified column and updates its data.

If the row is not found, no update is performed. Returns no variables.

Get Records

Returns all rows in the sheet that match the specified filters.

Result when "Return first row" is enabled (same as "Get Row"):

""" {{result.ColumnName}} → column value in the found row """

Result when "Return first row" is disabled:

Clear Sheet

Clears cell contents without deleting the sheet itself.

Does not return any variables.

Delete Rows or Columns

Deletes the specified rows or columns and shifts the remaining ones.

Does not return any variables.

Create Sheet

Adds a new tab to an existing spreadsheet.

Does not return any variables.

Delete Sheet

Deletes a tab from the spreadsheet along with all its data.

Does not return any variables.

Google Drive

Manage Google Drive files, folders, and shared drives directly from the bot.

Connection

Two authorization methods are supported:

• OAuth2 — Authorization via a Google account. Create an OAuth2 client in the Google Cloud Console (type: Web application), enable the Google Drive API, and add the redirect URI shown when creating the connection.
• Service Account — Service account JSON key. After creating the account, grant its email address access to the required Google Drive folders or files.

The connection type is selected upon creation and cannot be changed later. To change the authentication method, create a new connection.

File Actions

Copy File

Result variables (using the result prefix):

Create File from Text

Creates a text file from the content of a variable.

Result variables are the same as for "Copy File" (file_id, name, webViewLink).

Delete File

Returns no variables.

Download File

Downloads a file from Google Drive and saves it for further use.

Result variables:

Move File

Result variables: {{result.file_id}}, {{result.name}}.

Share File

Grants access to the file to a user, group, domain, or everyone.

Result variables: {{result.permission_id}}, {{result.role}}, {{result.type}}.

Update File

Upload File

Uploads a file from the specified URL to Google Drive.

If the URL starts with a local Telegram Bot API address, the file is read directly from the server without an HTTP download.

Result variables: {{result.file_id}}, {{result.name}}, {{result.webViewLink}}, {{result.mimeType}}.

Search Files and Folders

Find Files and Folders

Searches Google Drive using Drive Query Language syntax.

Result variables:

Folder Actions

Create Folder

Result variables: {{result.folder_id}}, {{result.name}}, {{result.webViewLink}}.

Cloudflare R2

Cloudflare R2 is S3-compatible object storage. It is suitable for storing files accessible via direct URLs.

Connection

1. Open the Cloudflare Dashboard → R2 Object Storage → your bucket → Settings tab.
2. Locate the S3 API field—it looks like "https://<account_id>.r2.cloudflarestorage.com/". The "<account_id>" part is your Account ID.
3. Go to R2 → Manage R2 API Tokens → Create API Token.
4. Select Object Read & Write permissions (or restrict access to a specific bucket) and save.
5. Copy the Access Key ID and Secret Access Key.

Paste the JSON into the connection field:

"""json { "account_id": "abc123...", "access_key_id": "...", "secret_access_key": "...", "bucket_name": "my-bucket", "public_url": "https://pub-xxx.r2.dev" } """

"public_url" — an optional field. Required to obtain direct links to files after uploading. Where to get it:

• Public Development URL (for testing): Bucket Settings → Public Development URL section → click Enable. Once enabled, copy the generated URL (e.g., "https://pub-xxx.r2.dev").
• Custom domain (for production): Settings → Custom Domains → Add.

If neither is configured, leave the field blank; "{{result.public_url}}" will be an empty string.

Upload file

Uploads a file to R2 via URL or from the bot's internal storage.

Result variables:

Delete file

The operation does not return a result.

List files

Returns a list of objects in the bucket.

Result variables:

Copy file

Copies an object within the bucket without re-uploading it.

Result variables: {{result.key}}, {{result.public_url}}.

File information

Returns object metadata (without downloading the content).

Result variables:

Delete folder

Returns no variables.

Share folder

Similar to "Share file" — same parameters and result, but for a folder.

Shared drive actions

Create shared drive

Result variables: {{result.drive_id}}, {{result.name}}.

Delete shared drive

Returns no variables.

Get shared drive

Result variables: {{result.drive_id}}, {{result.name}}, {{result.created_time}}.

List Shared Drives

Result variables: {{result.drives}} — array of drives · {{result.count}} — count.

Update Shared Drive

Result variables: {{result.drive_id}}, {{result.name}}.

Google Calendar

Manage Google Calendar events: create, retrieve, update, delete, and check availability.

Connection

Two authorization methods are supported:

• OAuth2 — authorization via a Google account. You must create an OAuth2 client in the Google Cloud Console (type: Web application), enable the Google Calendar API, and add a redirect URI.
• Service Account — service account JSON key. After creating the account, share the required calendars with the service account's email address in the Calendar settings.

Create Event

Additional parameters ("Advanced" section):

Result variables (using the result prefix):

Delete event

Returns no variables.

Get event

Result variables (with the result prefix):

Get events

Result variables:

Use {{result.count}} in the "Condition" block to check for the presence of events.

Update Event

Required parameters: Calendar and Event ID. All other fields (title, time, description, etc.) are optional—only the specified fields are updated.

Use the "Advanced" parameters—all the same fields available when creating an event are accessible there.

Result variables — the same as for "Create Event" (id, summary, status, htmlLink, start, end).

Calendar Availability

Checks if the specified time range is free in the calendar (uses the Google Calendar FreeBusy API).

Result variables:

Editing a message in the "Text" block

The "Edit message" option is available in the "Text" block under the "Advanced" section.

When enabled, instead of sending a new message, the bot edits an existing one—replacing its text with the content of the block.

1. "Integration" block (OpenAI / Claude) → enable "Output preliminary message" → set an ID variable, e.g., "message_id".
2. While the AI ​​generates the response, the user sees a placeholder.
3. Next, a "Text" block containing the response text "{{result.text}}" → "Advanced" → "Edit message" → "{{message_id}}".
4. The bot edits the preliminary message: the placeholder is replaced by the final response.

If the variable is empty or the specified ID does not exist, the block will send the message as standard text.

ElevenLabs

ElevenLabs is an AI-powered voice platform offering high-quality text-to-speech, speech recognition, voice changing, voice cloning, and sound effect generation.

Connection

1. Sign up at elevenlabs.io.
2. Go to Settings → API Keys → click Create API Key.
3. Copy the generated key and paste it into the connection field.
4. Click "Check" — the system will verify API access.

The ElevenLabs free plan has a monthly character limit. Voice cloning requires a paid "Creator" plan or higher.

Text-to-Speech

Converts text into an audio file using the selected voice.

Additional parameters:

Result variables (using the result prefix):

Important: The audio file link is available for 24 hours, after which it is automatically deleted. Typical scenario — announcer bot:

1. "Integration" block → ElevenLabs → Text-to-Speech → select voice → text "{{news_text}}".
2. Next block "Audio" → specify "{{result.url}}" in the "file_id or URL" field.
3. The bot sends the synthesized news as an audio message.

Speech Recognition (Speech-to-Text)

Converts a voice message or audio file into text (Scribe series models).

Additional parameters:

Result variables:

Typical scenario — voice assistant:

1. "Data Input" block → saves the voice message to the "voice_input" variable. 2. Integration block → Recognize speech → "file_id: {{voice_input}}" → "{{result.text}}".
2. Integration block → OpenAI / ChatGPT → "{{result.text}}" → response "{{ai.text}}".
3. Text block → "{{ai.text}}".

Voice Conversion (Speech-to-Speech)

Replaces the voice in an audio recording while preserving the original's intonation and emotions.

Additional parameters: Model, Audio format, Stability, Similarity boost.

Result variables: {{result.url}} — Audio file URL · {{result.request_id}}.

Important: The audio file link is available for 24 hours, after which it is automatically deleted.

Generate Sound Effect

Generates audio based on a text description: natural sounds, noise, technical sounds.

Additional parameters: Prompt influence (0–1), Audio format.

Result variables: {{result.url}} — Audio file URL.

Important: The audio file link is available for 24 hours, after which it is automatically deleted.

Music for Video (Video-to-Music)

Generates a musical soundtrack for a video file—automatically matching the tempo, mood, and instrumentation.

Additional parameters: Audio format. Result variables: {{result.url}} — URL of the audio file containing the music.

Important: The link to the audio file is available for 24 hours, after which it is automatically deleted.

Clone Voice (Instant Voice Cloning)

Creates a digital copy of a voice based on a short audio recording (ranging from a few seconds to a minute). The cloned voice is saved to your ElevenLabs account and can be used in the "Text-to-Speech" operation.

Additional parameters: Voice description, Remove background noise.

Result variables:

Typical scenario — a bot's personal voice:

1. "Input Data" block → user sends a voice message → "voice_sample".
2. "Integration" block → Clone Voice → "name: My Voice", "file_id: {{voice_sample}}" → "{{result.voice_id}}".
3. Save "{{result.voice_id}}" to the database.
4. In subsequent scenarios: "Integration" block → Text-to-Speech → "voice_id: {{saved_voice_id}}".

Voice cloning requires a paid ElevenLabs Creator plan or higher.

Tips for working with integrations

• Save integration results into variables with clear names, such as ai_answer or sheet_row.
• Use a "Condition" block after the integration to verify whether the operation successfully retrieved the required data.
• Test the block directly within the editor using the "Test" button; this saves time during development.
• When using AI conversation memory, enable "Generate conversation titles"; this makes it easier to navigate the chat history in future versions of the dashboard.
• For complex scenarios involving multiple AI blocks, use the "Conversation ID variable" so that each block explicitly interacts with the correct conversation, rather than defaulting to the "last" one.
• If the bot handles sensitive user data, enable "Encrypt data" in the conversation memory settings; messages will be stored in the database in encrypted form.

Supabase

Supabase is an open-source alternative to Firebase built on PostgreSQL. The integration allows you to perform CRUD operations on tables via the Supabase REST API (PostgREST) ​​directly from the bot scenario.

Connection

1. Open your project settings: supabase.com/dashboard → your project → Settings → API.
2. Copy the Project URL from the Project URL section.
3. Copy the service_role key (secret) from the Project API keys section.
4. Fill in the two fields in the connection dialog:

5. Click "Check connection"; the system will send an API request to verify the data.
6. Save the connection.

Important: Use the "service_role" key (secret), not the "anon" key. This allows bypassing Row Level Security and interacting with data while ignoring access policies. Keep the key secure.

Create Record

Inserts a new row into the table.

Result variables (using the result prefix):

Delete Record

Deletes rows that match the specified conditions.

Result variables:

Get Record

Retrieves the first row that meets the specified conditions.

Result variables:

If no record is found, the variables are not set.

Get List of Records

Returns an array of rows matching the filters.

Result variables:

Use {{result}} with dynamic buttons (type "Dynamic Buttons") or the "Condition" block to check "{{result.count}}".

Update Record

Updates rows that meet the specified conditions.

Result variables:

Condition operators

The following operators are supported in blocks with conditions (Select Conditions / Filters):

Example: Saving a user lead

1. "Data Input" block — name → "user_name", phone → "user_phone".
2. "Integration" block → Supabase → Create Record:

• Table: "leads"
• Data: "name" → "{{user_name}}", "phone" → "{{user_phone}}", "chat_id" → "{{USER_ID}}"

3. Variable "{{result.id}}" — ID of the created lead in Supabase.

Grok (xAI)

Grok is a powerful language model from xAI that offers capabilities for AI chat, image analysis, media generation, and audio processing.

API Base URL: "https://api.x.ai/v1" API Key: Starts with "xai-". Can be obtained at console.x.ai.

Connection Setup

In the integration settings, enter the API key in the format "xai-...". The "Check Connection" button sends a request to "/models" to verify the key's validity.

Operations

Send Message ("send_message")

Sends a text request to the Grok language model and returns the response.

Parameters:

• "{prefix}.text" — model response text
• "{prefix}.model" — model used
• "{prefix}.tokens_used" — number of tokens consumed
• "{prefix}." — JSON fields (if JSON mode with schema is enabled)

Analyze image ("analyze_image")

Sends an image to the model for visual analysis (Vision API).

Parameters:

Result variables:

• "{prefix}.text" — model response
• "{prefix}.model" — model used
• "{prefix}.tokens_used" — number of tokens consumed

Generate Image ("generate_image")

Generates an image based on a text description using the "grok-imagine-image" model.

Parameters:

Result variables:

• "{prefix}.url" — URL of the generated image (temporary)
• "{prefix}.file_id" — Telegram "file_id" of the first image (stable)
• "{prefix}.file_ids" — Array of Telegram "file_ids" for all images
• "{prefix}.count" — Number of generated images
• "{prefix}.{i}.file_id" — "file_id" of each image by index

Note: Image URLs returned by xAI are temporary. The block automatically uploads the images to Telegram and saves a stable "file_id".

React to Message ("react_to_message")

Analyzes a user message using AI and applies an appropriate emoji reaction in Telegram.

Parameters:

• "{prefix}.selected_emoji" — the selected emoji (or an empty string if the AI ​​decided not to react)

Generate video ("generate_video")

Generates a video clip based on a text description using the "grok-imagine-video" model.

⚠️ Important: Video generation takes 1–5 minutes (sometimes up to 10 minutes). The block performs asynchronous API polling every 5 seconds. Ensure your task queue supports long-running tasks.

Parameters:

Result variables:

• "{prefix}.url" — URL of the finished video (temporary)
• "{prefix}.file_id" — Telegram "file_id" of the video (stable)
• "{prefix}.duration" — video duration in seconds
• "{prefix}.model" — model used

Transcribe audio ("transcribe_audio")

Converts a voice message or audio file from Telegram into text (Speech-to-Text).

Parameters:

Result variables:

• "{prefix}.text" — transcribed text
• "{prefix}.language" — detected language
• "{prefix}.duration" — audio duration in seconds

Text-to-Speech ("text_to_speech")

Synthesizes speech from text and returns a temporary URL for the audio file.

Parameters:

Result variables:

• "{prefix}.url" — temporary URL of the audio file (valid for 24 hours)

The file is automatically deleted 24 hours after generation.

Get Model List ("list_models")

Retrieves the current list of available Grok models.

Result variables:

• "{prefix}" — array of objects with "id" and "created" fields

Model Examples

The current list is available via the "Get Model List" operation.