### Curl Example: Get Own Credential Metadata

Source: https://wiki.albato.com/en/articles/9264449-method-for-getting-metadata-of-a-connection-to-your-own-system

Example of making a POST request using curl to retrieve connection metadata from the Albato partner API. This command includes necessary headers for content type, acceptance, and basic authorization.

```bash
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --request POST "https://api.albato.com/wl/partner-name/get-own-credential-metadata"
```

--------------------------------

### API Documentation: Get User Profile

Source: https://wiki.albato.com/en/articles/9264133-method-for-getting-a-user-profile

Comprehensive documentation for the `get-user-profile` API endpoint. It outlines the HTTP method, URL, required authorization (partner's master account token), request parameters (user ID), and all possible response parameters with their types and descriptions. An example response body is also provided.

```APIDOC
Endpoint: POST https://api.albato.com/wl/partner-name/get-user-profile
Authorization: This method should be called with the partner's master account token.

Request Parameters:
  - id (alphanumeric string): An alphanumeric user ID that the partner passes when creating a new user.

Response Parameters:
  - success (boolean): Request success indicator. Available values: true or false.
  - data.id (integer): An existing user's ID (in Albato).
  - data.email (string): An existing user's email.
  - data.language (string): An existing user's interface language.
  - data.timezoneOffset (integer): An existing user's time zone offset.
  - data.planId (integer, optional): An existing user's plan ID; only returns a value if user billing plans are set by the partner.
  - data.trxLimit (integer, optional): User transaction limit left; only returns a value if user billing plans are set by the partner.

Response Example:
{
    "success": true,
    "data": {
        "id": 1357,
        "email": "test@example.com",
        "language": "pt",
        "timezoneOffset": -180
    }
}
```

--------------------------------

### Curl Example: Get User Profile API Request

Source: https://wiki.albato.com/en/articles/9264133-method-for-getting-a-user-profile

This code snippet provides a practical example of how to make a POST request to the `get-user-profile` API endpoint using the `curl` command-line tool. It demonstrates setting necessary headers (Content-Type, Accept, Authorization) and passing the user ID in the JSON request body.

```bash
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --request POST --data '{"id":"test"}' "https://api.albato.com/wl/partner-name/get-user-profile"
```

--------------------------------

### JSON Response Example for Add User Plan Transactions

Source: https://wiki.albato.com/en/articles/9264188-method-for-adding-extra-transactions-to-a-user-billing-plan

An example of the JSON response received after successfully adding transactions to a user's billing plan via the API. It indicates the success status of the request.

```json
{
    "success": true,
    "data": []
}
```

--------------------------------

### Albato Authorization Templates Reference

Source: https://wiki.albato.com/en/articles/9887964-introduction-to-the-authorization-section

This section provides a comprehensive reference for the five authorization templates supported by Albato, detailing their setup, field generation, and the mechanism for passing authentication data in API requests.

```APIDOC
Albato Authorization Templates:

1. oAuth 2.0
   - Description: A distinct authorization type with its own additional settings on step 1. It automatically creates two fields: 'Access token' and 'Refresh token'. It also generates requests for receiving and updating these tokens.

2. Basic
   - Description: Standard Basic authorization. It creates 'Login' and 'Password' fields. No additional requests are generated by the template.
   - Usage: On the 4th step, the rule for base64 string (login:password) is automatically filled. The authorization header will contain the result of this encoding:
     Authorization: Basic {{base64string}}

3. API token
   - Description: Authorization using a static API token. It creates a single 'API key' field. No additional requests are generated.
   - Usage: On step 4, the API key is passed in the headers as:
     Authorization: Bearer {{apiKey}}

4. Session auth
   - Description: Similar to the API token template, but includes an additional, uneditable 'access_token' field. This template provides a request that allows for exchanging an initial set of data (e.g., Login and password, or a static API key from the interface) for a final API access token. The response containing the access token is saved to the non-editable fields and then used in the request sending template on step 4.

5. Custom
   - Description: An empty template that does not pre-create any fields or requests. It is intended for highly custom authorization scenarios where defining the authorization flow from scratch is more efficient due to unique field requirements or complex logic.
```

--------------------------------

### Curl Request Example for Adding User Plan Transactions

Source: https://wiki.albato.com/en/articles/9264188-method-for-adding-extra-transactions-to-a-user-billing-plan

An example of how to make a POST request using curl to the 'add-user-plan-transactions' API endpoint. This demonstrates the required headers and data payload for adding transactions to a user's billing plan.

```bash
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --data '{"id":"test", "count": 2000}' "https://api.albato.com/wl/partner-name/add-user-plan-transactions"
```

--------------------------------

### Configure HTTP Request Templates and Authorization in Albato

Source: https://wiki.albato.com/en/articles/9887999-authorization-workflow-settings

This section describes the setup of a 'template' for HTTP requests in Albato, which dictates the behavior of all future API calls associated with a specific authorization. It covers how dynamic authorization variables are utilized and how different parts of an HTTP request (GET parameters, headers, and body parameters) are configured.

```APIDOC
HTTP Request Template Configuration:

Authorization Parameters:
  - accessToken:
      Description: Dynamic variable available when Authorization method is oAuth or 'With API key'.
      Value: The access token saved during the initial connection creation and data exchange for the token.
  - Login and password (base64):
      Description: Dynamic variable available when Authorization type is 'with login and password'.
      Value: The concatenated login and password (login:password) encoded in base64 format.

Available HTTP Request Fields:
  - Get parameters:
      Description: Manually entered key-value pairs that are substituted and transferred as URL query parameters with each HTTP request.
      Usage: Define parameters that will be appended to the request URL (e.g., `?param1=value1&param2=value2`).
  - Headers:
      Description: Fields for defining custom HTTP headers. Specify a 'key' (header name) and a 'value' (header value).
      Usage: Common headers include `Content-Type`, `Authorization`, `Accept`.
      Example:
        Key: Content-Type
        Value: application/json
  - Parameters (Request Body):
      Description: Fields for defining key-value pairs that will be transferred in the HTTP request body.
      Usage: Typically used for sending data with POST, PUT, or PATCH requests.
      Example:
        Key: name
        Value: John Doe
```

--------------------------------

### Albato Partner API: Add User Method

Source: https://wiki.albato.com/en/articles/9263916-method-for-adding-a-user

Documents the `POST /wl/partner-name/add-user` endpoint for registering new users in Albato via a partner's master account. It details the required request parameters, expected response parameters, and authorization requirements, along with request and response examples.

```APIDOC
POST https://api.albato.com/wl/partner-name/add-user

Authorization: This method requires the partner's master account token.

Request Parameters:
- id (string, alphanumeric): An alphanumeric user ID that the partner passes when creating a new user. The ID must be unique for each partner's user. (Required)
- language (string): User interface language. Available values: "en", "pt", "es" (English, Portuguese, and Spanish). The default language value can be set in the partner account (default value = en). (Optional)
- timezoneOffset (integer): The user's timezone defined in minutes relative to UTC. The default time zone can be set in the partner account. (Optional)

Response Parameters:
- success (boolean): Request success indicator. Available values: true or false.
- data.id (integer): The created user's ID (in Albato).
- data.email (string): The created user's email.
- data.language (string): The created user's interface language.
- data.timezoneOffset (integer): The created user's time zone.
- data.permanentToken (string): A permanent API token for the created user; it only returns a value if permanent tokens are enabled in the partner account settings.
- data.sessionToken (string): A temporary API token for the created user; it only returns a value if temporary tokens are enabled in the partner account settings.
- data.sessionTokenValidUntil (integer, unix timestamp): The API token expiration period for the created user; it only returns a value if temporary tokens are enabled in the partner account settings.
- data.planId (integer): The created user's plan ID; it only returns a value if there are user billing plans set by the partner.
- data.trxLimit (integer): The created user's transaction limit; it only returns a value if there are user billing plans set by the partner.

Request Example (curl):
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --request POST --data '{"id":"test", "timezoneOffset": -180}' "https://api.albato.com/wl/partner-name/add-user"

Response Example:
{
    "success": true,
    "data": {
        "id": 1357,
        "email": "test@example.com",
        "permanentToken": "IhIHggKkgBP-qtiDXLAMxKsSOO6A4Mu_L",
        "sessionToken": "eyJ0eXAiOiJKV.eyJpZGVudGl0eSI6OTczMzAsInRydWVJZGVudGl0eS..._GT8jc8Xby-3sidRPk",
        "sessionTokenValidUntil": 1654744263
    }
}
```

--------------------------------

### HTTP Request Concepts and Data Structures

Source: https://wiki.albato.com/en/articles/9024290-how-to-work-with-http-requests

This documentation outlines the core components of an HTTP request, including the URL, request headers, and the structure of the request body. It also differentiates between common HTTP methods like GET and POST, explaining how data is transmitted for each.

```APIDOC
HTTP Request Concepts:

URL:
  Description: The address of the function or resource that needs to be executed or accessed.
  Usage:
    - Specifies the target endpoint for the request.
  Examples:
    - http://example.com/nofollow/create/contact
    - http://example.com/nofollow/update/order

Request Headers:
  Description: Distinct markers for a request, enabling the receiving server to process it correctly.
  Purpose:
    - Provide metadata about the request or the client.
    - Contain authorization information (e.g., login, password).
    - Specify content type, encoding, etc.
  Examples:
    - Content-Type: application/json
    - Authorization: Bearer <token>

Request Body:
  Description: Contains information about the event itself, including specific fields and their corresponding values.
  Format: Always presented as key-value pairs.
  Data Structures:
    - Simple Object:
      Syntax: { "key": "value", "another_key": "another_value" }
      Access: Keys are accessed directly by their names.
      Example:
        {
          "name": "John Doe",
          "email": "john.doe@example.com"
        }
    - Nested Object:
      Syntax: { "parent_key": { "child_key": "value" } }
      Access: Keys are accessed using dot notation (e.g., 'parent_key.child_key').
      Example:
        {
          "user": {
            "id": 123,
            "name": "Jane Doe"
          },
          "action": "update_profile"
        }
    - Nested Array (containing objects or primitives):
      Syntax: { "array_key": [ element1, element2, ... ] }
      Access: Elements are accessed using dot notation with zero-based serial numbers (e.g., 'array_key.0', 'array_key.1').
      Example:
        {
          "order_id": "ORD123",
          "items": [
            {
              "product_id": 101,
              "quantity": 2
            },
            {
              "product_id": 102,
              "quantity": 1
            }
          ]
        }

Request Methods:
  Description: Defines the type of operation to be performed on the resource identified by the URL.
  Common Methods:
    - GET:
      Purpose: Retrieve data from the server.
      Characteristic: All information (parameters) is passed in the URL (query string).
      Analogy: Like a postcard, where all information is written on the outside next to the address.
    - POST:
      Purpose: Submit data to be processed to a specified resource.
      Characteristic: Information is passed in the request body.
      Analogy: Like a regular letter, where all information is contained inside.

Content-Type Header:
  Description: Indicates the media type of the resource in the request body.
  Influence: Crucial for the server to correctly parse and interpret the data sent in the request body.
  Examples:
    - application/json
    - application/x-www-form-urlencoded
    - text/plain
```

--------------------------------

### Albato Partner API: Manage Own System Connection

Source: https://wiki.albato.com/en/articles/9264461-method-for-getting-a-connection-to-your-own-system

This API method allows partners to request, validate, or update connection credentials to their own system within the Albato platform. It supports receiving webhooks and requires authorization with a user token.

```APIDOC
Endpoint: POST https://api.albato.com/wl/partner-name/get-own-credential
  Description: Request a connection to your system, validate connection credentials, or receive a webhook.
  Authorization: This method should be called with the user token (Bearer Token).
  
  Response Parameters:
    success: boolean
      Description: Request success indicator. Available values: true or false.
    data: object
      Description: Parameters of the created/updated connection in a key-value format. Keys depend on the particular connection and match those transferred in this method. Sensitive data (e.g., passwords, access tokens) cannot be returned in a readable format and will be partially masked for security.

Endpoint: POST https://api.albato.com/wl/partner-name/upsert-own-credential
  Description: Used for creating or updating a connection to your own system (inferred from cURL example).
  Authorization: Requires a user token (Bearer Token).
  Request Headers:
    Content-type: application/json
    Accept: application/json

Example Request (cURL):
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Bearer eyJ0eXAiOiJKV.eyJpZGVudGl0eSI6OTczMzAsInRydWVJZGVudGl0eS..._GT8jc8Xby-3sidRPk" "https://api.albato.com/wl/partner-name/upsert-own-credential"

Example Response:
{
    "success": true,
    "data": {
        "title": "Default credential",
        "accessToken": "••570f",
        "userId": 87123,
        "webhookUrl": "https://h.albato.com/wh/17600/1lfrdco/POoHj252FUkB7c8K252FeofTqNzAaoK34ClaUUnrz6vx1Q5pJE/"
    }
}
```

--------------------------------

### HTTP Request Connection and Automation Parameters

Source: https://wiki.albato.com/en/articles/9024290-how-to-work-with-http-requests

This section details the various parameters required when configuring an HTTP request connection and setting up automation within the Albato platform. It covers fields for initial connection setup and specific parameters for automation workflows, including request methods, headers, and body parameters.

```APIDOC
HTTP Request Connection Fields:
  Name: string
    - Description: Any user-defined name for the connection.
  URL: string
    - Description: The domain of the target CRM or API endpoint.
  HTTP request parameters (request body): object/string
    - Description: Data to be sent in the request body. Parameters vary based on the action (e.g., adding a car, finding by VIN, creating a contact). A complete list of required fields should be obtained from the receiving system's documentation.
  Headers: object
    - Description: Key-value pairs for request headers. Must include 'Authorization' for authentication.
  Content-Type: string
    - Description: The media type of the resource. Must be 'JSON' for JSON payloads.

Automation Fields:
  URL: string
    - Description: Leave empty; the URL specified in the App connection will be used.
  Request method: string
    - Description: The HTTP method to use for the request. Must be 'POST'.
  User-Agent header: string
    - Description: Identifies the client making the request. Must be 'Mozilla/5.0 (compatible; Albato/1.0)'.
  Authorization (header): string
    - Description: Authentication credentials. Format is 'Basic' followed by the Base64 encoding of 'login:password'.
    - Example: For login 'admin' and password 'password', the value is 'YWRtaW46cGFzc3dvcmQ='
  Parameters: object
    - Description: Specific data fields to transfer in the HTTP Request body for automation.
    - Fields: last_name, first_name, phone, email, dealer_code, request_type_id, source_id (these are examples; actual fields depend on the target system's requirements).
```

--------------------------------

### Albato Partner API: Get Own Credential Metadata

Source: https://wiki.albato.com/en/articles/9264449-method-for-getting-metadata-of-a-connection-to-your-own-system

API method to retrieve metadata for a connection to a partner's system, used for setting up user authentication. This method requires either a user token or a master account token for authorization.

```APIDOC
Albato Partner API: Get Own Credential Metadata

Endpoint: GET|POST https://api.albato.com/wl/partner-name/get-own-credential-metadata
Authorization: This method requires either a user token or a master account token.
Purpose: Retrieves metadata for a connection to your own system, which can be used to configure user authentication on your platform.

Response Parameters:
  - success (boolean): Indicates if the request was successful. Values: true, false.
  - data (object): Contains the connection metadata.
    - fields (array of objects): An array describing the connection fields.
      - id (string): The unique identifier for the field (e.g., "userId", "secretKey", "domain").
      - type (integer): The type of the field (e.g., 0, 3, 10).
      - label (string): A human-readable label for the field (e.g., "User ID", "Secret key", "Domain").
      - allowedValues (object, optional): For fields with predefined options, a map of value to display name (e.g., {"zone1.partner.com": "East-1", "zone2.partner.com": "West-1"}).

Example Response:
{
    "success": true,
    "data": {
        "fields": [
            {
                "id": "userId",
                "type": 0,
                "label": "User ID"
            },
            {
                "id": "secretKey",
                "type": 3,
                "label": "Secret key"
            },
            {
                "id": "domain",
                "type": 10,
                "label": "Domain",
                "allowedValues": {
                    "zone1.partner.com": "East-1",
                    "zone2.partner.com": "West-1"
                }
            }
        ]
    }
}
```

--------------------------------

### Map Simple JSON Object Field

Source: https://wiki.albato.com/en/articles/9887834-request-section

This example shows a basic JSON object with a single key-value pair. It illustrates how to map a direct field name for parameter configuration.

```json
{ "name":"John"}
```

--------------------------------

### Albato Telegram Bot Setup and Interaction Commands

Source: https://wiki.albato.com/en/articles/9579732-albato-telegram-bot

This section details the essential commands and actions required to connect and manage the Albato Telegram Bot within Telegram groups, enabling automated messaging and notifications. It covers initial setup, troubleshooting, and behavioral control.

```APIDOC
Command: /start <Token from your Albato connection>
Description: Initiates the connection between the Albato Telegram Bot and your Albato account within a specific Telegram group.
Parameters:
  <Token from your Albato connection>: A unique token generated from your Albato Telegram connection.
Usage: Send this command from the Telegram group where @AlbatoBot has been added.
Context: This command is crucial for the initial setup, linking a Telegram group to a specific Albato connection. A unique token is required for each group that needs a separate connection.
```

```APIDOC
Action: Add @AlbatoBot to a Telegram group
Description: Invites the Albato Bot to a Telegram group to enable its functionality.
Prerequisites: A Telegram group must exist, and the bot needs to be invited by a group administrator.

Action: Remove admin rights of @AlbatoBot
Description: Revokes administrative privileges from the Albato Bot in the group settings.
Purpose: Used to stop the bot from sending messages automatically after user messages or to limit its capabilities.

Action: Check bot permissions (Troubleshooting)
Description: Verify if the bot has permission to read messages in the group.
Context: This is a troubleshooting step when the bot doesn't seem to be receiving or processing messages from the group.

Action: Ensure bot has admin rights (Troubleshooting)
Description: Verify if the bot has the necessary administrative privileges in the group to perform actions like sending messages.
Context: This is a troubleshooting step when the bot isn't sending messages to the group, as it often requires admin rights for full functionality.
```

--------------------------------

### Albato User Session Management API

Source: https://wiki.albato.com/en/articles/10300885-implementation-guide-for-albato-embedded

This API documentation describes the methods for managing user sessions within Albato, including creating new users and refreshing session tokens for existing users. It outlines the parameters, return values, and conditional logic for handling different API responses.

```APIDOC
Albato User Management API:

1. Create a User
  Action: Call the Albato endpoint to add a new user.
  Inputs:
    - user_id* (string, required): Your internal customer ID, organization ID, workspace ID, or any other unique identifier for the user.
    - time zone (string, optional): The user's time zone.
    - language (string, optional): The user's preferred language.
  Outcomes:
    - HTTP 200 OK: User successfully created.
      Returns: A unique session token for the new user.
      Action: Save the user-session-token from the response. Use this token to pass the user's credential data to Albato using the SSO method (as described in Step 3).
    - HTTP 400 Bad Request: User already exists in Albato.
      Action: Call the 'Refresh User Token' endpoint to get a new session token for the existing user. Skip the SSO method step.

2. Refresh User Token
  Action: Call the Albato endpoint to get a new session token for an existing user.
  Trigger: This endpoint is typically called when the 'Create a User' endpoint returns an HTTP 400 response, indicating the user already exists.
  Returns: A new session token for the existing user.
```

--------------------------------

### Albato Partner API: Get Billing Plans

Source: https://wiki.albato.com/en/articles/9264154-method-for-getting-the-list-of-available-billing-plans

Retrieves a list of available billing plans for a partner's master account. Each billing plan specifies a monthly transaction limit. This method requires authorization using the partner's master account token.

```APIDOC
Endpoint: GET | POST https://api.albato.com/wl/partner-name/list-plans
Authorization: This method should be called with the partner's master account token.

Response Parameters:
  success: boolean - Request success indicator. Available values: true or false.
  data.id: integer - Plan ID.
  data.monthlyTrx: integer - Monthly transaction limit within a billing plan.

Request Example (curl):
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" "https://api.albato.com/wl/partner-name/list-plans"

Response Example:
{
    "success": true,
    "data": [
        {
            "id": 23,
            "monthlyTrx": 100000
        }
    ]
}
```

--------------------------------

### Albato String Split Tool Conceptual Example

Source: https://wiki.albato.com/en/articles/9024230-split-string-into-elements-of-a-row-section-array

This example illustrates the input string format and the resulting array structure after processing by the Albato string split tool. It shows how a delimited string is transformed into a structured array of objects, each containing a 'result' field, representing the split elements.

```JavaScript
string = 'name1;name2;name3'; // we get a string with several elements;
[
{
  "result": "name1"
},
{
  "result": "name2"
},
{
  "result": "name3"
}
]
//We display the result as three strings in one section.
```

--------------------------------

### cURL Example for Deleting a User

Source: https://wiki.albato.com/en/articles/9264140-method-for-deleting-a-user

This cURL command demonstrates how to send a POST request to the Albato API to delete a user. It includes setting the content type, accept headers, authorization token, and the user ID in the request body.

```bash
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --request POST --data '{"id":"test"}' "https://api.albato.com/wl/partner-name/delete-user"
```

--------------------------------

### HTTP Header Example for Data Extraction

Source: https://wiki.albato.com/en/articles/9887836-response-section

Illustrates the format for specifying an HTTP header key-value pair, such as 'dateTimeEvent', that Albato can recognize and extract. The key on the left is mapped to an entity field on the right to save the received value.

```HTTP
-H "dateTimeEvent: 2021-08-09 19:00:00"
```

--------------------------------

### Set User Billing Plan via cURL

Source: https://wiki.albato.com/en/articles/9264181-method-for-setting-a-user-billing-plan

Example cURL command to send a POST request to the Albato API's set-user-plan endpoint. It demonstrates how to include the necessary content type and authorization headers, along with the JSON request body containing the user ID and plan ID.

```shell
curl --header "Content-type: application/json" --header "Accept: application/json" --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" --data '{"id":"test", "planId": 23}' "https://api.albato.com/wl/partner-name/set-user-plan"
```

--------------------------------

### Configure HTTP Request Header with cURL Example

Source: https://wiki.albato.com/en/articles/9887834-request-section

This snippet demonstrates how to add a custom HTTP header to a request using the cURL command, illustrating the key-value pair concept for header configuration.

```curl
curl -H "Action: create"
```

--------------------------------

### Example JSON Response Structure with Array Data

Source: https://wiki.albato.com/en/articles/9887836-response-section

Demonstrates a typical JSON response body containing a root-level ID and an array of objects under the 'data' key. This structure is used to illustrate how Albato can process and map individual elements from such an array, allowing for iterative processing of array items.

```JSON
{ "id": 12345, "data":[  {   "name":"John",   "phone":"+19681112233"  },  {   "name":"Jhon",   "phone":"+19681112244"  } ]}
```

--------------------------------

### Example JSON Error Response Structure

Source: https://wiki.albato.com/en/articles/9887848-errors-section

Illustrates a typical JSON structure for an error response, which can be used as a source for mapping error messages within Albato's error handling configuration.

```JSON
{ "response":{  "error":"Error text"  }}
```

--------------------------------

### Example JSON Error Response Structure

Source: https://wiki.albato.com/en/articles/9887848-errors-section

This JSON snippet illustrates a common structure for an error response, containing a 'status' field indicating 'error' and a 'reason' field providing a descriptive message. This structure is used for configuring error handling logic.

```json
{ "status":"error", "reason":"Error occur..."}
```

--------------------------------

### Configure Albato Telegram Bot for Group Messaging

Source: https://wiki.albato.com/en/articles/10079283-how-to-connect-albato-telegram-bot

This section outlines the steps to connect the Albato Telegram Bot to a group chat, enabling it to send messages and integrate with Albato automations. It involves adding the bot to a group and authenticating it with a user-specific token.

```APIDOC
Albato Telegram Bot Group Configuration:

1. Add @AlbatoBot to your Telegram group.
2. Send the command /start followed by your Albato token in the group chat.

Expected Response: "Connection with token: XXXX successfully created. Now you can create an Albato automation using this connection."

Usage Notes:
- Multiple group connections are supported for different departments (e.g., sales, support).
- After sending the token, return to Albato connection settings and click 'Save' to finalize.
- The 'Chat is linked' status in Albato will change from 'no' to 'yes'.
```

--------------------------------

### Albato API: Block User Billing Plan

Source: https://wiki.albato.com/en/articles/9264197-method-for-blocking-a-user

Documents the API endpoint for blocking an existing user's billing plan within the Albato platform. This action pauses all user integrations and prevents new ones from starting. Authorization requires the partner's master account token.

```APIDOC
Endpoint:
  POST https://api.albato.com/wl/partner-name/block-user-plan

Authorization:
  This method requires the partner's master account token, typically passed via Basic authentication in the 'Authorization' header.

Request Parameters (JSON Body):
  - id (string, required): An alphanumeric user ID that the partner passes when creating a new user.

Response Parameters (JSON Body):
  - success (boolean): Request success indicator. Possible values: true or false.
  - data (array): An empty array, typically for future use or additional data.

Example Request (cURL):
  curl --header "Content-type: application/json" \
       --header "Accept: application/json" \
       --header "Authorization: Basic cEFJjGffUSkV6WFFyWUhBM1RzS2hRHg7iKgReghUiijBfrdTY6" \
       --data '{"id":"test"}' \
       "https://api.albato.com/wl/partner-name/block-user-plan"

Example Success Response:
  {
      "success": true,
      "data": []
  }
```

--------------------------------

### Albato User Session Token Refresh API Response Example

Source: https://wiki.albato.com/en/articles/9264147-method-for-refreshing-a-user-token

An example JSON response received from the Albato API after a successful request to refresh a user's session token. It illustrates the structure of the returned data, including the success status, and potentially permanent and temporary tokens with their expiration timestamp.

```json
{
    "success": true,
    "data": {
        "permanentToken": "IhIHggKkgBP-qtiDXLAMxKsSOO6A4Mu_L",
        "sessionToken": "eyJ0eXAiOiJKV.eyJpZGVudGl0eSI6OTczMzAsInRydWVJZGVudGl0eS..._GT8jc8Xby-3sidRPk",
        "sessionTokenValidUntil": 1654744263
    }
}
```

--------------------------------

### Telegram BotFather Commands for Bot Management and API Key Retrieval

Source: https://wiki.albato.com/en/articles/10079277-connecting-telegram-to-albato-integration-options

This section details the commands used with Telegram's BotFather to manage existing bots or create new ones, specifically to obtain the API key required for integration with platforms like Albato. These commands facilitate bot creation, listing, and API key retrieval.

```APIDOC
BotFather Commands:

/start
  - Description: Initiates a conversation with BotFather.
  - Usage: Send this command in a message to BotFather to begin interaction.

/mybots
  - Description: Lists all bots owned by the user and allows selection to manage them.
  - Usage: Send this command in a message to BotFather to view your existing bots and access their settings, including API key retrieval.
  - Parameters: None
  - Returns: A list of your bots, from which you can select one to manage and request its API key.

/newbot
  - Description: Guides the user through the process of creating a new Telegram bot.
  - Usage: Send this command in a message to BotFather to start creating a new bot. You will be prompted for:
    - Bot Name: A public name for your bot.
    - Username: A unique username for your bot, which must end with "bot" (e.g., `yourNamebot` or `yourName_bot`).
  - Returns: Upon successful creation, BotFather provides the new bot's API token (API key).
```

--------------------------------

### EzyCourse Integration Triggers and Actions for Albato

Source: https://wiki.albato.com/en/articles/10775566-how-to-connect-and-configure-webhook-for-ezycourse-to-albato

This section outlines the available triggers (events that initiate automation) and actions (steps performed after a trigger) for integrating EzyCourse with Albato. Triggers are real-time webhooks, while API triggers are checked at intervals.

```APIDOC
EzyCourse Integration Capabilities:

Available Triggers:
  - New sign-up: Initiates automation when a new user signs up.
  - New sale: Triggers automation upon a new sale event.
  - New product enrollment: Activates automation when a user enrolls in a new product.
  (Note: All triggers are real-time webhooks. API triggers are checked by Albato at 1-15 minute intervals based on plan.)

Available Actions:
  - Register a student: Registers a new student in EzyCourse.
  - Register and enroll a student: Registers a new student and enrolls them in a product.
  - Enroll product: Enrolls an existing student in a specific product.
  - Subscription cycle completed: Marks a subscription cycle as completed.
  - Unenroll product: Unenrolls a student from a product.
  - Toggle lesson progress: Changes the progress status of a lesson for a student.
  - Add tag to a student: Assigns a tag to a student.
  - Custom API request: Allows execution of custom API calls to EzyCourse.
```

--------------------------------

### Albato Webhook Event Configuration

Source: https://wiki.albato.com/en/articles/10775566-how-to-connect-and-configure-webhook-for-ezycourse-to-albato

This describes the structure for Albato webhook URLs, where specific event names are appended to the base URL to define different triggers for automations. It allows a single base webhook to handle multiple event types, such as new sign-ups or product enrollments.

```APIDOC
Webhook URL Structure:
  [BASE_WEBHOOK_URL]/[EVENT_NAME]

Parameters:
  BASE_WEBHOOK_URL: The unique base URL provided by Albato for your webhook (e.g., https://h.albato.ru/wh/24869/1lfpfao/iEFoYiXL43_bAoXvH4R********).
  EVENT_NAME: A custom string representing the event to be triggered.

Example Usage:
  - New Sign-up: newsignup
    Full URL: https://h.albato.ru/wh/24869/1lfpfao/iEFoYiXL43_bAoXvH4R********/newsignup

  - New Product Enrollment: newproductenrollment
    Full URL: https://h.albato.ru/wh/24869/1lfpfao/iEFoYiXL43_bAoXvH4R********/newproductenrollment

  - New Sale: newsale
    Full URL: https://h.albato.ru/wh/24869/1lfpfao/iEFoYiXL43_bAoXvH4R********/newsale

Purpose:
  Allows a single webhook to serve as a trigger for multiple distinct events within Albato automations by simply changing the path segment after the base URL.
```

--------------------------------

### Configure HTTP Authorization Requests for Token Management

Source: https://wiki.albato.com/en/articles/9887999-authorization-workflow-settings

This documentation describes the process of setting up HTTP requests within a platform's 'Requests widget' to manage API authorization tokens. It covers the initial acquisition of access and refresh tokens, saving them to variables, and subsequently using the refresh token to obtain new access tokens.

```APIDOC
HTTP Authorization Request Configuration:
  Purpose: To acquire and refresh access tokens for API authentication.
  Applicability: Authorization methods 'with login and password' and 'with API key'.

  1. Initial Access Token Acquisition Request:
    - Description: The first HTTP request widget is configured to obtain the initial access token upon connection creation.
    - Configuration:
      - URL: Specify the endpoint for token acquisition.
      - Method: HTTP method (e.g., POST).
      - Format: Request body format (e.g., JSON, form-urlencoded).
      - Body: Define request body parameters, potentially including dynamic variables (authorization fields).
      - Headers: Set necessary HTTP headers.
    - Response Handling:
      - Save accessToken: Configure the 'Response' tab to extract the access token from the response and save it to an 'accessToken' variable. This variable will be automatically transmitted with all subsequent outgoing HTTP requests from the application.
      - Save refreshToken (Optional): If 'Use RefreshToken' checkbox is enabled, configure the 'Response' tab to extract the refresh token from the response and save it to a designated variable.

  2. Token Update (Refresh) Request:
    - Description: A separate HTTP request widget is configured in the 'Update token' section to refresh the access token using the previously saved refresh token.
    - Configuration:
      - URL: Specify the endpoint for token refresh.
      - Method: HTTP method (e.g., POST).
      - Body/Headers: Pass the saved refresh token variable (and other dynamic variables if needed) in the request body or headers.
    - Response Handling:
      - Update accessToken: Crucially, set up the response parser in the 'Response' tab to receive, update, and save the new access token obtained from this refresh request.
```

--------------------------------

### Bitrix24 Marketplace App Direct Access Path

Source: https://wiki.albato.com/en/articles/10079197-connecting-bitrix24-to-albato-via-the-app

This specific URL path allows users to directly navigate to the Albato application details page within the Bitrix24 marketplace. It provides an alternative to searching for the app through the Bitrix24 interface.

```APIDOC
Path: /marketplace/detail/albato.connector/
Description: Direct path to the Albato app in Bitrix24 marketplace.
Usage: Append to your Bitrix24 domain (e.g., yourdomain.bitrix24.com/marketplace/detail/albato.connector/)
```

--------------------------------

### Configure RD Station Marketing Webhook for Albato

Source: https://wiki.albato.com/en/articles/10079223-how-to-connect-rd-station-marketing-to-albato

This section details the steps to set up a webhook in RD Station Marketing to send lead data to Albato. It covers naming the integration, providing the Albato webhook URL, and defining the trigger conditions for sending notifications.

```APIDOC
RD Station Marketing Webhook Configuration:

Fields:
  Name: string
    - Description: A descriptive name for the integration, ideally identifying the target tool (e.g., "Albato").
  URL: string (URL format)
    - Description: The webhook URL generated by Albato, where the data will be sent.
  Trigger: enum (Conversion, Opportunity)
    - Description: Defines the event that activates the notification sending.
    - Options:
      - Conversion:
        - Description: Sends leads that have performed a conversion in RD Station Marketing.
        - Details: Can select specific conversions to track, or leave blank to send any lead performing a conversion.
      - Opportunity:
        - Description: Sends leads marked as "Opportunity" (starred).
        - Details: Data is sent when a lead is manually marked as an opportunity or via an automation flow.

Actions:
  Save Webhook Button:
    - Description: Saves the webhook configuration and redirects to the configured Webhooks screen.
  Verify Button:
    - Description: Available on the configured Webhooks screen to test if the integration with the webhook is working.
```

--------------------------------

### Albato Bitrix24 Connection Configuration Fields

Source: https://wiki.albato.com/en/articles/10079197-connecting-bitrix24-to-albato-via-the-app

These fields are required when setting up a new Bitrix24 connection within the Albato platform. They define how Albato identifies and interacts with your specific Bitrix24 instance, allowing for proper data exchange.

```APIDOC
Connection Fields for Bitrix24 in Albato:

Name (string, required):
  - Purpose: User-defined name for the connection within Albato.
  - Constraints: Should be descriptive for easy identification.

Domain (string, required):
  - Purpose: The full domain of your Bitrix24 account.
  - Example: 'yourcompany.bitrix24.com'
  - Constraints: Must be copied directly from the browser's address bar when on your Bitrix24 page.

Phone format (string, required):
  - Purpose: Specifies the desired phone number format for data transfer to Bitrix24.
  - Constraints: Select from available options in Albato to ensure compatibility with Bitrix24's phone field.

Application ID (string, optional):
  - Purpose: Used for alternative connection methods where you add your own Albato app in Bitrix24.
  - Constraints: Skip if using the standard Albato app installation.

Application key (string, optional):
  - Purpose: Used in conjunction with Application ID for alternative connection methods.
  - Constraints: Skip if using the standard Albato app installation.
```

--------------------------------

### Dynamically Resize Albato iFrame with iframe-resizer.js

Source: https://wiki.albato.com/en/articles/9264467-embedding-albato-via-an-iframe

This JavaScript snippet integrates the `iframe-resizer` library to dynamically adjust the height of the embedded Albato iFrame. It first loads the library from a CDN and then initializes it for the iFrame with `id="albato"`, enabling public methods and using 'lowestElement' for height calculation. This script should be placed before the closing </body> tag.

```JavaScript
<script src="https://cdnjs.cloudflare.com/ajax/libs/iframe-resizer/4.3.2/iframeResizer.min.js"></script>
<script>
    iFrameResize({enablePublicMethods: true, heightCalculationMethod: 'lowestElement'}, '#albato')
</script>
```

--------------------------------

### Albato Embedded API: Custom System Connection Methods

Source: https://wiki.albato.com/en/collections/9383875-embedded-documentation

This section details the API methods for managing connections to your own system within Albato Embedded. It covers operations for creating, updating, retrieving, and fetching metadata for these custom connections.

```APIDOC
Method for creating/updating a connection to your own system
  - Endpoint: /api/v1/connections
  - Method: POST/PUT
  - Description: Establishes a new connection or updates an existing one to an external system.
  - Parameters: Connection details (e.g., name, type, credentials).
  - Returns: Connection object.

Method for getting a connection to your own system
  - Endpoint: /api/v1/connections/{connection_id}
  - Method: GET
  - Description: Retrieves the details of a specific connection to an external system.
  - Parameters: connection_id (path parameter).
  - Returns: Connection object.

Method for getting metadata of a connection to your own system
  - Endpoint: /api/v1/connections/{connection_id}/metadata
  - Method: GET
  - Description: Fetches metadata associated with a specific connection, such as available fields or schemas.
  - Parameters: connection_id (path parameter).
  - Returns: Metadata object.
```

--------------------------------

### Valuecase Integration API: Triggers and Actions

Source: https://wiki.albato.com/en/articles/10774536-how-to-connect-valuecase-to-albato

This section details the available triggers and actions for integrating Valuecase with Albato, enabling real-time data transfer and automation. Triggers initiate automation workflows, while actions perform operations within Valuecase.

```APIDOC
Available Triggers:
- New Space:
    Description: An event that triggers an automation when a new space is created in Valuecase.
    Execution: Runs in real-time; data is transferred the moment the event occurs.

Available Actions:
- Create Space:
    Description: Creates a new space in Valuecase.
    Parameters: (Implicit, typically requires space details like name, properties)
- Add External ID to Space:
    Description: Associates an external identifier with an existing Valuecase space.
    Parameters: (Implicit, typically requires space ID and external ID)
- Archive Space:
    Description: Archives an existing space in Valuecase.
    Parameters: (Implicit, typically requires space ID)
- Get Space by Slug:
    Description: Retrieves a Valuecase space using its slug.
    Parameters: (Implicit, typically requires a slug)
    Returns: Space details
- Return All Custom Properties of Space:
    Description: Fetches all custom properties associated with a specific Valuecase space.
    Parameters: (Implicit, typically requires space ID)
    Returns: List of custom properties
- Return Spaces by External ID:
    Description: Retrieves Valuecase spaces based on an external identifier.
    Parameters: (Implicit, typically requires an external ID)
    Returns: List of spaces
- Custom API Request:
    Description: Allows execution of a custom API request to Valuecase.
    Parameters: (Implicit, typically requires method, endpoint, body, headers)
- Update Custom Space Field:
    Description: Updates a specific custom field for a Valuecase space.
    Parameters: (Implicit, typically requires space ID, field name, new value)
```