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

| Parameter | Description |
|---|---|
| Model | GPT-4o, GPT-4o mini, etc. — selected from your account |
| User message | Request text; supports **{{variables}}** |
| System prompt | Instructions for the model — role, style, constraints. Supports Markdown formatting and **{{variables}}**. The **⤢** button opens the editor in full-screen mode |
| Temperature | Degree of response randomness (0–2) |
| Max tokens | Limit on response length | **Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.text}}** | Model response text |
| **{{result.model}}** | Model used |
| **{{result.tokens_used}}** | Tokens consumed |

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

| Parameter | Description |
|---|---|
| **Memory duration (hours)** | Number of hours of inactivity after which the history is reset. **0** — no time limit |
| **Max messages in history** | Number of recent messages to pass to the model with each request. Default: **100** |
| **Default dialogue name** | Name of a new dialogue before an automatic one is generated. Default: **Main** |
| **Generate dialogue names** | If enabled, upon creating a new dialogue, the bot sends a separate background request to the AI ​​to formulate a short title (up to 5 words) based on the user's first message. The title is saved automatically without delaying the response |
| **Encrypt data** | If enabled, user messages and AI responses are stored in the database in encrypted form (AES-256-CBC). Data is automatically decrypted upon each interaction with the AI. Existing unencrypted dialogues remain readable |
| **Dialogue ID** | Load a specific dialogue by its ID. Supports **{{variables}}** (e.g., "{{dialog_id}}"). If not specified, the last active dialogue is used, or a new one is created |
| **Dialogue ID variable** | Name of the variable where the current dialogue ID will be stored. Use it in other blocks to explicitly reference the required dialog |
|**Display preliminary message** | AI can take a long time to generate a response. When enabled, the bot immediately sends a short placeholder message to the user and edits it once the response is ready. This ensures the user feels the bot is responding without delay. |

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

| Parameter | Description |
|---|---|
| **Preliminary message** | Text or emoji for an instant user response (e.g., "⏳ Generating response...") |
| **Variable name for message ID** | The name of the variable where the "message_id" of the sent preliminary message is stored. Defaults to **message_id**. Use this in a "Text" block with **"Edit message"** enabled. |

> **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.).

| Parameter | Description |
|---|---|
| Model | dall-e-3, dall-e-2, gpt-image-1, etc. |
| Description | Prompt text; supports **{{variables}}** |
| References | Up to 5 links to source images. If at least one is specified, the model will automatically switch to `gpt-image-1` if DALL·E was selected. Each field supports **{{variables}}** |
| Size | Image resolution |
| File format | PNG / JPEG / WebP — output file format (only for `gpt-image-*` models) |
| Image quality | Auto / Low / Medium / High (only for `gpt-image-*` models) |
| Transparent background | Generate an image with a transparent background (PNG/WebP only; for `gpt-image-*` models) |
| Quantity | 1–10 images |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.url}}** | Image URL |
| **{{result.revised_prompt}}** | Refined prompt (returned by models that support prompt reformulation) |

---

### Analyze image (Vision)

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

| Parameter | Description |
|---|---|
| Model | GPT-4o, GPT-4 Turbo, and others with Vision support |
| Image URL | Link to the image; supports **{{variables}}** |
| Question | What exactly needs to be identified or described |

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

---

### Transcribe audio (Whisper)

Converts a voice message or audio file into text.

| Parameter | Description |
|---|---|
| file\_id or URL | Telegram file_id of the audio/voice message, or a direct URL; supports **{{variables}}** |
| Model | whisper-1, gpt-4o-transcribe, etc. |
| Language | ISO language code (leave blank for auto-detection) |

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

> Receiving voice/audio files is currently supported on **Telegram** and **Web Widget**.

**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):

| Property | Description |
|---|---|
| **{{result.N.id}}** | Model identifier (e.g., gpt-4o) |
| **{{result.N.object}}** | Object type (always "model") |
| **{{result.N.created}}** | Creation date (Unix timestamp) |
| **{{result.N.owned_by}}** | Model owner (e.g., openai) |

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.

| Parameter | Description |
|---|---|
| Message ID | The ID of the message to react to. Default: **{{USER_MESSAGE_ID}}** (the incoming user message) |
| Reaction List | A grid of the 73 available Telegram emoji reactions—select the ones the AI ​​can choose from |
| User Message | Text to analyze; supports **{{variables}}**. Default: **{{USER_MESSAGE}}** |
| Instruction | System prompt for the AI. A list of allowed emojis is automatically appended to the end of the instruction |
| Model | OpenAI model (default: "gpt-4o-mini"). Located in advanced settings |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.selected_emoji}}** | The selected reaction (empty if the AI ​​could not find a suitable one or returned null) |

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

| Parameter | Description |
|---|---|
| Model | Claude 4.6 Opus, Claude 4.6 Sonnet, Claude 4.5 Sonnet, and others — selected from your account |
| User message | Request text; supports **{{variables}}** |
| System prompt | Instructions for the model — role, style, constraints. Supports Markdown formatting and **{{variables}}**. The **⤢** button opens the full-screen editor |
| Max tokens | Response length limit |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.text}}** | Model's response text |
| **{{result.model}}** | Model used |
| **{{result.tokens_used}}** | Tokens consumed |

#### 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):

| Property | Description |
|---|---|
| **{{result.N.id}}** | Model identifier (e.g., `claude-sonnet-4-6`) |
| **{{result.N.display_name}}** | Model display name |
| **{{result.N.created_at}}** | Creation date (ISO 8601) |
| **{{result.N.type}}** | Object type (always "model") |
| **{{result.N.max_input_tokens}}** | Maximum context tokens |
| **{{result.N.max_tokens}}** | Maximum response tokens |

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.

| Parameter | Description |
|---|---|
| Message ID | The ID of the message to react to. Default: **{{USER_MESSAGE_ID}}** |
| Reaction list | Grid of 73 Telegram emoji reactions — select those allowed for the AI ​​|
| User message | Text to analyze; supports **{{variables}}** |
| Instruction | System prompt; the list of allowed emojis is added automatically |
| Model | Claude model (default: "claude-sonnet-4-6"). Found in advanced settings |

**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](https://console.cloud.google.com/apis/credentials) (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.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| Search Column | Column header to search by |
| Search Value | Value to search for; supports **{{variables}}** |

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.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| Columns and Values ​​| List of "Column → Value" pairs; supports **{{variables}}** |

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.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| Match Column | Column header used to determine uniqueness |
| Search Value | Supports **{{variables}}** |
| Data (Mapping) | List of "Column → Value" pairs; supports **{{variables}}** |

Does not return variables.

---

### Update Record

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

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| Search Column | Column header used to find the row |
| Search Value | Supports **{{variables}}** |
| Update Data | List of "Column → New Value" pairs; supports **{{variables}}** |

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.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| Filters | List of "Column = Value" conditions; returns all rows if no filters are set |
| Filter Combination | **AND** — all conditions; **OR** — at least one |
| Return first matching row *(optional)* | If enabled, returns only the first row found |

**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:**

| Variable | Value |
|---|---|
| **{{result}}** | JSON array of all found rows |
| **{{result.count}}** | Number of found rows |

---

### Clear Sheet

Clears cell contents without deleting the sheet itself.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| What to clear | Entire sheet / Specific rows / Specific columns / Specific range |
| Start row *(optional)* | For "Specific rows" mode |
| Number of rows *(optional)* | For "Specific rows" mode |
| Start column *(optional)* | For "Specific columns" mode (e.g., A) |
| Number of columns *(optional)* | For "Specific columns" mode |
| Range *(optional)* | For "Specific range" mode (e.g., A2:C10) |

Does not return any variables.

---

### Delete Rows or Columns

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

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Tab name |
| What to delete | **Rows** or **Columns** |
| Start Number | Number of the first row/column (1-based index); supports **{{variables}}** |
| Count | Number of rows/columns to delete; supports **{{variables}}** |

Does not return any variables.

---

### Create Sheet

Adds a new tab to an existing spreadsheet.

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| New Sheet Name | Tab name; supports **{{variables}}** |

Does not return any variables.

---

### Delete Sheet

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

| Parameter | Description |
|---|---|
| Spreadsheet ID or URL | Google Sheets identifier |
| Sheet Name | Name of the tab to delete |

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](https://console.cloud.google.com/apis/credentials) (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

| Parameter | Description |
|---|---|
| File | Select from the list or specify the ID |
| New Name | Name of the copy; leave blank to keep the original name. Supports **{{variables}}** |
| Destination Folder *(optional)* | Folder for the copy; if not specified, the copy is created in the same folder |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.file_id}}** | ID of the created copy |
| **{{result.name}}** | Name of the copy |
| **{{result.webViewLink}}** | Link to the file in Google Drive |

---

#### Create File from Text

Creates a text file from the content of a variable.

| Parameter | Description |
|---|---|
| File Name | Supports **{{variables}}** |
| Content | File content; supports **{{variables}}** |
| File Type | Text (.txt), CSV, HTML, JSON |
| Folder *(optional)* | Folder where the file will be saved |

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

---

#### Delete File

| Parameter | Description |
|---|---|
| File | Select from the list or specify the ID |

Returns no variables.

---

#### Download File

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

| Parameter | Description |
|---|---|
| File | Select from the list or specify the ID |
| Export format *(optional)* | For Google Docs/Sheets: PDF, DOCX, XLSX, TXT, CSV. Leave as "Auto" for standard files |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.file_url}}** | URL of the downloaded file |
| **{{result.name}}** | File name |
| **{{result.mime_type}}** | MIME type |
| **{{result.size}}** | Size in bytes |

---

#### Move File

| Parameter | Description |
|---|---|
| File | File to move |
| Destination folder | Folder to move the file to |

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

---

#### Share File

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

| Parameter | Description |
|---|---|
| File | File to share |
| Role | **Viewer** / **Commenter** / **Editor** |
| Type | **User** / **Group** / **Domain** / **Anyone** |
| Email address | For "User" and "Group" types. Supports **{{variables}}** |
| Send notification | Send an email notification to the recipient |

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

---

#### Update File

| Parameter | Description |
|---|---|
| File | File to update |
| New name | Supports **{{variables}}** | **Result variables:** **{{result.file_id}}**, **{{result.name}}**, **{{result.mimeType}}**.

---

#### Upload File

Uploads a file from the specified URL to Google Drive.

| Parameter | Description |
|---|---|
| File URL | Link to the file; supports **{{variables}}**. For Telegram files, use the `file_url` from the "Data Input" block variables |
| File Name | Automatically determined from the URL if not specified. Supports **{{variables}}** |
| Folder *(optional)* | Destination folder |
| Shared Drive ID *(optional)* | Upload to a Shared Drive. Supports **{{variables}}** |

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

| Parameter | Description |
|---|---|
| Search Query | Example: "name contains 'report'" or "mimeType = 'application/pdf'". Supports **{{variables}}** |
| Max Results *(optional)* | Up to 1000; default is 50 |
| Shared Drive ID *(optional)* | Limit search to a specific Shared Drive. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.files}}** | Array of files (id, name, mimeType, size, webViewLink) |
| **{{result.count}}** | Number of items found |

---

### Folder Actions

#### Create Folder

| Parameter | Description |
|---|---|
| Folder Name | Supports **{{variables}}** | | Parent folder *(optional)* | The folder inside which the new one is created |
| Shared drive ID *(optional)* | Create in a shared drive |

**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](https://dash.cloudflare.com/) → **R2 Object Storage** → your bucket → **Settings** tab.
2. Locate the **S3 API** field—it looks like "https://<account_id>.r2.cloudflarestorage.com/<bucket>". 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.

| Parameter | Description |
|---|---|
| File URL | Direct link to the file. Supports **{{variables}}**, including "{{result.file_url}}" from previous blocks |
| Object key | Path and filename within the bucket, e.g., "uploads/{{user.id}}/photo.jpg". Supports **{{variables}}** |
| MIME type *(optional)* | If not specified, it is determined automatically based on the file content |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.key}}** | Key of the saved object in the bucket |
| **{{result.public_url}}** | Direct download link (if "public_url" is set in the connection) |
| **{{result.size}}** | File size in bytes |

### Delete file

| Parameter | Description |
|---|---|
| Object key | Path to the file in the bucket. Supports **{{variables}}** |

The operation does not return a result.

### List files

Returns a list of objects in the bucket.

| Parameter | Description |
|---|---|
| Prefix (folder) | Filters files by the beginning of the key, e.g., "uploads/photos/". Optional |
| Max files | From 1 to 1000. Default is **100** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.files}}** | Array of objects: "key", "size", "last_modified", "public_url" |
| **{{result.count}}** | Number of files found |

### Copy file

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

| Parameter | Description |
|---|---|
| Source key | Key of the source file in the bucket |
| Destination key | Key of the new copy file |

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

### File information

Returns object metadata (without downloading the content).

| Parameter | Description |
|---|---|
| Object key | Path to the file in the bucket |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.exists}}** | "1" — file exists, "0" — not found |
| **{{result.size}}** | Size in bytes |
| **{{result.content_type}}** | File MIME type |
| **{{result.last_modified}}** | Last modification date |

---

#### Delete folder

| Parameter | Description |
|---|---|
| Folder | Folder to delete (deleted along with all its contents) |

Returns no variables.

---

#### Share folder

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

---

### Shared drive actions

#### Create shared drive

| Parameter | Description |
|---|---|
| Drive name | Supports **{{variables}}** |

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

---

#### Delete shared drive

| Parameter | Description |
|---|---|
| Shared drive ID | Supports **{{variables}}** |

Returns no variables.

---

#### Get shared drive

| Parameter | Description |
|---|---|
| Shared drive ID | Supports **{{variables}}** |

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

---

#### List Shared Drives

| Parameter | Description |
|---|---|
| Max results *(optional)* | Up to 100; default is 50 |

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

---

#### Update Shared Drive

| Parameter | Description |
|---|---|
| Shared drive ID | Supports **{{variables}}** |
| New name | Supports **{{variables}}** |

**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](https://console.cloud.google.com/apis/credentials) (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

| Parameter | Description |
|---|---|
| Calendar | Select from the list or specify the ID (**primary** — main calendar) |
| Event title | Title text; supports **{{variables}}** |
| All-day event | **Yes** — all-day event (date format **YYYY-MM-DD**); **No** — with time (RFC3339) |
| Start | Start date and time |
| End | End date and time |

**Additional parameters** ("Advanced" section):

| Parameter | Description |
|---|---|
| Description | Event description text |
| Location | Address or venue name |
| Participants | Comma-separated email addresses |
| Event color | One of the 11 Google Calendar colors |
| Visibility | Default / Public / Private / Confidential |
| Event status | Confirmed / Tentative / Cancelled |
| Guests can invite others | Yes / No |
| Guests can modify the event | Yes / No |
| Guests can see other participants | Yes / No |
| Send notifications | To all / External only / To no one |
| Use default reminders | Yes / No |
| Event ID | Custom identifier (auto-generated if not specified) |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.id}}** | ID of the created event |
| **{{result.summary}}** | Event title |
| **{{result.status}}** | Status (**confirmed**, **tentative**) |
| **{{result.htmlLink}}** | Link to the event in Google Calendar |
| **{{result.start}}** | Start time |
| **{{result.end}}** | End time |

---

### Delete event

| Parameter | Description |
|---|---|
| Calendar | Calendar ID |
| Event ID | Event identifier (**{{result.id}}** from the previous operation) |
| Send notifications | *(advanced)* All / External only / None |

Returns no variables.

---

### Get event

| Parameter | Description |
|---|---|
| Calendar | Calendar ID |
| Event ID | Event identifier |
| Time zone | *(advanced)* IANA time zone, e.g., **Europe/Moscow** |
| Max. attendees | *(advanced)* Limit on the number of attendees in the response |

**Result variables** (with the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.id}}** | Event ID |
| **{{result.summary}}** | Title |
| **{{result.status}}** | Status |
| **{{result.description}}** | Description |
| **{{result.location}}** | Location |
| **{{result.start}}** | Start |
| **{{result.end}}** | End |
| **{{result.htmlLink}}** | Link |
| **{{result.creator}}** | Creator's email |
| **{{result.organizer}}** | Organizer's email |

---

### Get events

| Parameter | Description |
|---|---|
| Calendar | Calendar ID |
| Range start | *(advanced)* **timeMin** — RFC3339 |
| Range end | *(advanced)* **timeMax** — RFC3339 |
| Text search | *(advanced)* Search by title and description |
| Max. results | *(advanced)* Default 250, maximum 2500 |
| Sorting | *(advanced)* By start time / By modification date |
| Expand recurring events | *(advanced)* Required for sorting by **startTime** |
| Show deleted events | *(advanced)* |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.events}}** | Array of events (each is an object with id, summary, start, end, etc.) |
| **{{result.count}}** | Number of events found |

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

| Parameter | Description |
|---|---|
| Calendar | Calendar ID |
| Range start | RFC3339 date-time for the start of the period to check |
| Range end | RFC3339 date-time for the end of the period to check |
| Time zone | *(advanced)* IANA timezone |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.is_available}}** | **true** if the period is free, **false** if there are busy slots |
| **{{result.busy_periods}}** | Array of busy intervals **[{ "start": "...", "end": "..." }]** |

---

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

| Parameter | Description |
|---|---|
| **Edit message** | Enable edit mode instead of sending |
| **Message ID** | ID of the message to edit. Specify a number or insert a variable, e.g., "{{message_id}}" | **Typical use case: pairing with an AI "preliminary message":**

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](https://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.

| Parameter | Description |
|---|---|
| Voice | Select a voice from your account list or specify a `voice_id` manually |
| Text | Text to be spoken; supports **{{variables}}** |

**Additional parameters:**

| Parameter | Description |
|---|---|
| Model | Multilingual v2 (recommended for Russian), Flash v2.5, Turbo v2.5, v3 |
| Audio format | MP3 128 kbps (recommended), MP3 64 kbps, PCM, μ-law |
| Stability (0–1) | Lower — more emotional and dynamic; higher — more monotonous but stable |
| Similarity boost (0–1) | How closely the AI ​​mimics the original voice |
| Style exaggeration (0–1) | Intensifies the speaking style; recommended to keep at **0** for natural sound |
| Speech rate | 1.0 — normal; lower — slower, higher — faster |
| Speaker boost | Makes the voice richer (requires slightly more resources) |
| Seed | Fixes the generation process for reproducible results |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.url}}** | Audio file URL — pass this to the "Audio" block |
| **{{result.character_count}}** | Number of characters used |
| **{{result.request_id}}** | Request ID |

> **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).

| Parameter | Description |
|---|---|
| Audio file_id or URL | Telegram file_id of the voice/audio message, or a direct URL; supports **{{variables}}** |
| Model | Scribe v2 (recommended), Scribe v1 |
| Language (ISO 639-1) | E.g., **ru**, **en**, **de**. Leave blank for auto-detection |

**Additional parameters:**

| Parameter | Description |
|---|---|
| Split by speaker | Diarization: labels utterances as "Speaker 1", "Speaker 2" |
| Clean filler words | Removes "um", "uh", "well", repetitions, and false starts |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.text}}** | Recognized text |
| **{{result.language_code}}** | Detected language |
| **{{result.transcription_id}}** | Transcription ID |

**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}}".
3. **Integration** block → OpenAI / ChatGPT → "{{result.text}}" → response "{{ai.text}}".
4. **Text** block → "{{ai.text}}".

> Receiving voice/audio files is currently supported on **Telegram** and **Web Widget**.

---

### Voice Conversion (Speech-to-Speech)

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

| Parameter | Description |
|---|---|
| Target voice | The voice used to replace the original |
| Audio file_id or URL | Telegram file_id of the voice/audio message, or a direct URL; supports **{{variables}}** |

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

| Parameter | Description |
|---|---|
| Sound description | Description text; supports **{{variables}}** |
| Duration (sec.) | Desired sound duration (optional) |

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

| Parameter | Description |
|---|---|
| Video file_id or URL | Telegram file_id of the video message, or a direct URL; supports **{{variables}}** |
| Music description | Optional text-based style direction; supports **{{variables}}** |

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

| Parameter | Description |
|---|---|
| Voice name | Name of the new voice in the ElevenLabs account; supports **{{variables}}** |
| Audio file_id or URL | Telegram file_id or a direct URL of the recording containing the target voice; supports **{{variables}}** |

**Additional parameters:** Voice description, Remove background noise.

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.voice_id}}** | Cloned voice ID — use this in the "Text-to-Speech" operation |
| **{{result.voice_name}}** | Voice name |

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

---

## Fish Audio

Fish Audio is an AI-powered voice platform and an alternative to ElevenLabs: text-to-speech in 83 languages, speech recognition, voice generation from a text description (Voice Design), and voice cloning.

### Connection

1. Sign up at [fish.audio](https://fish.audio).
2. Go to **API Keys** and create a new key.
3. Copy the generated key and paste it into the connection field.
4. Click "Check" — the system will verify API access.

---

### Text-to-Speech

Converts text into an audio file using the selected voice.

| Parameter | Description |
|---|---|
| Voice | Select one of your voice models from the list, or enter a public model ID manually |
| Text | Text to be spoken; supports **{{variables}}** |

**Additional parameters:**

| Parameter | Description |
|---|---|
| Model | S2.1-Pro (recommended), S2.1-Pro Free (for testing), S2-Pro, S1 (legacy, emotion tags) |
| Audio format | MP3, WAV, Opus, PCM |
| MP3 bitrate | 64 / 128 (recommended) / 192 kbps |
| Sample rate | Leave empty for the format's default |
| Latency mode | Normal (best quality), balanced, low (fastest) |
| Speech speed | 0.5–2.0, default 1.0 |
| Volume (dB) | Positive — louder, negative — quieter |
| Temperature (0–1) | Higher — more expressive and varied |
| Top P (0–1) | Nucleus sampling diversity |
| Chunk length (100–300) | Characters processed per audio segment |
| Normalize text | Normalizes numbers, dates, and abbreviations before synthesis |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.url}}** | Audio file URL — pass this to the "Voice"/"Audio" block |
| **{{result.character_count}}** | Number of characters used |
| **{{result.format}}** | Format of the saved audio file |

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

**Typical scenario — announcer bot:**
1. "Integration" block → Fish Audio → **Text-to-Speech** → select voice → text "{{news_text}}".
2. Next block **"Voice"** → specify "{{result.url}}" in the "file_id or URL" field.
3. The bot sends the synthesized news as a voice message.

---

### Speech-to-Text

Converts a voice message or audio file into text.

| Parameter | Description |
|---|---|
| Audio file_id or URL | Telegram file_id of the voice/audio message, or a direct URL; supports **{{variables}}** |
| Language (ISO 639-1) | E.g., **ru**, **en**, **zh**. Leave blank for auto-detection |

**Additional parameters:** Return timestamps — adds start/end times for each segment (slightly increases latency for audio shorter than 30 seconds).

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.text}}** | Recognized text |
| **{{result.duration}}** | Audio duration in seconds |
| **{{result.segments}}** | Array of timed segments (for those who enabled "Return timestamps") |

**Typical scenario — voice assistant:**
1. **"Data Input"** block → saves the voice message to the "voice_input" variable.
2. **"Integration"** block → **Speech-to-Text** → "file_id: {{voice_input}}" → "{{result.text}}".
3. **"Integration"** block → OpenAI / ChatGPT → "{{result.text}}" → response "{{ai.text}}".
4. **"Text"** block → "{{ai.text}}".

> Receiving voice/audio files is currently supported on **Telegram** and **Web Widget**.

---

### Voice Design

Creates a brand-new voice from a text description — no sample recording needed. Returns several candidates to choose from.

| Parameter | Description |
|---|---|
| Voice description | E.g. "A calm, friendly female voice, medium pitch"; supports **{{variables}}** |
| Preview text | Up to 150 characters — a phrase the generated voice will speak (optional) |
| Language | E.g. **ru**, **en** |
| Number of candidates | 1–4; each candidate is a separate audio file |

**Additional parameters:** Speech speed, Diffusion steps, Guidance scale, Instruction guidance scale, Seed.

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.url}}** | URL of the first generated candidate |
| **{{result.candidates}}** | Array of all candidates (id, index, url, duration_ms) |
| **{{result.count}}** | Number of generated candidates |

> **Important:** Audio links are available for **24 hours**, after which they are automatically deleted. To keep a voice you like permanently, use it as the sample for the "Create Voice Model" operation.

---

### Create Voice Model (cloning)

Creates a digital copy of a voice based on an audio recording. The created model is saved to your Fish Audio account, and its ID can be used as the "Voice" in the "Text-to-Speech" operation.

| Parameter | Description |
|---|---|
| Model title | E.g. "My Voice"; supports **{{variables}}** |
| Audio file_id or URL for cloning | Telegram file_id or a direct URL of the voice sample; supports **{{variables}}** |
| Visibility | **Private** (recommended), Unlisted (by link), Public |

**Additional parameters:** Description, Transcript (sample text — auto-transcribed if left empty), Tags, Enhance audio quality.

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.model_id}}** | ID of the created model — use as the "Voice" in the "Text-to-Speech" operation |
| **{{result.title}}** | Model title |
| **{{result.state}}** | Training state |

**Typical scenario — a bot's personal voice:**
1. **"Data Input"** block → user sends a voice message → "voice_sample".
2. **"Integration"** block → **Create Voice Model** → "title: My Voice", "file_id: {{voice_sample}}" → "{{result.model_id}}".
3. Save "{{result.model_id}}" to the database.
4. In subsequent scenarios: **"Integration"** block → **Text-to-Speech** → "Enter ID" → "{{saved_model_id}}".

> **Public** visibility requires a cover image and lists the model in the shared Fish Audio catalog — use **Private** for personal voices.

---

### List / Get / Update / Delete Voice Models

Utility operations for managing your voice models without leaving the constructor.

| Operation | Purpose |
|---|---|
| **List Voice Models** | Returns an array of your models — useful for listing them as buttons (**{{item.title}}**) via dynamic buttons so the user can pick a voice |
| **Get Voice Model** | Info about a single model by its ID |
| **Update Voice Model** | Changes the title / description / visibility / tags of an existing model |
| **Delete Voice Model** | Permanently deletes a model |

**Result variables for "List Voice Models":** **{{result.items}}** (array: id, title, description, languages, tags, state, visibility), **{{result.total}}**, **{{result.count}}**.

> The "Test" button never actually runs **Update** or **Delete** — it only checks the connection, so you can't accidentally modify or erase data while configuring the scenario.

---

## 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](https://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:

| Field | Value |
|---|---|
| **Project URL** | "https://xxxx.supabase.co" |
| **Service Role Key** | "eyJ..." (secret key) |

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.

| Parameter | Description |
|---|---|
| Table | Database table name; supports **{{variables}}** |
| Data | List of "Column → Value" pairs; supports **{{variables}}** |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.id}}** | ID of the created record (and other fields returned by the database) |
| **{{result.ColumnName}}** | Value of any returned column |

---

### Delete Record

Deletes rows that match the specified conditions.

| Parameter | Description |
|---|---|
| Table | Table name; supports **{{variables}}** |
| Select Conditions | Row selection conditions (field, operator, value); supports **{{variables}}** |
| Must Match *(optional)* | **All** — all conditions (AND); **Any** — at least one (OR) |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result}}** | Array of deleted records |
| **{{result.count}}** | Number of deleted records |

---

### Get Record

Retrieves the first row that meets the specified conditions.

| Parameter | Description |
|---|---|
| Table | Table name; supports **{{variables}}** |
| Select Conditions | Search conditions; if no conditions are provided, the first row is returned |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.id}}** | ID of the found record |
| **{{result.ColumnName}}** | Value of any column in the found row |

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

---

### Get List of Records

Returns an array of rows matching the filters.

| Parameter | Description |
|---|---|
| Table | Table name; supports **{{variables}}** |
| Return All | If enabled, returns all rows (ignores Limit) |
| Limit *(optional)* | Maximum number of records. Default is **50**; supports **{{variables}}** |
| Filters | Selection conditions (field, operator, value); supports **{{variables}}** |
| Must Match *(optional)* | **All** — AND; **Any** — OR |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result}}** | Array of records |
| **{{result.count}}** | Number of records |
| **{{result.0.ColumnName}}** | Column value in the first record |

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.

| Parameter | Description |
|---|---|
| Table | Table name; supports **{{variables}}** |
| Select Conditions | Conditions for selecting rows to update; supports **{{variables}}** |
| Must Match | **All** — AND; **Any** — OR |
| Fields to Send | List of "Column → New Value" pairs; supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result}}** | Array of updated records |
| **{{result.count}}** | Number of updated records |

---

### Condition operators

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

| Operator | Description |
|---|---|
| "=" | Equal to |
| "!=" | Not equal to |
| "<" | Less than |
| "<=" | Less than or equal to |
| ">" | Greater than |
| ">=" | Greater than or equal to |
| "like" | Pattern match ("%text%") |
| "ilike" | Same as above, case-insensitive |

---

### 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](https://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:**
| Parameter | Description |
|---|---|
| Model | Model ID (default: "grok-3") |
| System Prompt | Context/instructions for the model |
| User Message | Request to the model |
| Temperature | Response randomness (0–2) |
| Max Tokens | Response length limit |
| Chat History | Variable containing history to maintain context |
| JSON Mode | Force response in JSON format | **Result variables:**
- "{prefix}.text" — model response text
- "{prefix}.model" — model used
- "{prefix}.tokens_used" — number of tokens consumed
- "{prefix}.<key>" — 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:**
| Parameter | Description |
|---|---|
| Model | ID of a Vision-capable model (e.g., "grok-4.20-reasoning") |
| Image URL or file_id | Telegram "file_id" or direct link |
| Question | What to find out about the image |
| Detail level | "auto", "low", or "high" |
| Max tokens | Response length limit |

**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:**
| Parameter | Description |
|---|---|
| Prompt | Image description |
| Aspect ratio | "auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "2:1", "1:2" |
| Resolution | "1k" (standard) or "2k" (high) |
| Count | Number of images (1–10) |

**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:**
| Parameter | Description |
|---|---|
| Message ID | Telegram "message_id" to react to |
| Allowed reactions | List of emojis for the AI ​​to choose from |
| User message | Text to analyze |
| Model | Model ID (default: "grok-3-mini") |
| System prompt | Additional instructions for selecting the reaction | **Result variables:**
- "{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:**
| Parameter | Description |
|---|---|
| Prompt | Video description |
| Duration | Duration in seconds (1–15) |
| Aspect ratio | "16:9", "9:16", "1:1" |
| Resolution | "480p" or "720p" |

**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:**
| Parameter | Description |
|---|---|
| Audio File ID or URL | Telegram "file_id" of the audio or voice message, or a direct URL |
| Language | ISO language code (optional — for improved accuracy) |
| Normalization | Convert numbers and abbreviations into text format |

**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:**
| Parameter | Description |
|---|---|
| Text | Text to be spoken |
| Voice | One of: "eve" (energetic), "ara" (warm), "rex" (professional), "sal" (smooth), "leo" (authoritative) |
| Language | ISO language code (or "auto" for auto-detection) |
| Format | Audio format: "mp3", "wav", "pcm", "mulaw" |

**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

| Model | Purpose |
|---|---|
| "grok-3" | Flagship language model — text, chat |
| "grok-3-mini" | Lightweight and fast — short tasks, reactions |
| "grok-4.20-reasoning" | Vision + reasoning — image analysis |
| "grok-imagine-image" | Image generation |
| "grok-imagine-video" | Video generation |

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

---

## Twilio

Send SMS messages and check delivery status via Twilio.

### Connection

Paste your Twilio credentials as JSON:

```json
{
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auth_token": "your_auth_token"
}
```

Find your Account SID and Auth Token in the [Twilio Console](https://console.twilio.com/).

---

### Send SMS

| Parameter | Description |
|---|---|
| Recipient number | Phone number in E.164 format (e.g. +12125551234). Supports **{{variables}}** |
| Sender number | Your Twilio phone number (e.g. +15017122661). Supports **{{variables}}** |
| Message text | Text up to 1600 characters. Supports **{{variables}}** |

**Result variables** (using the **result** prefix):

| Variable | Value |
|---|---|
| **{{result.sid}}** | SID of the sent message |
| **{{result.status}}** | Status (queued, sent, delivered, failed, etc.) |
| **{{result.body}}** | Message text |
| **{{result.to}}** / **{{result.from}}** | Recipient and sender numbers |
| **{{result.date_created}}** | Creation date |
| **{{result.error_code}}** / **{{result.error_message}}** | Delivery error code and text (empty if no error) |
| **{{result.num_segments}}** | Number of SMS segments |
| **{{result.price}}** / **{{result.price_unit}}** | Sending cost and currency |

---

### Get message status

| Parameter | Description |
|---|---|
| Message SID | SID of the message to fetch (e.g. **{{result.sid}}** from "Send SMS"). Supports **{{variables}}** |

**Result variables** — the same as "Send SMS", with the current delivery status (**{{result.status}}**, **{{result.error_code}}**, etc.).

> SMS delivery is not instant: right after sending, the status is usually **queued**. Fetch the status later to see **delivered** or an error.

---

## Airtable

Read and manage records, tables, and bases in Airtable.

### Connection

Create a **Personal Access Token** at [airtable.com/create/tokens](https://airtable.com/create/tokens) and paste it into the connection field. Required scopes: `schema.bases:read`, `data.records:read`, `data.records:write`.

Common operation parameters:

| Parameter | Description |
|---|---|
| Base ID | Airtable base identifier (**appXXXXXXXXXXXXXX**). Supports **{{variables}}** |
| Table | Table ID or name (e.g. **tblXXXXXX** or **Contacts**). Supports **{{variables}}** |
| Automatic type conversion | If enabled, Airtable tries to convert string values to the appropriate field type |

---

### Get many bases

No parameters — returns the bases accessible to the token.

| Variable | Value |
|---|---|
| **{{result}}** | Array of bases |
| **{{result.count}}** | Number of bases |
| **{{result.N.id}}** / **{{result.N.name}}** | ID and name of the Nth base (N starts at 0) |

---

### Get base schema

| Parameter | Description |
|---|---|
| Base ID | The base whose schema to fetch |

**Result:** **{{result}}** — array of the base's tables; **{{result.count}}**, **{{result.N.id}}**, **{{result.N.name}}**, **{{result.N.fields}}** (JSON description of the Nth table's fields).

---

### Create a record

| Parameter | Description |
|---|---|
| Base ID, Table | See common parameters |
| Fields | List of "Field name → Value" pairs; supports **{{variables}}** |
| Automatic type conversion | Optional |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.id}}** | ID of the created record (**recXXXXXXXXXXXXXX**) |
| **{{result.createdTime}}** | Created time (ISO 8601) |
| **{{result.fields.FieldName}}** | Value of each record field |

---

### Create or update a record

Searches for a record by matching values in the specified fields. Updates it if found, otherwise creates a new one.

| Parameter | Description |
|---|---|
| Base ID, Table, Fields | Same as "Create a record" |
| Merge fields | Comma-separated field names used to match existing records (e.g. **Email,Name**). Supports **{{variables}}** |

**Result variables:** the same as "Create a record", plus:

| Variable | Value |
|---|---|
| **{{result.createdCount}}** | Number of created records (0 or 1) |
| **{{result.updatedCount}}** | Number of updated records (0 or 1) |

---

### Delete a record

| Parameter | Description |
|---|---|
| Base ID, Table | See common parameters |
| Record ID | Airtable record identifier (**recXXXXXXXXXXXXXX**). Supports **{{variables}}** |

**Result variables:** **{{result.deleted}}** — **true**/**false** · **{{result.id}}** — ID of the deleted record.

---

### Get a record

| Parameter | Description |
|---|---|
| Base ID, Table | See common parameters |
| Record ID | Record identifier. Supports **{{variables}}** |

**Result variables:** **{{result.id}}**, **{{result.createdTime}}**, **{{result.fields.FieldName}}**.

---

### Search records

| Parameter | Description |
|---|---|
| Base ID, Table | See common parameters |
| Filter formula | Airtable formula to filter records (e.g. **{Status}='Active'**). Supports **{{variables}}** |
| View *(advanced)* | View ID or name to scope results |
| Max records *(advanced)* | Default **100**. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result}}** | Array of found records |
| **{{result.count}}** | Number of records |
| **{{result.N.id}}** / **{{result.N.createdTime}}** | ID and created time of the Nth record |
| **{{result.N.fields.FieldName}}** | Field value of the Nth record |

---

### Update record

| Parameter | Description |
|---|---|
| Base ID, Table | See common parameters |
| Record ID | Record to update. Supports **{{variables}}** |
| Fields | "Field name → New value" pairs; only the specified fields are updated |

**Result variables:** **{{result.id}}**, **{{result.createdTime}}**, **{{result.fields.FieldName}}**.

---

## HubSpot

Manage contacts, deals, and companies in HubSpot CRM.

### Connection

Get your Private App Access Token from HubSpot: **Settings → Integrations → Private Apps → Create a private app**. The token starts with **pat-** — paste it into the connection field.

---

### Create or Update Contact

Searches for a contact by email or phone. Updates it if found, otherwise creates a new one.

| Parameter | Description |
|---|---|
| Search by | **Email** or **Phone** |
| Email | Email to search or assign (e.g. john@acme.com). Supports **{{variables}}** |
| Phone | Phone to search or assign. Supports **{{variables}}** |
| First name / Last name | Supports **{{variables}}** |
| Lifecycle stage | Contact lifecyclestage |
| Additional properties | HubSpot property name → value. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.action}}** | **created** or **updated** |
| **{{result.id}}** | Contact ID |
| **{{result.email}}** / **{{result.phone}}** | Email and phone |
| **{{result.firstname}}** / **{{result.lastname}}** | First and last name |
| **{{result.lifecyclestage}}** | Lifecycle stage |

---

### Get Contact

| Parameter | Description |
|---|---|
| Search by | **Email**, **Phone**, or **ID** |
| Email / Phone / Contact ID | Value to search by. Supports **{{variables}}** |
| Properties to return *(advanced)* | Comma-separated property names (e.g. **firstname,email,phone**) |

**Result variables:** the same as "Create or Update Contact" (without **action**). If the contact is not found, the variables are empty.

---

### Create Deal

| Parameter | Description |
|---|---|
| Deal name | Supports **{{variables}}** |
| Pipeline | Pipeline ID (e.g. **default**). Find in HubSpot Settings → Deals → Pipelines |
| Deal stage | Stage ID (e.g. **appointmentscheduled**) |
| Amount | Deal value (number). Supports **{{variables}}** |
| Close date | Expected close date (YYYY-MM-DD) |
| Associate with contact *(advanced)* | Contact ID to associate the deal with |
| Associate with company *(advanced)* | Company ID to associate the deal with |
| Additional properties | Property name → value |

**Result variables:** **{{result.id}}**, **{{result.dealname}}**, **{{result.pipeline}}**, **{{result.dealstage}}**, **{{result.amount}}**.

---

### Update Deal Stage

| Parameter | Description |
|---|---|
| Deal ID | ID of the deal to update. Supports **{{variables}}** |
| New stage | Stage ID (e.g. **closedwon**) |
| Pipeline *(advanced)* | Pipeline ID if the deal is being moved |
| Additional updates | Extra fields to update (property name → value) |

**Result variables:** **{{result.id}}**, **{{result.dealstage}}**.

---

### Find or Create Company

| Parameter | Description |
|---|---|
| Search by | **Domain** or **Name** |
| Domain | Company website domain (e.g. acme.com). Supports **{{variables}}** |
| Company name | Name to search or set |
| Create if not found | If disabled and the company is not found — returns **{{result.action}} = not_found** |
| Additional properties | Property name → value |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.action}}** | **found**, **created**, or **not_found** |
| **{{result.id}}** | Company ID (empty when not_found) |
| **{{result.name}}** / **{{result.domain}}** | Name and domain |

---

### Associate Contact with Company

| Parameter | Description |
|---|---|
| Contact ID | Supports **{{variables}}** |
| Company ID | Supports **{{variables}}** |

**Result variable:** **{{result.success}}** = **true**.

---

### Create Note

| Parameter | Description |
|---|---|
| Note body | Supports **{{variables}}** |
| Contact ID / Deal ID / Company ID *(advanced)* | Objects to associate the note with |

**Result variable:** **{{result.id}}** — ID of the created note.

---

### Create Call

| Parameter | Description |
|---|---|
| Call title | Title for the call log |
| Call notes | Notes about the call |
| Call time | ISO 8601 datetime (e.g. 2024-01-15T10:00:00Z) |
| Duration (ms) | E.g. 60000 = 1 min |
| Outcome | Call status |
| Contact ID / Deal ID *(advanced)* | Objects to associate with |

**Result variable:** **{{result.id}}** — ID of the call log.

---

### Create Meeting

| Parameter | Description |
|---|---|
| Meeting title | Title of the meeting |
| Meeting notes | Meeting notes / description |
| Start time / End time | ISO 8601 (e.g. 2024-01-15T10:00:00Z) |
| Contact ID / Deal ID *(advanced)* | Objects to associate with |

**Result variable:** **{{result.id}}** — meeting ID.

---

### Search CRM Objects

| Parameter | Description |
|---|---|
| Object type | contacts, companies, deals, etc. |
| Search filters | Conditions (property, operator, value); same operators as Supabase: **=**, **!=**, **<**, **<=**, **>**, **>=**, **like**, **ilike** |
| Filter logic | **AND** — all conditions; **OR** — at least one |
| Properties to return *(advanced)* | Comma-separated property names (e.g. **firstname,email**) |
| Sort by *(advanced)* | Property name to sort results by (e.g. **createdate**) |
| Max results *(advanced)* | Default 10, max 200 |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.count}}** | Number of returned objects |
| **{{result.total}}** | Total number of matches in HubSpot |
| **{{result.N.id}}** | ID of the Nth object (N starts at 0) |
| **{{result.N.property}}** | Value of each requested property |

---

## Salesforce

Manage leads, contacts, accounts, opportunities and tasks in Salesforce CRM.

### Connection

Paste Salesforce Connected App credentials as JSON:

```json
{
  "login_url": "https://login.salesforce.com",
  "client_id": "your_consumer_key",
  "client_secret": "your_consumer_secret",
  "username": "api@yourcompany.com",
  "password": "PasswordSecurityToken"
}
```

Create your Connected App in **Setup → App Manager** (enable OAuth and the Username-Password flow).

> **Note:** «password» = your password + security token concatenated (no separator). Use **https://test.salesforce.com** as login_url for sandbox.

---

### Create or Update Lead

Searches for a lead by email, phone, or ID. Updates it if found, otherwise creates a new one.

| Parameter | Description |
|---|---|
| Search by | **Email**, **Phone**, or **By ID** |
| Email / Phone | Used for search and to set the field. Supports **{{variables}}** |
| Lead ID | Salesforce Lead ID (starts with **00Q**) |
| First name / Last name / Company | Supports **{{variables}}** |
| Status | Lead status |
| Lead source | LeadSource |
| Custom fields | Field name → Value. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.id}}** | Lead ID |
| **{{result.action}}** | **created** or **updated** |
| **{{result.email}}** / **{{result.firstname}}** / **{{result.lastname}}** / **{{result.company}}** | Lead data |

---

### Convert Lead

Converts a lead into a contact + account (and optionally an opportunity).

| Parameter | Description |
|---|---|
| Lead ID | Salesforce Lead ID (starts with **00Q**). Supports **{{variables}}** |
| Converted status | Lead status after conversion (default **Closed - Converted**) |
| Opportunity name *(advanced)* | Name for the new Opportunity |
| Do not create Opportunity | Convert without creating an opportunity |
| Send notification email | Notify the record owner |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.contact_id}}** | ID of the created contact |
| **{{result.account_id}}** | ID of the created account |
| **{{result.opportunity_id}}** | ID of the created opportunity (empty if not created) |
| **{{result.success}}** | **true** / **false** |

---

### Create or Update Contact

| Parameter | Description |
|---|---|
| Search by | **Email**, **Phone**, or **By ID** |
| Email / Phone / Contact ID | Contact ID starts with **003**. Supports **{{variables}}** |
| First name / Last name | Supports **{{variables}}** |
| Account ID | Link to an account (starts with **001**) |
| Custom fields | Field name → Value |

**Result variables:** **{{result.id}}**, **{{result.action}}** (created/updated), **{{result.email}}**, **{{result.firstname}}**, **{{result.lastname}}**.

---

### Create Opportunity

| Parameter | Description |
|---|---|
| Opportunity name | Supports **{{variables}}** |
| Account ID | Salesforce Account ID (starts with **001**) |
| Stage | Opportunity stage (StageName) |
| Close date | Date in YYYY-MM-DD format. Supports **{{variables}}** |
| Amount | Numeric amount (e.g. 5000) |
| Description | Supports **{{variables}}** |
| Custom fields | Field name → Value |

**Result variables:** **{{result.id}}**, **{{result.name}}**, **{{result.stagename}}**, **{{result.closedate}}**, **{{result.amount}}**.

---

### Update Opportunity Stage

| Parameter | Description |
|---|---|
| Opportunity ID | Salesforce Opportunity ID (starts with **006**). Supports **{{variables}}** |
| Stage | New stage (StageName) |
| Close date *(advanced)* | YYYY-MM-DD |
| Additional updates | Field name → Value |

**Result variables:** **{{result.id}}**, **{{result.stagename}}**.

---

### Create or Update Account

| Parameter | Description |
|---|---|
| Search by | **By name** or **By website** |
| Name | Company name. Supports **{{variables}}** |
| Website | Website domain (e.g. acme.com). Used for search |
| Phone | Supports **{{variables}}** |
| Billing city / Billing country | Address fields |
| Custom fields | Field name → Value |

**Result variables:** **{{result.id}}**, **{{result.action}}** (created/updated), **{{result.name}}**.

---

### Create Task / Log Activity

| Parameter | Description |
|---|---|
| Subject | Task title. Supports **{{variables}}** |
| Type | **Task**, **Call**, or **Email** (Call/Email are logged as activities) |
| Who ID | Lead or Contact ID to link this task to (WhoId) |
| What ID | Account or Opportunity ID to link this task to (WhatId) |
| Description | Supports **{{variables}}** |
| Activity date | Task due date in YYYY-MM-DD format |
| Status / Priority | Standard Salesforce task fields |

**Result variable:** **{{result.id}}** — ID of the created task.

---

### Search Records (SOQL)

| Parameter | Description |
|---|---|
| SOQL Query | Full SOQL query, e.g. **SELECT Id, Name FROM Lead WHERE Email = '{{email}}' LIMIT 10**. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.count}}** | Number of returned records |
| **{{result.total}}** | Total number of matches (totalSize) |
| **{{result.N.Field}}** | Value of each selected field of the Nth record (N starts at 0), e.g. **{{result.0.Name}}** |

---

## Mailchimp

Manage email subscribers, tags and automation events in Mailchimp.

### Connection

Paste your Mailchimp API key. Find it at **Account → Extras → API keys**. The key ends with your data center code, e.g. **-us21**.

---

### Add or Update Member

Adds an email to an audience or updates an existing subscriber (matched by email).

| Parameter | Description |
|---|---|
| Audience ID | Audience List ID. Find it in **Audience → Settings → Audience name and defaults**. Supports **{{variables}}** |
| Email | Subscriber email address. Supports **{{variables}}** |
| Status | **Subscribed** adds immediately. **Pending** sends a double opt-in confirmation email (recommended for US/EU compliance) |
| Merge fields | Merge tag → Value. Standard tags: **FNAME**, **LNAME**, **PHONE**, **BIRTHDAY**. Supports **{{variables}}** |

**Result variables:**

| Variable | Value |
|---|---|
| **{{result.id}}** | Subscriber ID (subscriber hash) |
| **{{result.email_address}}** | Subscriber email |
| **{{result.status}}** | Final status (subscribed, pending, etc.) |
| **{{result.web_id}}** | ID for the Mailchimp web interface |

---

### Add or Remove Tags

| Parameter | Description |
|---|---|
| Audience ID | Audience List ID |
| Email | Subscriber email. Supports **{{variables}}** |
| Tags to add | Comma-separated tag names (e.g. **VIP, Newsletter**). Tags are created automatically. Supports **{{variables}}** |
| Tags to remove | Comma-separated tag names. Supports **{{variables}}** |

**Result variable:** **{{result.email_address}}**.

---

### Create Member Event

Sends a custom event — it can trigger **Customer Journey** automations.

| Parameter | Description |
|---|---|
| Audience ID | Audience List ID |
| Email | Subscriber email. Supports **{{variables}}** |
| Event name | Will be lowercased and limited to 30 chars. Supports **{{variables}}** |
| Event properties | Key → Value pairs passed as event properties. Supports **{{variables}}** |

**Result variables:** **{{result.email_address}}** · **{{result.event_name}}** — normalized event name.
