# Telegram

Все запросы следует выполнять методом **POST** по адресу:

<mark style="color:blue;">`https://cloud.controller.touch-api.com/api/{METHOD_NAME}`</mark>

Тело передавать в **JSON**, ответ также будет **JSON-объект**.

<mark style="color:red;">Тело запроса</mark> <mark style="color:red;"></mark><mark style="color:red;">**обязательно**</mark> <mark style="color:red;"></mark><mark style="color:red;">должно содержать поле:</mark>

```json
{
    "source": "telegram"
}
```

Если в ответе есть поле "**error**", значит произошла какая то ошибка, и в этом поле содержится ее текстовое описание. Так же будет возвращен **uuid**, который необходимо указать при обращении в **техническую поддежку**.

```json
{
    "uuid": 3928420,
    "error": "Some error text goes here"
}
```

## Подключение аккаунта

1. **/addAccount** - добавление аккаунта в систему. (**Логином должен быть номер телефона**)
2. **/setState** - запуск аккаунта

В случае, если логин был указан неверно, метод вернет ошибку:

```json
{
    "error": "Error text goes here"
}
```

## Возможные проблемы <a href="#editional-problems" id="editional-problems"></a>

#### В момент первого запуска или после смены прокси возможны следующие ошибки:

1\. В случае ошибки "**Challenge required**" - код придет в телеграм или смс, и с полученным кодом следует вызвать метод **/solveChallenge**

2\. Если включена двухфакторная аутентификация (2FA), метод вернёт ошибку "**Two factor auth required**". С полученным в SMS кодом следует вызвать метод **/twoFactorAuth**<br>

## Добавить аккаунт

## Добавить новый телеграм аккаунт

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/addAccount`

Метод для подключения нового телеграм аккаунта

#### Request Body

| Name                                          | Type   | Description                                             |
| --------------------------------------------- | ------ | ------------------------------------------------------- |
| token<mark style="color:red;">\*</mark>       | string | Токен для аутентификации                                |
| login<mark style="color:red;">\*</mark>       | string | Ваш телеграм логин                                      |
| proxyString<mark style="color:red;">\*</mark> | string | socks5://proxyUsername:proxyPassword\@proxyIP:proxyPort |
| webhookUrl                                    | string |                                                         |

{% tabs %}
{% tab title="200: OK Ok" %}

```javascript
{
    "status": "ok",
    "uuid": "8bed4fe3-8221-4ecf-b696-a05e7af6f335"
}
```

{% endtab %}

{% tab title="400: Bad Request Account exist" %}

```javascript
{
    "status": "error",
    "error": {
        "message": "Such account is already exist"
    }
}
```

{% endtab %}
{% endtabs %}

## Обновить аккаунт

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/updateAccount`

#### Request Body

| Name                                    | Type   | Description                                             |
| --------------------------------------- | ------ | ------------------------------------------------------- |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации                                |
| login<mark style="color:red;">\*</mark> | String | Номер телефона                                          |
| proxyString                             | String | socks5://proxyUsername:proxyPassword\@proxyIP:proxyPort |
| webhookUrl                              | String |                                                         |

{% tabs %}
{% tab title="200: OK Ok" %}

```javascript
{
    "status": "ok",
    "uuid": "8bed4fe3-8221-4ecf-b696-a05e7af6f335"
}
```

{% endtab %}
{% endtabs %}

## Удалить аккаунт

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/deleteAccount`

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

{% tabs %}
{% tab title="200: OK Ok" %}

```javascript
{
    "status": "ok",
    "uuid": "8bed4fe3-8221-4ecf-b696-a05e7af6f335"
}
```

{% endtab %}
{% endtabs %}

## Изменить состояние (запуск/остановка)

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/setState`

Если сервер не отвечает после setState, возможно есть проблема с вашим прокси. Пожалуйста, обратитесь для проверки в техническую поддержку

#### Request Body

| Name                                       | Type    | Description                                                |
| ------------------------------------------ | ------- | ---------------------------------------------------------- |
| token<mark style="color:red;">\*</mark>    | String  | Токен для аутентификации                                   |
| login<mark style="color:red;">\*</mark>    | String  | Номер телефона                                             |
| setState<mark style="color:red;">\*</mark> | boolean | запуск/остановка аккаунта                                  |
| qrLogin                                    | boolean | для авторизации по QR коду необходимо задать значение true |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "status": "ok",
    "uuid": "8bed4fe3-8221-4ecf-b696-a05e7af6f335"
}
```

{% endtab %}
{% endtabs %}

## Получить информацию о подключенном аккаунте

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/getMe`

Получение информации о подключенном аккаунте. Может быть актуально в случае куар авторизации.

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "username": "String",
    "phone": "String"
}
```

{% endtab %}
{% endtabs %}

## Принудительная остановка

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/forceStop`

Метод принудительной остановки аккаунта может быть полезен в случае, если были ошибки во время запуска или setState:false выполняется с ошибкой

#### Request Body

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| token | String |             |
| login | String |             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "status": "ok",
    "uuid": "8bed4fe3-8221-4ecf-b696-a05e7af6f335"
}
```

{% endtab %}
{% endtabs %}

## Получить ссылку на QR код

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/getQr`

Если аккаунт находится в степе 2.2, то это актуальная ссылка. Если в степе 2.3, то ссылка не актуальна - нужно перезапускать

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

{% tabs %}
{% tab title="200: OK  if account runned in QR auth module, here will be link for QR" %}

```json
{
    "value": "String"
}
```

{% endtab %}
{% endtabs %}

## Очистка

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/clearSession`

Метод используется для очистки данныйх сессии. Перед очисткой необходимо остановить аккаунт, после успешной очистки запустить аккаунт.

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "forceStop": true,
    "clearSession": true,
    "getNewProxy": true

}
```

{% endtab %}
{% endtabs %}

## 2FA авторизация

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/twoFactorAuth`

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| code<mark style="color:red;">\*</mark>  | String | Код для 2FA              |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

## Авторизация по коду из смс/лс телеграма

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/solveChallenge`

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| code<mark style="color:red;">\*</mark>  | String | Код из сообщения         |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |

## Получить информацию о контакте <a href="#dobavit-kontakt" id="dobavit-kontakt"></a>

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/getUserInfo`

По умолчанию выставлены лимиты в 15 новых контактов в день + 200 новых контактов за все время.

#### Request Body

| Name                                                   | Type    | Description                          |
| ------------------------------------------------------ | ------- | ------------------------------------ |
| token<mark style="color:red;">\*</mark>                | String  | Токен для аутентификации             |
| login<mark style="color:red;">\*</mark>                | String  | Номер телефона                       |
| to<mark style="color:red;">\*</mark>                   | String  | тел. номер/user\_id/username         |
| allowContactCreation<mark style="color:red;">\*</mark> | boolean | Создать контакт, если он отсутствует |

{% tabs %}
{% tab title="400: Bad Request Если достигнут лимит" %}

```json
{
    "error": "Max total contact import count reached"
    // or
    "error": "Max per day contact import count reached"
}
```

{% endtab %}
{% endtabs %}

## Отправить сообщение

<mark style="color:green;">`POST`</mark> `https://cloud.controller.touch-api.com/api/sendMessage`

#### Request Body

| Name                                    | Type   | Description               |
| --------------------------------------- | ------ | ------------------------- |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации  |
| msg<mark style="color:red;">\*</mark>   | object | Поля объекта описаны ниже |
| login<mark style="color:red;">\*</mark> | String | Номер телефона            |

```json
{
  "to": String,
  "text": String or null,  // required if content is empty
  "content": [  // required if text is empty
    {
      "type": String,  
      "src": String,  // media url
    }
  ]
}
```

## Таблица состояний аккаунта

| Message                                                          | Value |
| ---------------------------------------------------------------- | ----- |
| Account just started to start                                    | 0     |
| <p>This account needs 2FA solving,</p><p> API Docs 2.1</p>       | 2.1   |
| QR code received                                                 | 2.2   |
| <p>This account needs challenge solving, </p><p>API Docs 2.2</p> | 2.25  |
| Can not update QR                                                | 2.3   |
| Another error during account launch                              | 2.5   |
| <p>Account started successfully & </p><p>realtime init done</p>  | 5     |

## Возможные content (в хуках, `/sendMessage` и `/getChatMessages`)

| Type      | Src                        | Описание                                         |
| --------- | -------------------------- | ------------------------------------------------ |
| image     | image url                  | отправка / прием картинок                        |
| video     | video url                  | отправка / прием видео                           |
| link      | \<description>\&url=\<url> | <p>отправка / прием</p><p> ссылки с текстом </p> |
| audio     | audio url                  | отправка / прием аудио                           |
| has\_seen | \*пустая строка\*          | статус сообщения “прочитано”                     |
| file      | file url                   | отправка / прием файлов                          |

\* file используется в случае когда не удалось распознать картинку, видео или аудио

\*\* красным выделено то, что еще не добавлено в апи


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.touch-api.com/reference/opisanie-api/telegram.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.