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

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


---

# 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/whatsapp.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.