```perl
#!/usr/bin/env perl
use Mojo::Webqq;
my ($host, $port, $post_api);

$host = "0.0.0.0"; # Адрес прослушивания API для отправки сообщений, не меняйте если нет необходимости
$port = 5000;      # Порт прослушивания API для отправки сообщений, установите свой порт
#$post_api = 'http://xxxx';  # Адрес для получения входящих сообщений, удалите или закомментируйте эту строку, если вам это не требуется

my $client = Mojo::Webqq->new();
$client->load("ShowMsg");
$client->load("Openqq", data => { listen => [{ host => $host, port => $port }], post_api => $post_api });
$client->run();

$ perl xxxx.pl

Mojo::Webqq->new(log_level=>"info", http_debug=>0, tmpdir=>'C:\tmpdir\'); # Убедитесь, что указанная директория существует и доступна

### Описание состояний работы клиента

Клиент может находиться в различных состояниях во время своей работы. Некоторые из этих состояний являются блокирующими, то есть представляют собой бесконечные циклы, которые могут быть прерваны только при достижении определённых условий.

В режиме одного аккаунта используется однопоточная асинхронная модель, все API работают в неблокирующем режиме, поэтому во время блокирующего состояния некоторые операции API (например, отправка и получение сообщений) становятся недоступными. Например: В состоянии сканирования входа, если вход ещё не завершён, API для отправки сообщений вызывать нельзя, запрос не получит никакого ответа.

Понимание различий этих состояний клиента поможет вам правильно использовать API.| **Состояние** | **Режим** | **Описание состояния** |
| -------------- | ---------- | :---------------------- |
| init           | -          | Начальное состояние после создания клиента |
| loading        | blocking   | Клиент загружает плагины |
| scanning       | blocking   | Ожидание сканирования телефона |
| confirming     | blocking   | Ожидание нажатия кнопки "Подтвердить" на телефоне |
| updating       | blocking   | Обновление информации о себе, друзьях, группах и темах обсуждения |
| running        | non-blocking | Клиент работает в нормальном режиме, может принимать и отправлять сообщения, **соответствующие API работают** |
| stop           | -          | Клиент прекращает работу |Общий процесс перехода состояний клиента:

`init` => `loading` => `scanning` => `confirming` => `updating` => `running` => `stop`

Состояния клиента обновляются в реальном времени в файле `mojo_webqq_state_{название_клиента}.json`, который можно прочитать для получения текущих состояний.

Также можно получить текущее состояние клиента через событие `state_change` в разделе [Отчет о событиях](API.md#отчет-о-событиях).

В случае использования нескольких аккаунтов также можно проверить это состояние через интерфейс `/openqq/check_client`, предоставленный контроллером.

(Интерфейс `/openqq/check_client` фактически возвращает данные из файла `mojo_webqq_state_{название_клиента}.json`.)

### Описание запросов heartbeat

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

Установка параметров `poll_api` и `poll_interval` в плагине `Openqq` заставляет клиента при работе в состоянии `running` автоматически запрашивать адрес `poll_api`.

Желательно, чтобы этот запрос был долгоживущим и ожидал ответа, а сервер не возвращал данных (логика сервера должна быть реализована самостоятельно).

При получении ответа от сервера или истечении времени ожидания запрос будет повторяться каждые `poll_interval` секунд, так продолжается цикл.Если ваша программа установлена в локальной сети, но вы хотите обращаться к ней с внешнего сервера для выполнения действий, таких как отправка сообщений, то эта конфигурация может помочь вам в этом. Когда внешний сервер хочет, чтобы клиентская программа в локальной сети вызвала определённый API-интерфейс, например, отправила сообщение указанному другу с помощью `/openqq/send_friend_message`, сервер использует HTTP-ответ 302 Location для передачи полного адреса API.Сервер отвечает HTTP-ответом 302 Redirect с полным адресом API:

Клиент, получив ответ 302, автоматически переходит по указанному адресу (клиент сам запрашивает свой локальный адрес 127.0.0.1) для выполнения операции отправки сообщения.

### Получение данных пользователя
|   API  | Получение данных пользователя |
|--------|:------------------------------|
| uri    | /openqq/get_user_info          |
| Метод запроса | GET                          |
| Запросные параметры | Нет                         |
| Пример запроса | http://127.0.0.1:5000/openqq/get_user_info |

Формат ответа:

```json
{
    "name": "小灰",
    "mobile": "188********",
    "state": "online",
    "client_type": "web",
    "email": "",
    "city": "北京",
    "personal": "这是我的个性签名",
    "province": "北京",
    "id": "1234567",
    "birthday": "1990-01-01",
    "sex": "male",
    "country": "中国",
    "uid": "1234567",
    "account": "1234567",
    "college": "",
    "occupation": "计算机/互联网/IT",
    "phone": "",
    "homepage": "",
    "blood": "3",
    "signature": " "
}

### Получение данных группы
|API|Получение данных группы|
|---|----------------------|
|URI|/openqq/get_group_info|
|Метод запроса|GET|
|Запросные параметры|Нет|
|Пример вызова|http://127.0.0.1:5000/openqq/get_group_info|

Возвращаемый JSON массив:
```json
[
    {# Первая группа
        "markname": "xxx",
        "id": "",
        "uid": "552603",
        "code": "",
        "name": "",
        "role": "",
        "createtime": "",
        "owner_id": 12345,
        "owner_uid": 123456,
        "max_member": 2000,
        "max_admin": 10,
        "member": [
            {
                "qage": "16",
                "name": "xxx",
                "join_time": "0",
                "state": "offline",
                "client_type": "unknown",
                "city": "Дальний",
                "province": "Ляонин",
                "id": "2832277643",
                "sex": "мужской",
                "bad_record": "0",
                "country": "Китай",
                "uid": "45678",
                "last_speak_time": "1453449884",
                "role": "участник",
            },
            {
                "qage": "16",
                "name": "xxx",
                "join_time": "0",
                "state": "offline",
                "client_type": "unknown",
                "city": "Дальний",
                "province": "Ляонин",
                "id": "2832277643",
                "sex": "мужской",
                "bad_record": "0",
                "country": "Китай",
            }
        ]
    }
]
``````markdown
                "uid": "123455",
                 "last_speak_time": "1453449884",
                 "role": "OWNER",
             },
         ]
     },
     {#Second group
     . . .
     }
 ]

|   API  |Получение базовых данных группы (не включает участников группы) |
|--------|:-------------------------------------------------------------|
| uri    | /openqq/get_group_basic_info                                 |
| Метод запроса | GET                                                      |
| Запросные параметры | Нет                                                     |
| Пример вызова | http://127.0.0.1:5000/openqq/get_group_basic_info          |

### Получение данных обсуждения
|   API  |Получение данных обсуждения                                   |
|--------|:------------------------------------------------------------|
| uri    | /openqq/get_discuss_info                                      |
| Метод запроса | GET                                                       |
| Запросные параметры | Нет                                                     |
| Пример вызова | http://127.0.0.1:5000/openqq/get_discuss_info               |
Возвращаемый JSON массив:

```json
[
    {
        "name": "тест",
        "id": "4118239384",
        "owner_id": "4118239384",
        "member": [
            {
                "id": "4118239384",
                "name": "Серый",
                "state": "offline",
                "client_type": "unknown",
                "uid": "123456"
            },
            {
                "did": "4118239384",
                "nick": "Хаха",
                "state": "offline",
                "client_type": "unknown",
                "dname": "тест",
                "id": "456789"
            }
        ]
    }
]

{"status":"Message successfully sent","id":23910327,"code":0} # code = 0 indicates successful sending

{"status":"Message successfully sent","id":23910327,"code":0} # code = 0 indicates successful sending
``````http://127.0.0.1:3000/openwx/send_group_message?id=xxxx&content=hello&async=1```

### Отправка сообщения в группу
|   API  | Отправка сообщения в группу |
|--------|:---------------------------|
| uri    | /openqq/send_group_message  |
| метод запроса | GET\|POST                 |
| параметры запроса | **id**: ID группы (может меняться при каждом входе) <br> **content**: содержание сообщения (китайский текст требует urlencode) <br> **async**: 0 или 1, опционально, асинхронная отправка сообщения |
| формат данных | application/x-www-form-urlencoded |
| Пример использования | http://127.0.0.1:5000/openqq/send_group_message?id=xxxx&content=hello <br> http://127.0.0.1:5000/openqq/send_group_message?id=xxx&content=%e4%bd%a0%e5%a5%bd |

Возвращаемый JSON массив:

Если успех отправки сообщения вас не интересует, можно использовать асинхронную отправку, что позволит вызываемому интерфейсу сразу вернуться:```http://127.0.0.1:3000/openwx/send_group_message?id=xxxx&content=hello&async=1```

### Отправка временного сообщения в группу
|   API  |Отправка временного сообщения в группу (было заблокировано Tencent)|
|--------|:---------------------------------------------------------------|
|uri     |/openqq/send_sess_message                                        |
|метод запроса|GET\|POST                                                     |
|параметры запроса|**group_id**: ID группы (может меняться при каждом сканировании входа)<br>**group_uid**: номер группы<br>**id**: ID незнакомца (может меняться при каждом сканировании входа)<br>**uid**: QQ номер незнакомца<br>**content**: содержание сообщения (китайский текст требует urlencode)|
|формат данных|application/x-www-form-urlencoded                              |
|Пример использования|http://127.0.0.1:5000/openqq/send_sess_message?group_id=xxxx&id=xxx&content=hello<br>http://127.0.0.1:5000/openqq/send_sess_message?group_uid=xxx&uid=xxx&content=%E4%BD%A0%E5%A5%BD|
Возвращаемый JSON массив:

|   API  |Отправка временного сообщения в беседу (было заблокировано Tencent) |
|--------|:---------------------------------------------------------------:|
| uri    | /openqq/send_sess_message                                        |
| метод запроса | GET \| POST                                                 |
| параметры запроса | **discuss_id**: ID беседы (может меняться при каждом сканировании входа)<br>**id**: ID незнакомца (может меняться при каждом сканировании входа)<br>**uid**: QQ номер незнакомца<br>**content**: содержание сообщения (китайский текст требует urlencode) |
| формат данных | application/x-www-form-urlencoded                            |
| Пример использования | http://127.0.0.1:5000/openqq/send_sess_message?discuss_id=xxxx&id=xxx&content=hello<br>http://127.0.0.1:5000/openqq/send_sess_message?discuss_id=xxx&uid=xxx&content=%E4%BD%A0%E5%A5%BD |

Возвращаемый JSON массив:

| API | Используйте HTTP GET для долгого ожидания получения событий (сообщений) |
| ---- | :--------------------------------------------------------------------- |
| uri  | /openqq/check_event                                                    |
| метод запроса | GET                                                             |
| формат данных | application/json                                               |

Интерфейс возвращает JSON-массив, каждый элемент которого представляет собой JSON-сообщение с тем же форматом, что и [адрес отчета о пользовательских событиях](API.md#адрес_отчета_о_пользовательских_событиях).

Программа максимум хранит последние 20 записей, размер этого буфера можно настроить через параметр плагина `check_event_list_max_size`. Клиент использует долгополлинговый механизм, при отсутствии событий (сообщений) запрос будет висеть в ожидании 30 секунд, после чего завершится, требуя повторной отправки запроса клиентом.

API может работать только в неблокирующем режиме, что ограничивает его возможности; он менее полезен, чем POST-запросы для получения информации. В настоящее время поддерживаются следующие события:

отправка сообщения, получение сообщения и следующий набор событий:

`новое_групповое_сообщение`, `новый_пользователь`, `новый_участник_группового_сообщения`, `новое_диалоговое_сообщение`, `новый_участник_диалогового_сообщения`

`потерянное_групповое_сообщение`, `потерянный_пользователь`, `потерянный_участник_группового_сообщения`, `потерянное_диалоговое_сообщение`, `потерянный_участник_диалогового_сообщения````
* Подключен к 127.0.0.1 (127.0.0.1) порт 5000 (#0)
> GET /openqq/check_event? HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.0.0.1:3000
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
< Date: Tue, 22 Nov 2016 04:11:36 GMT
< Content-Length: 16405
< Server: Mojolicious (Perl)

[
   {
      "класс": "отправка",
      "контент": "hello world",
      "идентификатор": "2647366348175870091",
      "тип_сообщения": "отправка_сообщения",
      "получатель": "小灰",
      "идентификатор_получателя": "xxxxxx",
      "uid_получателя": 12345,
      "отправитель": "灰灰",
      "время": "1479787946",
      "тип": "личное_сообщение"
   }
]

* Подключен к 127.0.0.1 (127.0.0.1) порт 3000 (#0)
> GET /openqq/check_event? HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.0.0.1:3000
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
< Date: Tue, 22 Nov 2016 04:11:36 GMT
< Content-Length: 16405
< Server: Mojolicious (Perl)

[]

Сначала следует ознакомиться с некоторыми ключевыми атрибутами сообщений:Тип `post_type` в JSON данных, отправляемых или получаемых, используется для разделения сообщений на различные категории.

| Ключевой атрибут | Возможные значения | Описание |
| :--------------- | :----------------- | :-------- |
| post_type         | receive_message<br>send_message<br>event | Получение сообщения<br>Отправка сообщения<br>Другие события |

Ключевые атрибуты для отправленных/полученных сообщений (`post_type` равен `receive_message` или `send_message`) :| Атрибут          | Возможные значения | Описание |
| :--------------- | :----------------- | :-------- |
| id                | -                  | Уникальный идентификатор сообщения |
| type              | friend_message<br>group_message<br>discuss_message<br>sess_message | Подкатегории типов сообщений:<br> Сообщение от друга<br> Сообщение группы<br> Сообщение обсуждения<br> Временное сообщение |
| class             | send<br>recv       | Обозначает, является ли это отправленным или полученным сообщением |
| sender_id         | -                  | Уникальный идентификатор отправителя сообщения (не все типы сообщений имеют этот атрибут) |
| sender_uid        | -                  | QQ номер отправителя сообщения (не все типы сообщений имеют этот атрибут) |
| receiver_id       | -                  | Уникальный идентификатор получателя сообщения (не все типы сообщений имеют этот атрибут) |
| receiver_uid      | -                  | QQ номер получателя сообщения (не все типы сообщений имеют этот атрибут) |
| group_id          | -                  | Уникальный идентификатор группы, связанной с сообщением (не все типы сообщений имеют этот атрибут) |
| group_uid         | -                  | QQ номер группы, связанной с сообщением (не все типы сообщений имеют этот атрибут) |При получении сообщения, оно передается через JSON данные POST запросом к этому интерфейсу.

```markdown
Подключение к 127.0.0.1 порт 5000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "time": "1442542632",
    "content": "тест",
    "class": "recv",
    "sender": "Грей",
    "sender_id": "2372835507",
    "sender_uid": "456789",
    "receiver": "Маленький Грей",
    "receiver_id": "4072574066",
    "receiver_uid": "123456",
    "group": "Обучение PERL",
    "group_id": "2617047292",
    "group_uid": "67890",
    "id": "10856",
    "type": "group_message",
    "post_type": "receive_message"
}

{
    "ответ": "xxxxx",    # Чтобы ответить на сообщение, необходимо включить свойство reply
    "mute": 1,           # Необязательный параметр, указывающий, следует ли замутить отправителя сообщения
    "mute_duration": 60  # Необязательный параметр, продолжительность мута в секундах, значение по умолчанию — 60 сек
}

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json;charset=UTF-8
Date: Mon, 29 Feb 2016 05:53:31 GMT
Content-Length: 27
Server: Mojolicious (Perl)

{"ответ": "Привет", "код": 0}

| Название события                | Описание события          | Отправленные параметры                                                                 |
|-------------------------------|:--------------------------|:--------------------------------------------------------------------------------------|
| login                         | Клиентское приложение вошло в систему | *1*: указывает, что после сканирования QR-кода ID друзей могут измениться<br>*0*: указывает, что без сканирования QR-кода ID друзей не изменятся |
| stop                          | Клиентское приложение завершено      | Приложение прекращает работу, программа завершается                                  |
| state_change                  | Изменение состояния клиента         | Предыдущее состояние, новое состояние См.  [Описание состояний клиентского приложения](API.md#описание-состояний-клиента)                 |
| input_qrcode                  | Сканирование QR-кода               | Локальный путь сохранения QR-кода, base64-кодировка исходных данных QR-кода           |
| new_group                     | Вступил в новый чат             | Соответствующий объект группы                                                         |
| new_discuss                   | Вступил в новую группу обсуждений | Соответствующий объект группы обсуждений                                             |
| new_friend                    | Добавлен новый друг             | Соответствующий объект друга                                                         |
| new_group_member              | Добавлен новый участник группы    | Соответствующий объект участника, соответствующий объект группы                      |
```|new_discuss_member            | Добавлен новый участник группы обсуждений | Соответствующий объект участника, соответствующий объект группы обсуждений |
 |lose_group                    | Вышел из группы                            | Соответствующий объект группы                      |
 |lose_group                    | Вышел из группы                            | Соответствующий объект группы                      |
 |lose_discuss                  | Вышел из группы обсуждений                | Соответствующий объект группы обсуждений         |
 |lose_friend                   | Удалён друг                                | Соответствующий объект друга                      |
 |lose_group_member             | Участник вышел из группы                   | Соответствующий объект участника, соответствующий объект группы              |
 |lose_discuss_member           | Участник вышел из группы обсуждений       | Соответствующий объект участника, соответствующий объект группы обсуждений  |
 |group_property_change         | Изменение свойства группы                 | Объект группы, свойство, первоначальное значение, обновлённое значение      |
 |group_member_property_change  | Изменение свойства участника группы       | Объект участника, свойство, первоначальное значение, обновлённое значение    |
 |friend_property_change        | Изменение свойства друга                  | Объект друга, свойство, первоначальное значение, обновлённое значение      |
 |user_property_change          | Изменение свойства аккаунта               | Объект аккаунта, свойство, первоначальное значение, обновлённое значение    |

В Openqq плагине можно указать события, которые будут отправлены через параметр `post_event_list`.По умолчанию используется следующий список событий:

```markdown
default `post_event_list => ['login', 'stop', 'state_change', 'input_qrcode', 'new_group', 'new_friend', 'new_group_member', 'lose_group', 'lose_friend', 'lose_group_member']`

соединение с 127.0.0.1 порт 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "post_type":"event",
    "event":"new_friend",
    "params":[
        {
            "account":"ms-xiaoice",
            "name":"小灰",
            "markname":"",
            "sex":"0",
            "city":"海淀",
            "province":"北京",
            "displayname":"小冰",
            "id":"@75b9db5ae52c87361d1800eaaf307f4d",
            "uid": 123456
        }
    ]
},

соединение с 127.0.0.1 порт 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "post_type":"event",
    "event":"input_qrcode",
    "params":[
        {
            "/tmp/qrcode.jpg", #локальный путь к QR-коду
            "/9j/4AAQSkZJRgABAQAAAQABAAD...UUUUUUUUUUUV/Z\n", #QR-код в виде базовой 64-битной строки
        }
    ]
},

{
    "code": 0,
    "account": "default",
    "log_encoding": null,
    "log_level": "debug",
    "log_path": null,
    "os": "linux",
    "pid": 15497,
    "runtime": 3096,
    "starttime": 1475135588,
    "status": "success",
    "http_debug": "0",
    "version": "1.2.0"
}

{
    "code": 0,
    "account": "default",
    "pid": 15972,
    "runtime": 30,
    "starttime": 1475136637,
    "status": "success, client(15972) будет завершен через 3 секунды"
}