WhatsApp

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

https://cloud.controller.touch-api.com/api/{METHOD_NAME}

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

Тело запроса обязательно должно содержать поле:

{
    "source": "whatsapp"
}

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

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

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

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

POST https://cloud.controller.touch-api.com/api/addAccount

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

Request Body

Name	Type	Description
token*	string	Токен для аутентификации
login*	string	Номер телефона
proxyString*	string	socks5://proxyUsername:proxyPassword@proxyIP:proxyPort
webhookUrl	string

200: OK Ok

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

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

POST 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*	String	Токен для аутентификации
login*	String	Номер телефона
webhookUrl	String
webhookUrls	Array	Массив вебхуков ["",""]

200: OK Ok

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

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

POST https://cloud.controller.touch-api.com/api/addWehook

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

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

Request Body

Name	Type	Description
token	String
webhookUrl	String
login	String

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

POST https://cloud.controller.touch-api.com/api/deleteAccount

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Номер телефона

200: OK Ok

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

setBeta

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

POST https://cloud.controller.touch-api.com/api/setBeta

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

Отправлять запрос с остановленным аккаунтом (перед вызовом сделать forceStop) для избежания конфликтов

Request Body

Name	Type	Description
token*		Токен для аутентификации
login*		Номер телефона
value*		true включить false выключить

200: OK

{
    "status": "ok"
}

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

POST https://cloud.controller.touch-api.com/api/setState

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Номер телефона
setState*	boolean	запуск/остановка аккаунта

200: OK

{
    "status": "ok"
}

200: OK

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

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

GET 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*	String	Токен для аутентификации
login*	String	Номер телефона
source*	String	whatsapp

200: OK

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

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

Настройки -> WhatsApp Web

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

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

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

POST https://cloud.controller.touch-api.com/api/getInfoByToken

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
skipDetails	boolean	если true, будет опрошен каждый аккаунт на статус подключения, если у Вас большое кол-во аккаунтов, рекомендуется использовать false, в таком случае актальным будет только defualtState , а далее опросить каждый аккаунт методом /getInfo

200: OK

{
    "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"
}

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

POST https://cloud.controller.touch-api.com/api/getIngo

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

Request Body

Name	Type	Description
token	String
login	String

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

POST https://cloud.controller.touch-api.com/api/forceStop

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

Request Body

Name	Type	Description
token	String
login	String

200: OK

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

Получить строку QR кода

POST https://cloud.controller.touch-api.com/api/getQr

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

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

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Номер телефона

200: OK if account runned in QR auth module, here will be link for QR

{
    "value": "String"
}

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

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

На данный момент этот способ не рекомендуется использовать как основной, только если пользователь не может авторизиваться по QR

1. Установить setState: false методом /setState

2. Очистить текущую сессию /сlearSession

3. Получить новый проки /getNewProxy

4. Переключить аккаунт в режим входа по коду /enablePhoneAuth

5. Установить setState: true методом /setState

6. Дождаться окончания загрузки и получить код /getAuthCode

7. Ввести полученный код на телефоне в приложении WhatsApp, в разделе Linked Diveces

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

POST https://cloud.controller.touch-api.com/api/enablePhoneAuth

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Логин для аутентификации
phone*	String	Номер телефона, который будет подключен

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

POST https://cloud.controller.touch-api.com/api/getAuthCode

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Логин для аутентификации

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

POST https://cloud.controller.touch-api.com/api/disablePhoneAuth

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Логин для аутентификации
phone*	String	Номер телефона

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

POST https://cloud.controller.touch-api.com/api/clearSession

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

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Номер телефона

200: OK

{
    "forceStop": true,
    "clearSession": true,
    "getNewProxy": true
}

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

POST https://cloud.controller.touch-api.com/api/getUserInfo

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
to*	String	phone like 380999999999
login*	String	Номер телефона

200: OK

{
    "number": 380999999999,
    "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"
}

400: Bad Request

{
    "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
}

Получечение информации об аккаунте

POST https://cloud.controller.touch-api.com/api/getInfo

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
login*	String	Номер телефона

200: OK

 {
	"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
	}
}

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

POST https://cloud.controller.touch-api.com/api/sendMessage

Request Body

Name	Type	Description
token*	String	Токен для аутентификации
msg*	object	Поля объекта описаны ниже
login*	String	Логин аккаунта

{
  "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 (устаревшее)
Account started successfully & realtime init done	5

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

Type	Src	Описание
image	image url	отправка / прием картинок
video	video url	отправка / прием видео
link	<description>&url=<url>	отправка / прием ссылки с текстом
audio	audio url	отправка / прием аудио
has_seen	*пустая строка*	статус сообщения “прочитано”
file	file url	отправка / прием файлов
geo	{"latitude": 50.4501,"longitude": 30.5234}	Отправка карты сообщением

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

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