> For the complete documentation index, see [llms.txt](https://docs.touch-api.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.touch-api.com/reference/opisanie-api/whatsapp.md).

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

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