# 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 используется в случае когда не удалось распознать картинку, видео или аудио

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