# Описание API

## Telegram API

{% content-ref url="/pages/lipdvv1SPQXZCTFjgIsT" %}
[Telegram](/reference/opisanie-api/telegram)
{% endcontent-ref %}

## WhatsApp API

{% content-ref url="/pages/nSEfoSf3IQXzqE58xkVF" %}
[WhatsApp](/reference/opisanie-api/whatsapp)
{% endcontent-ref %}


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

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


# Типовые ответы

## Доступ запрещен

```
{
    "status": "error",
    "error": {
        "message": "Access denied"
    }
}
```

## Значение не передано

```
{
    "status": "error",
    "error": {
        "message": "No value(string) sended"
    }
}
```

## Необходима авторизация по коду

```
{
    "status": "error",
    "error": {
        "message": "Challenge required"
    }
}
```

## Ошибка формата Proxy

```
{
    "status": "error",
    "error": {
        "message": "Invalid port component"
    }
}
```

## Попытка удалить несуществующий аккаунт

```
{
    "status": "error",
    "error": {
        "message": "Trying to delete unexisting account"
    }
}
```


# Конфигурация TG

## Получить список конфигураций

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

#### Request Body

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String |             |

## Получить конфигурацию

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

#### Request Body

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String |             |
| login<mark style="color:red;">\*</mark> | String |             |
| name<mark style="color:red;">\*</mark>  | String |             |

## Установить конфигурацию

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

#### Request Body

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark>  | String |             |
| login<mark style="color:red;">\*</mark>  | String |             |
| name<mark style="color:red;">\*</mark>   | String |             |
| config<mark style="color:red;">\*</mark> | Object |             |

**Config** позволяет настроить дополнительные параметры, такие как:

1. включение/отключение вебхуков на смену состояния (запуск, потеря соединения, конфликт)
2. реакция на открытие другого окна WhatsApp Web ("Использовать здесь")

| config name                | property name                       | type                     | meaning                                             | default                 |
| -------------------------- | ----------------------------------- | ------------------------ | --------------------------------------------------- | ----------------------- |
| services                   | stateHook                           | boolean                  | хуки на изменение состояния (п.1)                   | false                   |
| conflict                   | takeover                            | boolean                  | нажимать ли кнопку "Использовать здесь"             | false                   |
| <p><br></p><p>conflict</p> | <p><br></p><p>takeoverTimeoutMs</p> | <p><br></p><p>number</p> | задержка перед нажатием кнопки "Использовать здесь" | <p><br></p><p>10000</p> |

#### Пример вебхука при смене состояния:

```
{
  state: {
    current: {
      message: 'Account started successfully & is connected to phone now',
      value: 5
    },
    previous: {
      message: 'Account just started to start',
      value: 0
    }
  },
  time: 1597481788993000000,
  login: '380999999999',
  phone: '380999999999'
}

```

#### Пример входящего вебхука

```
{
  "from":"79999999999", 
  "to":"7998888888",
  "text":"text ", // текст сообщения
  "content": [
    {
      "type":"delivered", //статус доставки сообщения
      //возможные статусы
      //has_seen прочитано 
      //server отправлено на сервер
      //delivered доставлено получателю
      "src":"" //ссылка на медиа файл
    }
  ],
  "time":1637138181000000,
  "thread":"79999999999@c.us",
  "item":"99F39D2154F84418EAF0B4EDD3AFD90A",
  "source":"whatsapp"
}
```


# WhatsApp

Все запросы следует выполнять методом **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": "whatsapp"
}
```

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

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

```

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

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

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

После успешного вызова можно сразу вызвать setState для запуска аккаунта

#### 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": "62441448-e337-4288-9a0b-5496a81b2e25"
}
```

{% endtab %}
{% endtabs %}

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

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

Перед вызовом данного метода аккаунт должен находит в выклюенном состоянии ( state : false ), после успешного выполнения необходимо выполнить /setState со значением state : true .

UPD: С 04.12.2023 нет необходимости устанавливать setState: TRUE || FALSE для обновления вебхуков

Чтобы удалить вебхуки -  передайте пустой массив в параметре webhooksUrls

#### Request Body

| Name                                    | Type   | Description              |
| --------------------------------------- | ------ | ------------------------ |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации |
| login<mark style="color:red;">\*</mark> | String | Номер телефона           |
| webhookUrl                              | String |                          |
| webhookUrls                             | Array  | Массив вебхуков \["",""] |

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

```javascript
{
    "status": "ok",
    "uuid": "62441448-e337-4288-9a0b-5496a81b2e25"
}
```

{% endtab %}
{% endtabs %}

## Добавить вебхук в массив вебхуков

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

Метод добавляет вебхук для приема сообщений на заданный Url

Чтобы удалить вебхуки - передайте пустой массив в параметре webhooksUrls /updateAccount

#### Request Body

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

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

<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": "62441448-e337-4288-9a0b-5496a81b2e25"
}
```

{% endtab %}
{% endtabs %}

## setBeta

## Устаревший метод.

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

Актаулен только если аккаунт был создан до 01.08.2022 и beta не был задан true

<mark style="color:red;">Отправлять запрос с остановленным аккаунтом (перед вызовом сделать forceStop) для избежания конфликтов</mark>

#### Request Body

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

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

```javascript
{
    "status": "ok"
}
```

{% 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 | запуск/остановка аккаунта |

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

```javascript
{
    "status": "ok"
}
```

{% endtab %}

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

```javascript
{
    "status": "error",
    "error": {
        "message": "QR code received"
    }
}
```

{% endtab %}
{% endtabs %}

После успешного вызова **`/setState`** можно сразу запросить QR-код методом GET:

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

пример: <https://controller.touch-api.com/api/screenshot?token={token}&login={login}&source=whatsapp>

#### Path Parameters

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

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

```
Возвращает изображение (скриншот) с QR кодом для авторизации
```

{% endtab %}
{% endtabs %}

Полученный QR код нужно отсканировать приложением WhatsApp в телефоне&#x20;

{% hint style="info" %}
**Настройки** -> **WhatsApp Web**
{% endhint %}

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

Если скриншот не грузит и ваши сервера расположены в России, можно ко всем GET запросам передать дополнительный параметр `useAlternativeAddress=1`, который решит эту проблему

<br>

## Получить данные по токену

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

Получении информации об аккаунтах, приязанных к токену

#### Request Body

| Name                                    | Type    | Description                                                                                                                                                                                                                                  |
| --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token<mark style="color:red;">\*</mark> | String  | Токен для аутентификации                                                                                                                                                                                                                     |
| skipDetails                             | boolean | если true, будет опрошен каждый аккаунт на статус подключения, если у Вас большое кол-во аккаунтов, рекомендуется использовать false, в таком случае актальным будет только defualtState  , а далее опросить каждый аккаунт методом /getInfo |

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

```javascript
{
    "clients": [
        {
            "activated": false,
            "defaultState": true,
            "apiV": "beta/s30",
            "additional": {
                "isBeta": false,
                "_id": "6390ea93cf925c28d7883875",
                "config": {
                    "_id": "6390ea93cf925c28d7883876",
                    "services": {
                        "outgoingOnlyHook": false,
                        "_id": "6390ea93cf925c28d7883877",
                        "stateHook": false
                    },
                    "conflict": {
                        "_id": "6390ea93cf925c28d7883878",
                        "takeover": false,
                        "takeoverTimeoutMs": 10000
                    }
                }
            },
            "_id": "6390ea93cf925c28d7883874",
            "owner": "73375e42-efdf-4129-8068-0894d39ff98e",
            "login": "81231239944",
            "proxyString": "http://tizwrnqy:4ex8l9xcb2m7@5.183.60.151:7163/",
            "addedTime": 1670441619182,
            "__v": 0,
            "state": true,
            "step": {
                "message": "QR code received",
                "value": 2.2
            }
        }
    ],
    "summary": {
        "active": 1,
        "activated": 0,
        "demo": 1,
        "count": 1,
        "payment": {
            "mode": "per month",
            "balance": 0
        }
    },
    "errors": [],
    "status": "ok",
    "uuid": "07c88bf7-3286-431a-b738-c02b1cfbbf37"
}
```

{% endtab %}
{% endtabs %}

## Получить данные по аккаунту

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

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

#### Request Body

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

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

<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": "62441448-e337-4288-9a0b-5496a81b2e25"
}
```

{% endtab %}
{% endtabs %}

## Получить строку QR кода <a href="#poluchit-ssylku-na-qr-kod" id="poluchit-ssylku-na-qr-kod"></a>

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

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

После получения ответа из значения value необходимо сформировать QR и отсканировать его через приложение WhatsApp

Код обновлеяется каждые 10 секунд, если пользователь не успел подключиться необходимо сформировать код заново

#### 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" %}

```javascript
{
    "value": "String"
}
```

{% endtab %}
{% endtabs %}

## Описание авторизации по коду для ввода в приложении вместо сканирования QR

> На данный момент функция получения кода может занимать больше времени чем получения QR кода в связи со спецификой установки соединения с WhatsApp и получения кода авторизации, ниже список действий для авторизации по коду.
>
> **На данный момент этот способ не рекомендуется использовать как основной, только если пользователь не может авторизиваться по QR**

1. Установить setState: false методом /setState
2. Очистить текущую сессию /сlearSession
3. Получить новый проки /getNewProxy
4. Переключить аккаунт в режим входа по коду /enablePhoneAuth
5. Установить setState: true методом /setState
6. Дождаться окончания загрузки и получить код /getAuthCode
7. Ввести полученный код на телефоне в приложении WhatsApp, в разделе Linked Diveces

## Включить авторизацию по коду

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

Активация авторизации по коду, если нет возможности отсканировать QR

#### Request Body

| Name                                    | Type   | Description                             |
| --------------------------------------- | ------ | --------------------------------------- |
| token<mark style="color:red;">\*</mark> | String | Токен для аутентификации                |
| login<mark style="color:red;">\*</mark> | String | Логин для аутентификации                |
| phone<mark style="color:red;">\*</mark> | String | Номер телефона, который будет подключен |

## Получить код для входа

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

Получить код для ввода в приложении WhatsApp&#x20;

#### Request Body

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

## Выключить авторизацию по коду

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

#### Request Body

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

## Очистка сессии

<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 %}

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

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

#### Request Body

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

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

<pre class="language-json"><code class="lang-json">{
<strong>    "number": 380999999999,
</strong>    "isBusiness": false,     
    "isEnterprise": false,
    "labels": [],
    "name": "Name",
    "pushname": "iv",
    "shortName": "Name",
    "statusMute": false,
    "type": "in",
    "isMe": false,
    "isUser": true,
    "isGroup": false,
    "isWAContact": true,
    "isMyContact": true,
    "status": "ok"
}
</code></pre>

{% endtab %}

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

```json
{
    "status": "error", 
    "error": { "message": "Such user is not exist" }
    // if there isn't whatsapp registered with this phonen
}
// OR
{
    "status": "error",
    "error": { "message": "Such user is not in contact list" } 
    // someone with this phone has whatsapp, but he isn't in your contacts
}
```

{% endtab %}
{% endtabs %}

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

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

#### 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
 {
	"source": "whatsapp",
	"login": "String",
	"owner": "String",
	"activated": true // or false,
	"addedTime": "timestamp",
	"webhookUrl": "String",
	"proxyString": "String",	
	"defaultState": true // or false,
	"APIv": "String",
	"state": true // or false,
	"step": {
		"message": "String",
		"value": 1 // number
	}
}

```

{% 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                |
| False session                                                         | 2.0 (устаревшее) |
| QR code received                                                      | 2.2              |
| Can not update QR                                                     | 2.3              |
| Код авторизации получен                                               | 2.22             |
| Connection with phone was timeouted and will be retried in 20 seconds | 3.0 (устаревшее) |
| Trying to run two Whatsapp instances                                  | 3.7 (устаревшее) |
| Trying to reconnect with phone                                        | 3.9 (устаревшее) |
| <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                                   | отправка / прием файлов                          |
| geo       | {"latitude": 50.4501,"longitude": 30.5234} | Отправка карты сообщением                        |

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

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


# Конфигурация WA

## Получить список конфигураций

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

#### Request Body

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String |             |

## Получить конфигурацию

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

#### Request Body

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String |             |
| login<mark style="color:red;">\*</mark> | String |             |
| name<mark style="color:red;">\*</mark>  | String |             |

## Установить конфигурацию

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

#### Request Body

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark>  | String |             |
| login<mark style="color:red;">\*</mark>  | String |             |
| name<mark style="color:red;">\*</mark>   | String |             |
| config<mark style="color:red;">\*</mark> | Object |             |

**Config** позволяет настроить дополнительные параметры, такие как:

1. включение/отключение вебхуков на смену состояния (запуск, потеря соединения, конфликт)
2. реакция на открытие другого окна WhatsApp Web ("Использовать здесь")

| config name                | property name                       | type                     | meaning                                             | default                 |
| -------------------------- | ----------------------------------- | ------------------------ | --------------------------------------------------- | ----------------------- |
| services                   | stateHook                           | boolean                  | хуки на изменение состояния (п.1)                   | false                   |
| conflict                   | takeover                            | boolean                  | нажимать ли кнопку "Использовать здесь"             | false                   |
| <p><br></p><p>conflict</p> | <p><br></p><p>takeoverTimeoutMs</p> | <p><br></p><p>number</p> | задержка перед нажатием кнопки "Использовать здесь" | <p><br></p><p>10000</p> |

#### Пример вебхука при смене состояния:

```
{
  state: {
    current: {
      message: 'Account started successfully & is connected to phone now',
      value: 5
    },
    previous: {
      message: 'Account just started to start',
      value: 0
    }
  },
  time: 1597481788993000000,
  login: '380999999999',
  phone: '380999999999'
}

```

#### Пример входящего вебхука

```
{
  "from":"79999999999", 
  "to":"7998888888",
  "text":"text ", // текст сообщения
  "content": [
    {
      "type":"delivered", //статус доставки сообщения
      //возможные статусы
      //has_seen прочитано 
      //server отправлено на сервер
      //delivered доставлено получателю
      "src":"" //ссылка на медиа файл
    }
  ],
  "time":1637138181000000,
  "thread":"79999999999@c.us",
  "item":"99F39D2154F84418EAF0B4EDD3AFD90A",
  "source":"whatsapp"
}
```


# Типовые ответы

## Доступ запрещен

```
{
    "status": "error",
    "error": {
        "message": "Access denied"
    }
}
```

## Значение не передано

```
{
    "status": "error",
    "error": {
        "message": "No value(string) sended"
    }
}
```

## Необходима авторизация по коду

```
{
    "status": "error",
    "error": {
        "message": "Challenge required"
    }
}
```

## Ошибка формата Proxy

```
{
    "status": "error",
    "error": {
        "message": "Invalid port component"
    }
}
```

## Попытка удалить несуществующий аккаунт

```
{
    "status": "error",
    "error": {
        "message": "Trying to delete unexisting account"
    }
}
```