NAV
cURL PHP Go JavaScript

История обновлений

31.10.2025

Добавлена возможность постраничного получения ботов с фильтрацией по названию.

Методы API:

15.10.2025

Добавлена возможность работы с обложкой видеофайла.

Методы API:

Объектные модели:

14.08.2025

Добавлена возможность импортировать пользователей, чаты и переписки.

Методы API:

Объектные модели:

27.03.2025

Добавлена возможность получать список ботов.

Методы API:

Объектные модели:

13.03.2025

Добавлена возможность создания заявки бота.

Методы API:

27.01.2025

В статус пользователя добавлено поле slug.

Объектные модели:

20.01.2025

Добавлены:

Методы API:

Объектные модели:

25.10.2024

В версии v1.0 добавлена возможность отвечать на сообщения.

Методы API:

Объектные модели:

23.10.2024

Добавлена поддержка загрузки файлов через multipart/form-data, и возможность отправки сообщений с загруженными файлами.

Методы API:

Объектные модели:

16.10.2024

Добавлены новые типы значений полей заявки.

Объектные модели:

15.05.2024

Добавлена поддержка закреплённых сообщений.

Методы API:

Webhooks:

Объектные модели:

Быстрый старт

Данное руководство описывает программный интерфейс (далее API) к amo | корпоративный мессенджер (далее amo - мессенджер).

Доступ к API имеют только партнеры amo. Чтобы стать партнером - необходимо авторизоваться под учетной записью amo - мессенджера и пройти регистрацию в кабинете партнера (https://developers.amo.tm)

Шаг 1. Регистрация кабинета партнера.

Для регистрации необходимо:

Перейдем в кабинет партнера

Авторизуемся под учетной записью amo - мессенджера.

img

Заполним форму регистрацию партнера

img

Дождемся одобрения заявки. Как правило, заявка одобряется в течение 3-4 рабочих дней.

img

После одобрения заявки, нам откроется доступ к личному кабинету партнера.

img

В личном кабинете партнера доступно:

Шаг 2. Создание своего первого приложения

Управлять своими приложениями мы можем в разделе "Портал разработчика".

img

Клик на "Новое приложение" чтобы создать наше первое приложение. Введем название приложения и email для информационных рассылок. (Данные можно будет отредактировать)

img

Клик "Создать". Попадаем на экран настроек приложения.

img

Добавим иконку приложения

img

Клик "Сохранить"

img

Переходим в наш аккаунт amo - мессенджера, где вы админ. (https://web.amo.tm)

img

Переходим в раздел "Настройки аккаунта" -> "Интеграции"

img

Видим наше приложение. Установить его не получится, т.к мы не настроили OAuth авторизацию.

img

Шаг 3. Настройка OAuth авторизации

Когда пользователь будет устанавливать наше приложение, система запросит доступ для приложения к определенным ресурсам аккаунта (скопам). После согласия пользователь будет перенаправлен на URL, указанный в Oauth настройках вашего приложения. В параметрах к запросу будет передан код авторизации, который в дальнейшем приложение сможет обменять на Access Token.

Подробнее про Authorization code flow можно почитать по ссылке https://www.oauth.com/oauth2-servers/access-tokens/authorization-code-request/

Для простоты эксперимента воспользуемся сервисом https://webhook.site, чтобы сгенерировать ссылку, куда будет перенаправлен запрос пользователя с кодом авторизации.

img

Копируем ссылку, переходим в настройки вашего приложения, в раздел "Oauth авторизация", вставляем ссылку на редирект и отмечаем любой скоп на ваш вкус. Сейчас это не принципиально. Жмем сохранить.

img

Возвращаемся в амо, и пробуем установить наше приложение

img

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

Видим что нас перенаправило на webhook.site.

img

Возвращаемся на https://webhook.site и видим наш запрос с кодом авторизации.

img

Дальше приложению нужно будет обменять код на access token.

Шаг 4. Обмен кода авторизации на access token

В данном руководстве мы напишем простое PHP приложение, которое обменяет код авторизации на access token и выведет его пользователю. После чего, через 15 секунд, закроет окно авторизации.

Нам потребуется учетная запись на heroku.com

Создаем директорию для нашего приложения

$ mkdir amo-tutorial
$ cd amo-tutorial

Создаем приложение на heroku

$ heroku create


// Creating app... done, ⬢ frozen-cove-98296
// https://frozen-cove-98296.herokuapp.com/ | https://git.heroku.com/frozen-cove-98296.git

Создаем локальный git репозиторий и добавляем репозиторий, который нам создал heroku

git init
git remote add origin https://git.heroku.com/frozen-cove-98296.git

Подключим библиотеку для работы с OAuth https://oauth2-client.thephpleague.com

composer require league/oauth2-client

Папку vendor под игнор

$ echo "vendor" > .gitignore

Создадим файл amo_authorization.php, на который будет перенаправлен пользователь с кодом авторизации. Проинициализируем oauth клиент. clientId, clientSecret нужно взять из настроек нашего приложения

<?php

use League\OAuth2\Client\Provider\GenericProvider;

require_once 'vendor/autoload.php';

$appURL = "https://{$_SERVER['SERVER_NAME']}";

$provider = new GenericProvider([
    'clientId'                 => '2b92db76-9897-11eb-a9d4-00163ef260f3',
    'clientSecret'             => 'DlnECLENlMDe1K5zaPDla8CkCAkEEyZdDZON3sB7K8a87ohMbbSeLwoKVQQ4afMN',
    'redirectUri'              => "{$appURL}/amo_authorization.php",
    'urlAuthorize'             => 'https://id.amo.tm/access',
    'urlAccessToken'           => 'https://id.amo.tm/oauth2/access_token',
    'urlResourceOwnerDetails'  => null
]);

if (!isset($_GET['code'])) {

    exit('Invalid code');

} else {

    try {

        $accessToken = $provider->getAccessToken('authorization_code', [
            'code' => $_GET['code']
        ]);

        echo 'Access Token: ' . $accessToken->getToken() . "<br>";
        echo 'Refresh Token: ' . $accessToken->getRefreshToken() . "<br>";
        echo 'Expired in: ' . $accessToken->getExpires() . "<br>";
        echo 'Already expired? ' . ($accessToken->hasExpired() ? 'expired' : 'not expired') . "<br>";
        echo '<script>setTimeout(function(){window.close()}, 15 * 1000);</script>';

    } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {

        exit($e->getMessage());

    }

}   

Комитим изменения и отправляем в репозиторий heroku.

$ git add . 
$ git commit -m 'initial commit' 
$ git push --set-upstream origin master

Ждем когда задеплоится приложение на heroku.

// remote: https://frozen-cove-98296.herokuapp.com/ deployed to Heroku

Заходим в настройки нашего приложения, раздел Oauth авторизация. Прописываем redirect URL, который нам выдал heroku. Сохраняем.

img

Возвращаемся в амо - мессенджер, удаляем и заново устанавливаем наше приложение. Если все сделали правильно, видим наш access token

img

Шаг 5. Получить контекст access token

В дальнейшей работе с API, помимо токена, нам понадобится информация о том, кто установил нашу интеграцию. Дополним наше PHP приложение, чтобы после получения access token мы сразу узнали user_id, company_id, client_id. Весь код будет выглядеть так:

<?php

use League\OAuth2\Client\Provider\GenericProvider;

require_once 'vendor/autoload.php';

$appURL = "https://{$_SERVER['SERVER_NAME']}";

$provider = new GenericProvider([
    'clientId'                 => '2b92db76-9897-11eb-a9d4-00163ef260f3',
    'clientSecret'             => 'DlnECLENlMDe1K5zaPDla8CkCAkEEyZdDZON3sB7K8a87ohMbbSeLwoKVQQ4afMN',
    'redirectUri'              => "{$appURL}/amo_authorization.php",
    'urlAuthorize'             => 'https://id.amo.tm/access',
    'urlAccessToken'           => 'https://id.amo.tm/oauth2/access_token',
    'urlResourceOwnerDetails'  => null
]);

if (!isset($_GET['code'])) {

    exit('Invalid code');

} else {

    try {

        $accessToken = $provider->getAccessToken('authorization_code', [
            'code' => $_GET['code']
        ]);

        $request = $provider->getAuthenticatedRequest(
            'GET',
            "https://id.amo.tm/oauth2/validate",
            $accessToken,
            [
                'headers' => [
                    'Accept' => 'application/json'
                ],
            ]
        );

        $client = new \GuzzleHttp\Client();
        $response = $client->send($request);
        $responseJson = json_decode($response->getBody());

        echo 'Access Token: ' . $accessToken->getToken() . "<br>";
        echo 'Refresh Token: ' . $accessToken->getRefreshToken() . "<br>";
        echo 'Expired in: ' . $accessToken->getExpires() . "<br>";
        echo 'Already expired? ' . ($accessToken->hasExpired() ? 'expired' : 'not expired') . "<br>";

        echo 'User Id: ' . $responseJson->{'user_uuid'} . "<br>";
        echo 'Company Id: ' . $responseJson->{'company_uuid'} . "<br>";
        echo 'Client Id: ' . $responseJson->{'client_uuid'} . "<br>";
        echo '<script>setTimeout(function(){window.close()}, 15 * 1000);</script>';

    } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {

        exit($e->getMessage());

    }

}

Комитим изменения, пушим в репозиторий Heroku.

$ git add . 
$ git commit -m 'added access token context' 
$ git push --set-upstream origin master

Переустанавливаем наше приложение в амо-мессенджере, теперь, помимо access token, мы получим его контекст, который сможем использовать в дальнейших запросах:

img

Исходный код примера доступен в нашем репозитории на github. (https://github.com/amo-tm/tutorial/tree/bootstrap)

Вы можете развернуть код примера сразу на heroku

Deploy

Что дальше?

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

Либо можете сразу начать изучение доступных методов API.

Туториал

В рамках данного руководства вы научитесь:

Предполагается, что вы уже прошли "Быстрый старт" и обладаете навыками настройки приложения в amo - мессенджер. Все дальнейшие уроки будут основаны на приложении, которое вы создали на "Быстром страте".

Разработка директ-бота

В данном туториале мы разработаем бота, которому можно написать в директ, а он ответит аналогичным сообщением.

Добавим нашей интеграции дополнительные скопы:

img

После изменения скопов, интеграцию нужно переустановить. Переходим в amo - мессенджер, удаляем и переустанавливаем интеграцию

img

Теперь в табе "Команда" нам будет доступен наш Бот.

img

Чтобы принимать сообщения от сутрудников, нам нужно подписать наше приложение на хук о входящем сообщении. Переходим в раздел Webhooks. В качестве webhook URL будем использовать снова https://webhook.site

Добавим ссылку и отметим галочкой событие messages

img

Возвращаемся в amo - мессенджер, пишем боту сообщение. 2 серые галочки в статусе доставки означают, что наш сервер принял хук и ответил 200 кодом.

img

Перейдем на https://webhook.site. Видим хук

img

Теперь доработаем наше приложение, чтобы то принимало хук на входящее сообщение и отправляло ответ.

Создадим новый файл webhook.php и выведем в лог heroku тело запроса.

require_once 'vendor/autoload.php';

$requestBody = file_get_contents('php://input');

file_put_contents("php://stderr", "{$requestBody}\n");

Закомитим правки, запушим. Дождемся сборки

git commit -m 'webhook endpoint'
git push

Пропишем ссылку на вебхук в настройках приложения на портале разработчика

img

Снова напишем боту и посмотрим лог на стороне heroku

img

Отлично. Осталось вызвать метод API на отправку сообщения. Но, для метода нужен токен доступа, который мы получаем в другом сценарии. Нам нужно сохранить токен в постоянное хранилище. Для простоты, будем использовать redis.

Подключим redis к нашему приложению на heroku

// Узнаем имя нашего приложения
$ heroku apps 

// frozen-cove-98296

// Подключим редис к нашему приложению 

$ heroku addons:create heroku-redis:hobby-dev -a frozen-cove-98296

// Дождемся когда развернется дополнение

Добавим компонент predis/predis в менеджер зависимостей

$ composer require predis/predis

Теперь доработаем скрипт, чтобы токен доступа писался в redis.


...

$accessToken = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code']
]);

$redis = new Predis\Client(getenv('REDIS_URL'));
$redis->set("ACCESS_TOKEN", json_encode($accessToken->jsonSerialize()));

...

В скрипте обработки хука вытащим токен из редиса и запишем в лог


...

file_put_contents("php://stderr", "{$requestBody}\n");

$redis = new Predis\Client(getenv('REDIS_URL'));
$accessTokenJson = $redis->get("ACCESS_TOKEN");

file_put_contents("php://stderr", "AccessToken: {$accessTokenJson}\n");

...

Закомитим правки, отправим в heroku и дождемся сборки

$ git add .
$ git commit -m 'store token to redis'
$ git push 

Теперь, переустановим приложение, чтобы токен сохранился в redis, и напишем боту.

img

Видим в логах наш токен.

Доработаем скрипт хука, чтоб тот отправлял в ответ аналогичное сообщение.


...

// Распарсим токен
$accessToken = new \League\OAuth2\Client\Token\AccessToken(
    json_decode($accessTokenJson, true)
);

$message = $parsedBody['_embedded']['message'];
$conversationIdentity = $parsedBody['_embedded']['conversation_identity'];

// Подготовим запрос на ответ
$answerBody = [
];

if ($messageText = $message['text'] ?? null) {
    $answerBody['text'] = $messageText;
}

if ($attachments = $message['attachments'] ?? null) {
    $answerBody['attachments'] = $attachments;
}

// Инициализируем провайдер
$provider = new League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                 => getenv('CLIENT_ID') ?? null,
    'clientSecret'             => getenv('CLIENT_SECRET') ?? null,
    'redirectUri'              => "https://{$_SERVER['SERVER_NAME']}/amo_authorization.php",
    'urlAuthorize'             => 'https://id.amo.tm/access',
    'urlAccessToken'           => 'https://id.amo.tm/oauth2/access_token',
    'urlResourceOwnerDetails'  => null
]);

// Отправим запрос
$answerRequest = $provider->getAuthenticatedRequest(
    'POST',
    "https://api.amo.io/v1.3/direct/{$conversationIdentity['direct_id']}/sendMessage",
    $accessToken,
    [
        'headers' => [
            'content-type' => 'application/json'
        ],
        'body' => json_encode($answerBody)
    ]
);

$client = new \GuzzleHttp\Client();
$response = $client->send($answerRequest);
$responseJson = (string) $response->getBody();

file_put_contents("php://stderr", "Answer response: {$responseJson}\n");

...

Задеплоим

$ git add .
$ git commit -m 'answer'
$ git push 

Возвращаемся в amo - мессенджер и попробуем отправить боту несколько разных сообщений

img

Отлично.

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


...

$answerBody = [
    'reply_to' => [
        'conversation_identity' => $conversationIdentity,
        'msg_id' => $message['id']
    ]
];

...

Пушим, тестим

$ git add .
$ git commit -m 'reply'
$ git push 

img

На этом все.

Исходный код примера можно найти в нашем репозитории на github https://github.com/amo-tm/tutorial/tree/tutorial-1

Или сразу развернуть пример на heroku

Deploy

Встраивание чата в собственный продукт (closed beta)

В данном туториале мы разберем технологию встраивания чата амо в собственный продукт.

Предположим, в вашем продукте есть интерфейс, где вы хотите реализовать функционал мгновенных сообщений. Будь то карточка клиента CRM, или экран задачи в тудушнике.

Общение в амо происходит в рамках "Команды". Поэтому для начала, нам нужно получить доступ к команде или создать новую. В этом туториале мы будем создавать новую команду.

Добавим в проект файл embed_subject.php.

<?php

require_once 'vendor/autoload.php';

?>

Подключим amo PHP sdk


composer require amo-tm/amosdk-php:dev-v1.0.0-BETA

Напишем код, который создаст команду и сохранит ее ID в постоянное хранилище.


$redis = new Predis\Client(getenv('REDIS_URL'));

$clientId = getenv('CLIENT_ID') ?? null;
$clientSecret = getenv('CLIENT_SECRET') ?? null;

$sdk = new AmoClient([
  'clientId' => $clientId,
  'clientSecret' => $clientSecret,
]);

$appScopedSdk = $sdk->withToken($sdk->getApplicationToken(['teams', 'profiles']));

$teamID = $redis->get("T4_TEAM_ID");
if (!$teamID) {
  // Создали команду
  $newTeam = $appScopedSdk->team()->create(new Team([
    'title' => 'testTeamName'
  ]));

  $teamID = $newTeam->getId();
  $redis->set("T4_TEAM_ID", $teamID);
}

Далее для каждого пользователя вашей системы нужно создать профиль в амо. Профиль - это пользователь амо без авторизационных данных. Индентификатор профиля амо нужно будет закрепить за реальным пользователем вашей системы.

Напишем код, который будет создавать профиль и сохранять его идентификатор в постоянное хранилище.

// Для работы с командой нам понадобится токен команды
$teamTokenJson = $redis->get("{$teamID}_TOKEN");
if ($teamTokenJson) {
  $teamToken = new \League\OAuth2\Client\Token\AccessToken(
    json_decode($teamTokenJson, true)
  );
  $teamService = $sdk->withToken($teamToken)->team($teamID);
} else {
// Токена нет в сторе, создадим новый
  $teamService = $appScopedSdk->team($teamID)->scope();
  $redis->set("{$teamID}_TOKEN", json_encode($teamService->getAccessToken()));
}

$profileID = $redis->get("T4_PROFILE_ID");

//
if (!$profileID) {
  // Создали профиль
  $createdProfile = $appScopedSdk->profile()->create(new Profile([
    'name' => 'Tim',
    'email' => 'tim@example.com',
    'external_id' => Uuid::uuid4(),
  ]));

  // Приглашаем профиль в команду
  $invitedUser = $teamService->invite($createdProfile->getId(), new TeamProps([
    'is_admin' => true,
    'position' => 'CEO'
  ]));

  $profileID = $createdProfile->getId();
  $redis->set("T4_PROFILE_ID", $profileID);
}

Общение должно происходить в рамках чата. Мы создали специальный тип группового чата для интеграций - объект обсуждения (subject).

Интеграция может: - создавать сколько угодно объектов обсуждения - приглашать и удалять участников - публиковать сообщения от имени любого участника - встраивать интерфейс чата объекта обсуждения от лица любого участника в свою системы с помощью специального виджета

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

$subjectID = $redis->get("T4_SUBJECT_ID");

if (!$subjectID) {
  $subjectService = $teamService->subject();
  $newSubject = $subjectService->create(new Subject([
    'title' => 'A lead sample subject',
    'external_link' => 'https://example.com/',
    'author' => Participant::user($profileID),
    'participants' => new ParticipantCollection([
      Participant::user($profileID),
    ]),
    'subscribers' => new ParticipantCollection([
      Participant::user($profileID),
    ]),
    'threads' => new SubjectThreadCollection([
      new SubjectThread([
        'title' => 'Patient #100',
        'avatar_url' => 'https://picsum.photos/600'
      ]),
    ]),
    'status' => new SubjectStatusCollection([
      SubjectStatus::status('Unsorted', '#F9F6EE'),
    ])
  ]));

  $subjectID = $newSubject->getId();
  $redis->set("T4_SUBJECT_ID", $subjectID);
}

Мы создали команду, профиль и объект обсуждения. Теперь встроим виджет чата объекта обсуждения в наш интерфейс. Предположим, что в интерфейсе у нас авторизован пользователь, для которого мы создали профиль амо. Будем встраивать виджет от его лица.

Создадим папку embed_subject и структуру файлов для фронта

img

embed_subject/package.json

{
  "name": "embed_subject",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "build": "rimraf dist/* && parcel build src/index.html --public-url /embed_subject/dist"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@amo-tm/wsc": "^1.0.x",
    "parcel": "^2.1.1"
  }
}

embed_subject/src/index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Embed subject demo</title>
</head>
<body>
<script>
  window.AMO_WSC_PARAMS = "%AMO_WSC_PARAMS%";
</script>
<div>
  <h1>Embed subject demo</h1>
  <div id="amo-subject-container" style="width: 700px; height: 800px"></div>
</div>
<script type="module" src="app.js"></script>
</body>
</html>

embed_subject/src/app.js

import { initializeWsc, mountWsc } from '@amo-tm/wsc';

initializeWsc(window.AMO_WSC_PARAMS);
mountWsc({
  container: "#amo-subject-container"
});

Соберем фронт

cd embed_subject
npm install
NODE_ENV=production npm run build

Подключим фронт в наш PHP скрипт

$subjectService = $teamService->subject($subjectID);

$htmlPath = realpath(__DIR__ . '/embed_subject/dist/index.html');
$htmlContent = file_get_contents($htmlPath);

$amoWscParams = [
  'appId' => $clientId,
  'teamId' => $teamID,
  'subjectId' => $subjectID,
  'userId' => $profileID,
  'userToken' => $subjectService->embedUserToken($profileID),
];

$htmlContent = str_replace("\"%AMO_WSC_PARAMS%\"", json_encode($amoWscParams), $htmlContent);

echo $htmlContent;

Пушим проект в heroku, открываем php скрипт https://[your-heroku-app-id].herokuapp.com/embed_subject.php. Должен отобраться iframe с интерфейсом переписки по объекту обсуждения.

img

На этом все.

Исходный код примера можно найти в нашем репозитории на github https://github.com/amo-tm/tutorial/tree/tutorial-4

Или сразу развернуть пример на heroku

Deploy

Методы API

Идентифицировать access token

Пример запроса

$ curl -X GET \
  'http://id.amo.io/oauth2/validate' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' 

В ответ придет структура JSON

{
    "access_token": "9edca18a17dc7fba8bf51d450d98ab38e279d9179d2c4beba4e4a1687530953fa9ed7a4a985e05b3",
    "user_uuid": "866696fa-a37d-11eb-982e-00163e664c4c",
    "client_uuid": "cfc41470-a37e-11eb-ae62-00163e664c4c",
    "company_uuid": "866dd30c-a37d-11eb-a6f5-00163e664c4c",
    "_links": {
        "self": {
            "href": "http://id.dev.amo.io/oauth2/validate"
        }
    }
}

Получить user uuid, client uuid, company uuid, связанные с access token.

HTTP Request

GET http://id.amo.io/oauth2/validate

Query Parameters

Response format

Status Body Description
200 {object} Success
401 {object} Invalid access token

Список пользователей

$ curl -X GET \
  'https://api.amo.io/v1.3/users?user_id[]=ba08130e-3f9b-11ef-b659-02420a0001c3&user_id[]=cb7c1748-e53c-11ee-9818-02420a0001fa' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json'

Ответ придет в следующем JSON'e:

{
  "links": {
    "self": {
      "href": "https://api.amo.io/v1.3/users"
    }
  },
  "_embedded": {
    "items": [
      {
        "links": {
          "self": {
            "href": "https://api.amo.io/v1.3/users/ba08130e-3f9b-11ef-b659-02420a0001c3"
          }
        },
        "id": "ba08130e-3f9b-11ef-b659-02420a0001c3",
        "name": "Client",
        "team_props": {
          "is_admin": true,
          "invited_at": 1720712354000,
          "updated_at": 1720712354000
        }
      },
      {
        "links": {
          "self": {
            "href": "https://api.amo.io/v1.3/users/cb7c1748-e53c-11ee-9818-02420a0001fa"
          }
        },
        "id": "cb7c1748-e53c-11ee-9818-02420a0001fa",
        "name": "Dev",
        "team_props": {
          "position": "Партнер amo",
          "is_admin": true,
          "invited_at": 1720712355000,
          "updated_at": 1721314096000
        }
      }
    ]
  },
  "count": 2
}

Возвращает список пользователей аккаунта

HTTP Request

GET https://api.amo.io/v1.3/users

Query Parameters

Parameter Required Type Description
user_id[] no []string(uuid) Список ID пользователей (до 50 элементов)

Response body

Поле Тип Описание
_embedded.Items []User Пользователи
count int Количество пользователей

Response codes

Код Описание
200 ОК
400 Некорректный формат запроса
401 Невалидный токен авторизации
500 Внутренняя ошибка сервера

Создание нового пользователя

$ curl -X POST \
  'https://api.amo.io/v1.0/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_tokeen}} ' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "John Smith",
        "email": "john@example.com",
        "position": "CEO",
        "phone": "+13251234312"
        "group": "2bae398a-3146-11e9-b210-d663bd873d93"
    }' 

Требуемые права: - Управление структурой компании (company:rw)

Вы можете добавлять новых сотрудников в компанию. Пользователем с таким email будет добавле в вашу компанию, а на его почту придет письмо с приглашением присоединиться.

Query Parameters

Parameter Required Type Description
name yes string (email) Имя сотрудника.
email yes string Email сотрудника.
position no string Должность в компаии
phone yes string Номер телефона сотрудника

Информация о пользователе

$ curl -X GET \
  'https://api.amo.io/v1.0/users/d5326016-a146-11e8-a20e-525400f24f69?hash=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json' \

Ответ придет в следующем JSON'e:

{
    "id": "d5326016-a146-11e8-a20e-525400f24f69",
    "name": "vevseev",
    "email": "vevseev@team.amocrm.com",
    "contact_email": "vevseev@team.amocrm.com",
    "groups": [
        "d5301414-a146-11e8-a516-525400f24f69"
    ],
    "_links": {
        "self": {
            "href": "https://api.amo.io/v1.0/users/d5326016-a146-11e8-a20e-525400f24f69"
        },
         "avatar": {
            "href": "http://sap.amocrm2.saas/v1/user/d5326016-a146-11e8-a20e-525400f24f69/avatar"
        }
    }
}

Возвращает информацию о пользователе {{user_uuid}}

HTTP Request

GET https://api.amo.io/v1.0/users/{{user_uuid}}

Query Parameters

Parameter Required Type Description
hash yes string not yet implemented

Response format

Status Body Description
200 {object} Success, contains user information
200 {object} Failure, problem+json
204 empty User not found

Изменение пользователя

$ curl -X PATCH \
  'https://api.amo.io/v1.0/users/d5326016-a146-11e8-a20e-525400f24f69?hash=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "dont@email.me",
    "phone": "+79604305432",
    "position": "Mascot",
}'

Ответ придет в следующем JSON'e:

{
    "id": "d5326016-a146-11e8-a20e-525400f24f69",
    "name": "vevseev",
    "email": "vevseev@team.amocrm.com",
    "phone": "+79604305432",
    "contact_email": "dont@email.me",
    "_links": {
        "avatar": {
            "href": ""
        }
    }
}

Возвращает информацию о пользователе {{user_uuid}}

user type Description
email string Контактный email
phone string Контактный телефон
position string Должность

HTTP Request

PATCH https://api.amo.io/v1.0/users/{{user_uuid}}

Query Parameters

Parameter Required Type Description
hash yes string not yet implemented

Response format

Status Body Description
200 {object} Success, contains user information
200 {object} Failure, problem+json
204 empty Сhanges are not applied

Деактивация пользователя

$ curl -X DELETE \
  'https://api.amo.io/v1.0/users/d5326016-a146-11e8-a20e-525400f24f69?hash=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json' \

Деактивирует пользователя в аккаунте

HTTP Request

DELETE https://api.amo.io/v1.0/users/{{user_uuid}}

Query Parameters

Parameter Required Type Description
hash yes string not yet implemented

Response format

Status Body Description
200 {object} Success
200 {object} Failure, problem+json
204 empty User already deactivated

Создание объекта

$ curl -X POST \
    https://api.amo.io/v1.0/objects \
    -H 'Authorization: Bearer {{access_token}}' \
    -H 'Content-Type: application/json' \
    -d '{
    "display_name": "Test iframe url",
    "iframe_url": "https://example.com?t=2",
    "participants": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        },
        {
            "type": "access_list",
            "id": "35b612d4-20ae-11e9-92fb-8c859057bdea"
        }
    ],
    "followers": [
        {
            "type": "access_list",
            "id": "35b612d4-20ae-11e9-92fb-8c859057bdea"
        }
    ]
  }' 

IFrame

Значение поля iframe_url используется в клиентских приложения amo для предоставления дополнительной информации по объекту обсуждения. Контент по этой ссылке будет выведен в iframe (web версия) или WebView (мобильная).

Дополнительно к параметрам ссылки будут добавлены:

Параметр Значение
user_id Id пользователя, который просматривает ссылку
account_id Id аккаунта, в котором находится объект обсуждения
expired_at Дата unix когда истекает доступ по ссылке
sig Подпись ссылки.

Подпись формируется из полного URL, отбрасывая только параметр sig. Ключом для подписи является секрет приложения. Алгоритм hmac_sha1.

Например, ссылка https://example.com?account_id=b29273bc-0ca8-11e8-8127-02000a040011&arg=2&expired_at=1546991113&sig=97dded84ac2235afbac5e97ac82eb7c45a4d320a&user_id=b2fb51de-0ca8-11e8-acf6-02000a040011 Отбрасываем sig, получаем https://example.com?account_id=b29273bc-0ca8-11e8-8127-02000a040011&arg=2&expired_at=1546991113&user_id=b2fb51de-0ca8-11e8-acf6-02000a040011, подписываем секретом и сверяем со значением аргумента sig

Далее проверяем дату expired_at. Должна быть больше текущей.

Коды ответа:

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

curl -X POST \
  https://api.amo.io/v1.0/objects/7EbQ41iLrEemlMoyFkFe96g/members \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "members": [{
        "type": "user",
        "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
    }]
}'

Удалить участников

curl -X DELETE \
  https://api.amo.io/v1.0/objects/7EbQ41iLrEemlMoyFkFe96g/members \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "members": [{
        "type": "user",
        "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
    }]
}'

Создание треда

curl -X POST \
 https://api.amo.io/v1.0/objects/{{object_id}}/threads \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -d '[{
      "display_name": "Kevin",
      "profile": {
              "avatar_url": "https://funnyducks.ru/upload/iblock/941/941f5474a6bdb18bc188a7eddabd63b8.jpg",
              "source": {
                    "id": "123321",
                    "display_name": "Kevin",
                    "icon_url": "https://funnyducks.ru/upload/iblock/941/941f5474a6bdb18bc188a7eddabd63b8.jpg"
                        }
               }
       }]'

Удалить тред

curl -X DELETE \
 https://api.amo.io/v1.0/objects/{{object_id}}/threads \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -d '[
      "9472061b-be2d-11eb-ab1c-02420a000088"
]'

Добавить подписчиков

curl -X POST \
  https://api.amo.io/v1.0/objects/7EbQ41iLrEemlMoyFkFe96g/followers \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "followers": [{
        "type": "user",
        "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
    }]
}'

Удалить подписчиков

curl -X DELETE \
  https://api.amo.io/v1.0/objects/7EbQ41iLrEemlMoyFkFe96g/followers \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "followers": [{
        "type": "user",
        "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
    }]
}'

Информация по объекту

$ curl -X GET \
  https://api.amo.io/v1.0/objects/{{object_id}} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' 

Ответ придет в следующем JSON'e:

{
  "id": "9c4a62bd-c203-11eb-8ee2-02420a0000bf",
  "display_name": "test_object",
  "iframe_url": "https://example.com?t=2",
  "participants": [
    {
      "type": "user",
      "id": "e8d122a4-bd42-11eb-9927-00163e664c44"
    }
  ],
  "threads": [
    {
      "id": "b1c05739-c20d-11eb-8d74-02420a0000b8",
      "display_name": "nikola"
    },
    {
      "id": "ba948325-c20d-11eb-8d74-02420a0000b8",
      "display_name": "kolya"
    }
  ],
  "_links": {
      "self": {
           "href": "https://api.amo.io/v1.0/objects/9c4a62bd-c203-11eb-8ee2-02420a0000bf"
    }
  }
}

Получить участников, тредов, id и имя объекта.

HTTP Request

GET https://api.amo.io/v1.0/objects/{{object_id}}

Query Parameters

Response format

Status Body Description
200 {object} Success, contains dialog information
401 {object} Failure, access token is invalid
404 empty Object not found

Информация о треде

$ curl -X GET \
  'https://api.amo.io/v1.0/objects/b3f64fbb-ba60-11e8-8b9f-1c872c5f1719/threads/b3f64fd2-ba60-11e8-8b9f-1c872c5f1719?hash=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json' \

Ответ придет в следующем JSON'e:

{
    "id": "b3f64fd2-ba60-11e8-8b9f-1c872c5f1719",
    "avatar": "",
    "deleted": false,
    "name": "Филипп Гордон",
    "_links": {
        "self": {
            "href": "https://api.amo.io/v1.0/threads/b3f64fd2-ba60-11e8-8b9f-1c872c5f1719?hash="
        }
    }
}

Возвращает информацию о треде {{thread_id}} по диалогу {{object_uuid}}

HTTP Request

GET https://api.amo.io/v1.0/objects/{{object_id}}/threads/{{thread_id}}

Query Parameters

Parameter Required Type Description
hash yes string not yet implemented

Response format

Status Body Description
200 {object} Success, contains thread information
200 {object} Failure, problem+json

Списки доступа

Если система прав на стороне вашего приложения заставляет массово обновлять участников или подписчиков объектов, можете воспользоваться списками доступа AccessList.

Данный механизм позволяет вам объединять пользователей / группы пользователей в 1 список и указывать его в качестве участника или подписчика объекта.

Создание списка доступа

Запрос на создание списка

$ curl -X POST \
     https://api.amo.io/v1.0/access_lists \
    -H 'Authorization: Bearer {{access_token}}' \
    -H 'Content-Type: application/json' \
    -d '{
    "participants": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        },
        {
            "type": "group",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        }
    ]
  }'' 

Ответ

{
    "id": "35b612d4-20ae-11e9-92fb-8c859057bdea"
}

Просмотр списка доступа

Запрос на получение списка

$ curl -X GET \
    https://api.amo.io/v1.0/access_lists/35b612d4-20ae-11e9-92fb-8c859057bdea \
    -H 'Authorization: Bearer {{access_token}}' \
    -H 'Content-Type: application/json' 

Ответ

{
    "id": "35b612d4-20ae-11e9-92fb-8c859057bdea",
    "participants": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        },
        {
            "type": "group",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        }
    ]
}

Изменение участников в списке доступа

Запрос на изменение списка участников


$ curl -X PATCH \
    https://api.amo.io/v1.0/access_lists/35b612d4-20ae-11e9-92fb-8c859057bdea/participants \
    -H 'Content-Type: application/json' \
    -d '{
    "remove": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        }
    ],
    "add": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        },
        {
            "type": "group",
            "id": "6ecd6e42-0ca9-11e8-90b7-02000a040011"
        }
    ]
  }'

Замена участников в списке доступа

Запрос на замену списка участников


$ curl -X PUT \
   https://api.amo.io/v1.0/access_lists/35b612d4-20ae-11e9-92fb-8c859057bdea/participants \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImZkNzc1NTBkYTk0ZTBmZDY0NzNlZThhMzcwYzA1YTYwZDEzMmM4MDVlYTkzN2E5NTdlNWVkNTQyYzY2OWNmOGY1ODhiN2E2OTdiYzI2ZGY2In0.eyJhdWQiOiI1NzgzZWIzMi02NGVmLTExZTgtODFhYy0wMjQyMGEwYzAwMDQiLCJqdGkiOiJmZDc3NTUwZGE5NGUwZmQ2NDczZWU4YTM3MGMwNWE2MGQxMzJjODA1ZWE5MzdhOTU3ZTVlZDU0MmM2NjljZjhmNTg4YjdhNjk3YmMyNmRmNiIsImlhdCI6MTU0ODQzNjkwMiwibmJmIjoxNTQ4NDM2OTAyLCJleHAiOjE1NDg1MjMzMDIsInN1YiI6ImIyZmI1MWRlLTBjYTgtMTFlOC1hY2Y2LTAyMDAwYTA0MDAxMSIsInNjb3BlcyI6W10sInNhcCI6dHJ1ZX0.hLqPhdozrdOz1jMALo5PusGNq70bJdQf2BT7D3vX-0lh7o8lsvPe4L4ucm8vS4vdyjc3qoovtHpHoUC1XhPmp5sYOxasHAiTq2SsqcG6LKf13x1Wvfudpg3KeZjijUonvFmqbIoqIfFeRbUaR9bCZSbB2iyFI2nTUm_MO3J-16Mp7IVnQYcLFd2ZNifx1EXyqfDIukA1TSdQVGPosANyulI-PcZYSa0brNMKQuXYED4dfQ0wUHYYq-4A4bysxViM_Oml-cOjHphhZcThJXoGdf4DLbEpGCthSguMQ_oJkBhqLEcyvbUK5Lb4H6oUuf5UIISFsWk7Lz3JRq0Q4U9S6g' \
   -H 'Content-Type: application/json' \
   -d '{
    "participants": [
        {
            "type": "user",
            "id": "b2fb51de-0ca8-11e8-acf6-02000a040011"
        }
    ]
 }' 

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

Сообщения можно отправлять в:

Отправка сообщения в директ

Отправка текста

curl --location --request POST 'https://api.amo.io/v1.3/direct/{USER_ID}/sendMessage' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "hello"
}'

Отправка изображения

curl --location --request POST 'https://api.amo.io/v1.3/direct/{USER_ID}/sendMessage' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "attachments": [
        {
            "type": "photo",
            "photo": {
                "filename": "ariplane.png",
                "link": "https://homepages.cae.wisc.edu/~ece533/images/airplane.png"
            }
        }
    ]
}'

Отправка сообщения с ранее загруженным файлом

curl --location --request POST 'https://api.amo.io/v1.3/direct/{USER_ID}/sendMessage' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "attachments":[
        {
            "file_id": "8e97fddd-8c8f-11ef-a286-089df4ec9762"
        }
    ]
}'

Отправка сообщения в объект

curl -X POST 'https://api.amo.io/v1.0/objects/{OBJECT_ID}/messages' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
    "to": {
         "type": "all"
    },
    "from": {
         "type": "user",
         "id": "866696fa-a37d-11eb-982e-00163e664c4c"
    },
    "refer_to": {
        "id": "5303654e-92b7-11ef-b1b0-02420a000054"
    },
    "message": {
         "text": "Hello everyone"
    }
}' 

Пример тела запроса при отправке сообщения от лица треда в объект

{
  "to": {
    "id": "866696fa-a37d-11eb-982e-00163e664c4c",
    "type": "user"
  },
  "from": {
    "type": "thread",
    "id": "9996a615-be28-11eb-ab1c-02420a000088"
  },
  "refer_to": {
    "id": "5303654e-92b7-11ef-b1b0-02420a000054"
  },
  "message": {
    "text": "hello to user from thread"
  }
}

В ответ придет структура с id сообщения:

{
    "message_id": "8f2d05e9-09f5-11e9-8fef-1c872c5f1719"
}

HTTP Request

Request: POST https://api.amo.io/v1.3/direct/{USER_ID}/sendMessage

Content-Type: application/json

Body: Message

Response

Content-Type: application/json

Body:

Поле Тип Описание
msg_id string (uuid) Идентификатор сообщения

Возможные ошибки

Status Type Description
403 https://developers.amo.tm/docs/handle-errors/#file-access-forbidden Использование файла запрещено
404 https://developers.amo.tm/docs/handle-errors/#file-not-found Не найден id ранее загруженного файла

Отправка сообщения в канал

Request: POST https://api.amo.io/v1.3/channels/{CHANNEL_ID}/sendMessage

Content-Type: application/json

Body: Message

Response

Content-Type: application/json

Body:

Поле Тип Описание
msg_id string (uuid) Идентификатор сообщения

Возможные ошибки

Status Type Description
403 https://developers.amo.tm/docs/handle-errors/#file-access-forbidden Использование файла запрещено
404 https://developers.amo.tm/docs/handle-errors/#file-not-found Не найден id ранее загруженного файла

Отправка сообщения в объект

Request: POST https://api.amo.io/v1.0/objects/{object_id}/messages

Content-Type: application/json

Body Message v1.0

Response

Content-Type: application/json

Body:

Поле Тип Описание
message_id string (uuid) Идентификатор сообщения

Возможные ошибки

Status Type Description
404 https://developers.amo.io/docs/rest-api/using-rest-api/error-handling#404 Не найден id сообщения для ответа

Список сообщений

$ curl -X GET \
  'https://api.amo.io/v1.0/objects/7s_ZPu7pgEeiLnxyHLF8XGQ/messages?after_id=&before_id=&limit=1&hash=' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \

Ответ придет в следующем JSON'e:

{
    "_embedded": {
        "messages": [
            {
                "id": "07cd92f9-18b0-11e9-823e-1c872c5f1719",
                "client_id": "",
                "date": 1547547993573,
                "from": {
                    "id": "b681548e-0ca8-11e8-a062-02000a040011",
                    "type": "user"
                },
                "to": {
                    "id": "636bb624-11a6-11e8-af62-02000a040011",
                    "type": "group"
                },
                "regular": {
                    "message": "",
                    "media": {
                        "photo": {
                            "thumbs": {
                                "128": {
                                    "w": 128,
                                    "h": 128,
                                    "file_name": "bepatient",
                                    "file_id": "fe74e3d2-18af-11e9-823e-1c872c5f1719",
                                    "mime_type": "image/jpeg",
                                    "dc_id": 1,
                                    "access_hash": "be6ba9d8f0daa082",
                                    "size": 5859,
                                    "_links": {
                                        "self": {
                                            "href": "https://api.amo.io/v1.0/files/1/fe74e3d2-18af-11e9-823e-1c872c5f1719?hash=be6ba9d8f0daa082"
                                        }
                                    }
                                },
                                "256": {
                                    "w": 256,
                                    "h": 256,
                                    "file_name": "bepatient",
                                    "file_id": "fe6dcbd3-18af-11e9-823e-1c872c5f1719",
                                    "mime_type": "image/jpeg",
                                    "dc_id": 1,
                                    "access_hash": "38aacd1ddfcbc16c",
                                    "size": 16107,
                                    "_links": {
                                        "self": {
                                            "href": "https://api.amo.io/v1.0/files/1/fe6dcbd3-18af-11e9-823e-1c872c5f1719?hash=38aacd1ddfcbc16c"
                                        }
                                    }
                                },
                                "1024": {
                                    "w": 1024,
                                    "h": 1024,
                                    "file_name": "bepatient",
                                    "file_id": "fe634fd7-18af-11e9-823e-1c872c5f1719",
                                    "mime_type": "image/jpeg",
                                    "dc_id": 1,
                                    "access_hash": "77bf43d90e08c0d2",
                                    "size": 138230,
                                    "_links": {
                                        "self": {
                                            "href": "https://api.amo.io/v1.0/files/1/fe634fd7-18af-11e9-823e-1c872c5f1719?hash=77bf43d90e08c0d2"
                                        }
                                    }
                                }
                            },
                            "w": 2048,
                            "h": 2048,
                            "file_name": "bepatient",
                            "file_id": "fdcc4d37-18af-11e9-823e-1c872c5f1719",
                            "mime_type": "image/jpeg",
                            "dc_id": 1,
                            "access_hash": "31f356c94b81da0b",
                            "size": 406853,
                            "_links": {
                                "self": {
                                    "href": "https://api.amo.io/v1.0/files/1/fdcc4d37-18af-11e9-823e-1c872c5f1719?hash=31f356c94b81da0b"
                                }
                            }
                        }
                    }
                }
            },
            {
                "id": "55ba81eb-18af-11e9-969d-1c872c5f1719",
                "client_id": "",
                "date": 1547547694814,
                "from": {
                    "id": "b681548e-0ca8-11e8-a062-02000a040011",
                    "type": "user"
                },
                "to": {
                    "id": "636bb624-11a6-11e8-af62-02000a040011",
                    "type": "group"
                },
                "regular": {
                    "message": "",
                    "media": {
                        "document": {
                            "thumb": {
                                "w": 0,
                                "h": 0,
                                "file_id": ""
                            },
                            "file_name": "ru",
                            "file_id": "5f3d6ea8-18a0-11e9-a57f-1c872c5f1719",
                            "mime_type": "text/html",
                            "dc_id": 1,
                            "access_hash": "951d6af928a81e10",
                            "size": 85933,
                            "_links": {
                                "self": {
                                    "href": "https://api.amo.io/v1.0/files/1/5f3d6ea8-18a0-11e9-a57f-1c872c5f1719?hash=951d6af928a81e10"
                                }
                            }
                        }
                    }
                }
            },
            {
                "id": "1f5c58ea-18af-11e9-969d-1c872c5f1719",
                "client_id": "",
                "date": 1547547603599,
                "from": {
                    "id": "b681548e-0ca8-11e8-a062-02000a040011",
                    "type": "user"
                },
                "to": {
                    "id": "636bb624-11a6-11e8-af62-02000a040011",
                    "type": "group"
                },
                "regular": {
                    "message": "Sample Text"
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://api.amo.io/v1.0/objects/7s_ZPu7pgEeiLnxyHLF8XGQ/messages?after_id=&before_id=&limit=3&hash="
        },
        "next": {
            "href": "https://api.amo.io/v1.0/objects/7s_ZPu7pgEeiLnxyHLF8XGQ/messages?after_id=07cd92f9-18b0-11e9-823e-1c872c5f1719&limit=3&hash="
        },
        "prev": {
            "href": "https://api.amo.io/v1.0/objects/7s_ZPu7pgEeiLnxyHLF8XGQ/messages?&before_id=1f5c58ea-18af-11e9-969d-1c872c5f1719&limit=3&hash="
        }
    }
}

Возвращает участников и сообщения из объекта.

HTTP Request

GET https://api.amo.io/v1.0/objects/{{object_uuid}}/messages

Query Parameters

Parameter Required Type Description
after_id no string uuid of message
before_id no string uuid of message
limit no int limit messege in responce, max=50
hash yes string not yet implemented

Response format

Status Body Description
200 {object} Success, contains messages information
200 {object} Failure, problem+json
204 empty User not found

Информацию по файлу

$ curl -X GET \
  'https://api.amo.tm/v1.0/files/1/62269742-f6ee-11e8-ac2d-1c872c5f1719?hash=bbf631a9cdfd3501' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{access_token}} ' \
  -H 'Content-Type: application/json' \
  -H 'X-Account-ID: d52d175a-a146-11e8-a21d-525400f24f69' \

Получает информацию на файл, включая ссылку.

Ответ придет в следующем JSON'e:

{
    "file_id": "62269742-f6ee-11e8-ac2d-1c872c5f1719",
    "dc_id": 1,
    "access_hash": "bbf631a9cdfd3501",
    "url": "https://api.amo.tm/storage/62269742-f6ee-11e8-ac2d-1c872c5f1719.jpg?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDM4NDAwMDYsImlzcyI6IjYyMjY5NzQyLWY2ZWUtMTFlOC1hYzJkLTFjODcyYzVmMTcxOS5qcGcifQ.v4qAk60BWSqKBPLsEMBJ0Z7dGPc21sLW24t5_NOeYnk",
    "_links": {
        "self": {
            "href": "https://api.amo.tm/v1.0/files/1/62269742-f6ee-11e8-ac2d-1c872c5f1719&hash=bbf631a9cdfd3501"
        }
    }
}

HTTP Request

GET https://api.amo.io/v1.0/files/1/{{file_id}}

Query Parameters

Parameter Required Type Description
hash yes string Тут hash - это секрет файла

Response format

Status Body Description
200 {object} Success, contains file information
200 {object} Failure, problem+json
204 empty File not found

Загрузка файла

$ curl -X POST 'https://api.amo.tm/v1.3/files/upload' \
  --header 'Authorization: Bearer {{access_token}}' \
  --form 'filename="MY FILENAME"' \
  --form 'file=@"/my_image.jpg"'

Загружает файл через multipart/form-data, возвращая id загруженного файла.

Ответ придет в следующем JSON'e:

{
    "file_id": "62269742-f6ee-11e8-ac2d-1c872c5f1719"
}

Request: POST https://api.amo.tm/v1.3/files/upload

Content-Type: multipart/form-data

Body:

Поле Обязательно Тип Описание
file Да file object Загружаемый файл
filename Нет string Название файла
preview_image Нет file_object Обложка для видео

Response

Content-Type: application/json

Body:

Поле Тип Описание
file_id string id загруженного файла

Codes:

Код Тип (опционально) Описание
200 - OK
400 https://developers.amo.tm/docs/handle-errors/#file-too-large Файл превышает максимально допустимый размер
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
400 https://developers.amo.tm/docs/handle-errors/#validation-error Некорректный запрос
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Отправка сообщения от имени бота

Пока управление передано виджету, приложение может публиковать сообщения в чат заявки от мени бота

curl --POST 'https://api.amo.tm/v1.3/bots/<bot_id>/request/<request_id>/sendMessage' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "text",
    "receiver": {
        "user_id": "<id получателя>"
    },
    "reply_markup": {
        "inline_keyboard": {
            "buttons": [
                {
                    "text": "OK"
                },
                {
                    "text": "Continue"
                }
            ]
        }
    }
}'

HTTP Request

Request: POST https://api.amo.io/v1.3/bots/{BOT_ID}/request/{REQUEST_ID}/sendMessage

Body Message

Информации о заявке

Запрос на получение информации о заявке

$ curl -X GET \
  'https://api.amo.tm/v1.3/bots/<bot_id>/request/<request_id>' \
  --header 'Authorization: Bearer <access toke>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \

Ответ придет в виде JSON:

{
    "links": {
        "self": {
            "href": "https://api.amo.io/v1.3/bots/e907aa79-a1d6-11eb-98cb-0242c0a80412/request/f85879ff-7af9-4ec2-9663-8d1d5fd7f314"
        }
    },
    "_embedded": {
        "fields": [
            {
                "id": "b58b2cd0-a1e2-11eb-b1ee-0123456789ab",
                "type": 1,
                "title": "Строка"
            },
            {
                "id": "b8523c10-a1e2-11eb-b1ee-0123456789ab",
                "type": 3,
                "title": "Список",
                "enums": [
                    {
                        "id": "bc4aed80-a1e2-11eb-b1ee-0123456789ab",
                        "title": "Значение 1"
                    },
                    {
                        "id": "bc4aed81-a1e2-11eb-b1ee-0123456789ab",
                        "title": "Значение 2"
                    }
                ]
            }
        ],
        "statuses": [
            {
                "id": "dd12eb50-a1d6-11eb-80ea-0123456789ab",
                "title": "Создано",
                "color": "#768896"
            },
            {
                "id": "dd12eb51-a1d6-11eb-80ea-0123456789ab",
                "title": "Подтвержденo",
                "color": "#DEAD18"
            }
        ]
    },
    "id": "f85879ff-7af9-4ec2-9663-8d1d5fd7f314",
    "status_id": "dd12eb50-a1d6-11eb-80ea-0123456789ab",
    "title": "Новый бот",
    "author_id": "2a1623e2-36fa-11eb-b92e-00163ef260f3",
    "field_values": {
        "b58b2cd0-a1e2-11eb-b1ee-0123456789ab": {
            "string": "Обычный текст"
        },
        "b8523c10-a1e2-11eb-b1ee-0123456789ab": {
            "enum_id": [
                "bc4aed81-a1e2-11eb-b1ee-0123456789ab"
            ]
        }
    },
    "created_at": 1618928089320,
    "updated_at": 1618928106438,
    "seq_id": "22",
    "responsible_id": "2a1623e2-36fa-11eb-b92e-00163ef260f3",
    "responsible":{
      "user_id":"2a1623e2-36fa-11eb-b92e-00163ef260f3"
    },
    "bot_id": "e907aa79-a1d6-11eb-98cb-0242c0a80412",
    "prototype_id": "dd118bc0-a1d6-11eb-80ea-0123456789ab"
}

HTTP Request

Request: GET https://api.amo.io/v1.3/bots/{BOT_ID}/request/{REQUEST_ID}

Response

Content-Type: application/json

Body Request

Поле Тип Описание
_embedded.Fields []RequestField Поля заявки
_embedded.Statuses []RequestStatus Статусы заявки

Создание заявки

Приложение может создать новую заявку с возможностью передачи значений полей

curl --location 'https://api.amo.io/v1.3/bots/{BOT_ID}/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access token>' \
--data '{
    "user_id": "e0122386-7683-11ef-a77c-02420a00013b",
    "field_values": {
        "9c0e7090-fb67-11ef-8192-0123456789ab": {
            "string": "STR field val"
        },
        "a098b3a0-fb67-11ef-8192-0123456789ab": {
            "string": "TEXT field val"
        },
        "abb083d0-fb67-11ef-8192-0123456789ab": {
            "enum_id": [
                "a5931da2-fb67-11ef-8192-0123456789ab"
            ]
        },
        "b639cfa0-fb67-11ef-8192-0123456789ab": {
            "enum_id": [
                "ae07e150-fb67-11ef-8192-0123456789ab",
                "ae07e152-fb67-11ef-8192-0123456789ab"
            ]
        },
        "b9e6f920-fb67-11ef-8192-0123456789ab": {
            "date": "2006-01-02"
        },
        "c0e34da0-fb67-11ef-8192-0123456789ab": { 
            "date_range": ["2006-01-02", "2019-01-02"]
        },
        "c597d500-fb67-11ef-8192-0123456789ab": {
            "int": 3321
        },
        "cc16e330-fb67-11ef-8192-0123456789ab": {
            "float": 100.213
        },
        "d1a8d240-fb67-11ef-8192-0123456789ab": {
            "currency": {
                "value": 1201,
                "currency": 2
            }
        },
        "de927c40-fb67-11ef-8192-0123456789ab": {
            "enum_id": [
                "9d390fe6-a647-11ee-9694-02420a000142"
            ]
        },
        "e3ff7e30-fb67-11ef-8192-0123456789ab": {
            "int": 432113245
        }
    }
}'

HTTP Request

Request: POST https://api.amo.io/v1.3/bots/{BOT_ID}/run

Content-Type: application/json

Body:

Тип: object

Поле Тип Описание
external_id string Внешний id заявки
user_id string Автор заявки
field_values map[string]RequestFieldValue Значение полей заявки

Response

Content-Type: application/json

Body: Request

Возможные ошибки

Status Type Description
422 https://developers.amo.tm/docs/handle-errors/#validation-error Ошибка валидации запроса

Редактирование заявки

Приложение может редактировать поля заявки, пока передано управление.

$ curl --PUT 'https://api.amo.tm/v1.3/bots/<bot_id>/request/<request_id>' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "field_values": {
        "<field_id>": {
            "string": "Строковое значение поля"
        }
    }
}'

Request: PUT https://api.amo.io/v1.3/bots/{BOT_ID}/request/{REQUEST_ID}

Content-Type: application/json

Body: map[string]RequestFieldValue

Возврат управления

После завершения работы виджета, приложение должно вернуть управление

curl --POST  'https://api.amo.tm/v1.3/bots/<bot_id>/request/<request_id>/returnControl' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "return_code": "success"
}'

Request: POST https://api.amo.io/v1.3/bots/{BOT_ID}/request/{REQUEST_ID}/returnControl

Content-Type: application/json

Body:

Поле Тип Описание
return_code string Код возврата

Создание команды (закрытая бета)

use \Amo\Sdk\AmoClient;
use \Amo\Sdk\Models\Team;

$sdk = new AmoClient([
  'clientID' => 'your_client_id',
  'clientSecret' => 'your_client_secret',
]);

$appScopedSdk = $sdk->withToken($sdk->getApplicationToken(['teams', 'profiles']))
$newTeam = $appScopedSdk->team()->create(new Team([
  'title' => 'testTeamName'
]))

print "team created with id " . $newTeam->getId();

HTTP Request

Request: POST https://api.amo.io/v1.3/teams

Content-Type: application/json

Body: Team

Response

Content-Type: application/hal+json

Body: TeamCreateResponse

Создание профиля (закрытая бета)

use \Amo\Sdk\AmoClient;
use \Amo\Sdk\Models\Team;

$sdk = new AmoClient([
  'clientID' => 'your_client_id',
  'clientSecret' => 'your_client_secret',
]);

$appScopedSdk = $sdk->withToken($sdk->getApplicationToken(['teams', 'profiles']))
$createdProfile = $appScopedSdk->profile()->create(new Profile([
  'name' => 'Tim',
  'email' => 'tim@domain.com',
  'external_id' => '7688d6ac-57a1-421e-ac41-a68205d96d4e'
]));

print "profile created with id " . $createdTeam->getId();

HTTP Request

Request: POST https://api.amo.io/v1.3/profiles

Content-Type: application/json

Body: Profile

Response

Content-Type: application/hal+json

Body: ProfileCreateResponse

Закрепление сообщения

Закрепление сообщения в директ-чате

curl -X POST 'https://api.amo.io/v1.3/direct/{USER_ID}/pins' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "message_id": "{MESSAGE_ID}"
}'

Закрепление сообщения в канале

curl -X POST 'https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "message_id": "{MESSAGE_ID}"
}'

Ответ

{
   "_embedded":{
      "message":{
         "id":"a91d0d1e-fb48-11ee-a30d-02420a000013",
         "author":{
            "bot_id":"2f82c26e-e53d-11ee-a2e4-02420a0001fa"
         },
         "text":"3",
         "created_at":1713199998853,
         "updated_at":1715850687042,
         "pin":true
      }
   },
   "message_id":"a91d0d1e-fb48-11ee-a30d-02420a000013",
   "pinned_by":{
      "bot_id":"2f82c26e-e53d-11ee-a2e4-02420a0001fa"
   },
   "created_at":1715850687042
}

Закреплённое сообщение — сообщение, прикреплённое к верхней части чата и всегда находящееся на виду у пользователя.
При закреплении сообщения отправляется системное сообщение username закрепил сообщение "...".
Сообщение закрепляется для всех участников чата.
Любой участник чата может закрепить сообщение.
Нельзя закрепить удалённое или системное сообщение.

img

Сообщения можно закреплять с помощью методов API в:

Закрепление сообщения в директ-чате

Request: POST https://api.amo.io/v1.3/direct/{USER_ID}/pins

Content-Type: application/json

Body:

Поле Тип Описание
message_id string (uuid) ID сообщения

Response

Content-Type: application/json

Body: MessagePin

Codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Закрепление сообщения в канале

Request: POST https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins

Content-Type: application/json

Body:

Поле Тип Описание
message_id string (uuid) ID сообщения

Response

Content-Type: application/json

Body: MessagePin

Codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Открепление сообщения

При откреплении сообщения отправляется системное сообщение username открепил сообщение "...".
Сообщение открепляется для всех участников чата.
Любой участник чата может открепить сообщение.
При удалении сообщения оно автоматически открепляется.

Сообщения можно откреплять с помощью методов API в:

Открепление сообщения в директ-чате

curl -X POST 'https://api.amo.io/v1.3/direct/{USER_ID}/pins/remove' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "message_id": "{MESSAGE_ID}"
}'

Открепление сообщения в канале

curl -X POST 'https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins/remove' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "message_id": "{MESSAGE_ID}"
}'

Открепление сообщения в директ-чате

Request: POST https://api.amo.io/v1.3/direct/{USER_ID}/pins/remove

Content-Type: application/json

Body:

Поле Тип Описание
message_id string (uuid) ID сообщения

Response codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Открепление сообщения в канале

Request: POST https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins/remove

Content-Type: application/json

Body:

Поле Тип Описание
message_id string (uuid) ID сообщения

Response codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Список закреплённых сообщений

Список закреплённых сообщений в директ-чате

curl -X GET 'https://api.amo.io/v1.3/direct/{USER_ID}/pins' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'

Список закреплённых сообщений в канале

curl -X GET 'https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'

Ответ

{
   "items":[
      {
         "_embedded":{
            "message":{
               "id":"14ae5d31-0b7c-11ef-979e-02420a0000d3",
               "author":{
                  "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
               },
               "receiver":{
                  "bot_id":"2f82c26e-e53d-11ee-a2e4-02420a0001fa"
               },
               "text":"?",
               "created_at":1714981302259,
               "updated_at":1714981369664,
               "pin":true
            }
         },
         "message_id":"14ae5d31-0b7c-11ef-979e-02420a0000d3",
         "pinned_by":{
            "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
         },
         "created_at":1714981369657
      },
      {
         "_embedded":{
            "message":{
               "id":"a91d0d1e-fb48-11ee-a30d-02420a000013",
               "author":{
                  "bot_id":"2f82c26e-e53d-11ee-a2e4-02420a0001fa"
               },
               "text":"3",
               "created_at":1713199998853,
               "updated_at":1715850687042,
               "pin":true
            }
         },
         "message_id":"a91d0d1e-fb48-11ee-a30d-02420a000013",
         "pinned_by":{
            "bot_id":"2f82c26e-e53d-11ee-a2e4-02420a0001fa"
         },
         "created_at":1715850687042
      }
   ],
   "pagination":{
      "next_cursor":"eyJMYXN0TWVzc2FnZUlkIjoiYTkxZDBkMWUtZmI0OC0xMWVlLWEzMGQtMDI0MjBhMDAwMDEzIn0="
   }
}

Список закреплённых сообщений в директ-чате

Request: GET https://api.amo.io/v1.3/direct/{USER_ID}/pins

Content-Type: application/json

Query parameters:

Параметр Обязательный Тип Описание
cursor нет string Параметр для получения следующей страницы сообщений. Отсутствует при запросе первой страницы
limit нет int Ограничение количества возвращаемых сообщений (максимум 25)

Response

Content-Type: application/json

Body:

Поле Тип Описание
items []MessagePin Список закреплённых сообщений
pagination Pagination Состояние пагинации

Codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Список закреплённых сообщений в канале

Request: GET https://api.amo.io/v1.3/channels/{CHANNEL_ID}/pins

Content-Type: application/json

Query parameters:

Параметр Обязательный Тип Описание
cursor нет string Параметр для получения следующей страницы сообщений. Отсутствует при запросе первой страницы
limit нет int Ограничение количества возвращаемых сообщений (максимум 25)

Response

Content-Type: application/json

Body:

Поле Тип Описание
items []MessagePin Список закреплённых сообщений
pagination Pagination Состояние пагинации

Codes:

Код Описание
200 OK
401 Невалидный токен авторизации
403 Действие запрещено (нет разрешения)
500 Внутренняя ошибка сервера

Получение списка ботов

$ curl --location 'https://api.amo.io/v1.3/bots?query=%D0%97%D0%B0%D1%8F%D0%B2%D0%BA%D0%B0\u0026limit=2\u0026page_token=eyJwcm90b3R5cGVfaWRfZ3QiOiJhZTI3ZGJmMC1iNDIwLTExZjAtYjNlMS0wMjQyMGEwMDAxMTQifQ%3D%3D' \
--header 'Authorization: ••••••'

Ответ придет в следующем JSON'e:

{
  "links": {
    "first": {
      "href": "https://api.amo.io/v1.3/bots?query=%D0%97%D0%B0%D1%8F%D0%B2%D0%BA%D0%B0\u0026limit=2"
    },
    "next": {
      "href": "https://api.amo.io/v1.3/bots?query=%D0%97%D0%B0%D1%8F%D0%B2%D0%BA%D0%B0\u0026limit=2\u0026page_token=eyJwcm90b3R5cGVfaWRfZ3QiOiJkYzI4M2FjMS1iNDFlLTExZjAtYjNlMS0wMjQyMGEwMDAxMTQifQ%3D%3D"
    },
    "self": {
      "href": "https://api.amo.io/v1.3/bots?query=%D0%97%D0%B0%D1%8F%D0%B2%D0%BA%D0%B0\u0026limit=2\u0026page_token=eyJwcm90b3R5cGVfaWRfZ3QiOiJhZTI3ZGJmMC1iNDIwLTExZjAtYjNlMS0wMjQyMGEwMDAxMTQifQ%3D%3D"
    }
  },
  "_embedded": {
    "items": [
      {
        "links": {
          "run": {
            "href": "https://api.amo.io/v1.3/rpa/bots/b1ea5d32-b41e-11f0-b3e1-02420a000114/run",
            "method": "POST"
          },
          "self": {
            "href": "https://api.amo.io/v1.3/rpa/bots/b1ea5d32-b41e-11f0-b3e1-02420a000114"
          }
        },
        "id": "b1ea5d32-b41e-11f0-b3e1-02420a000114",
        "title": "Заявка на отпуск"
      },
      {
        "links": {
          "run": {
            "href": "https://api.amo.io/v1.3/rpa/bots/c6cba44a-b41e-11f0-b3e1-02420a000114/run",
            "method": "POST"
          },
          "self": {
            "href": "https://api.amo.io/v1.3/rpa/bots/c6cba44a-b41e-11f0-b3e1-02420a000114"
          }
        },
        "id": "dc283ac1-b41e-11f0-b3e1-02420a000114",
        "title": "Заявка на оплату счёта"
      }
    ]
  },
  "count": 2,
  "page_token": "eyJwcm90b3R5cGVfaWRfZ3QiOiJkYzI4M2FjMS1iNDFlLTExZjAtYjNlMS0wMjQyMGEwMDAxMTQifQ=="
}

Request: GET https://api.amo.io/v1.3/bots

Content-Type: application/json

Body: -

Query Parameters:

Параметр Обязательно Тип Описание
limit Нет int Размер страницы. По умолчанию 500.
page_token Нет string Строка для получения следующей страницы.
query Нет string Для поиска по названию бота.

Response

Content-Type: application/hal+json

Body:

Поле Обязательно Тип Описание
links.first.href Да string (url) Ссылка на первую страницу.
links.next.href Нет string (url) Ссылка на следующую страницу. Отсутствует, если следующей страницы нет.
links.self.href Да string (url) Ссылку на текущую страницу.
_embedded.items Да []RPABot Список ботов
count Нет int Количество ботов. Отсутствует при 0.
page_token Нет string Строка для получения следующей страницы. Отсутствует, если следующей страницы нет.

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
400 https://developers.amo.tm/docs/handle-errors/#validation-error Некорректный запрос
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Создание импорта

curl -X POST 'https://api.amo.io/v1.3/import' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'

Создание нового импорта. Возвращает текущий активный импорт приложения или создаёт новый.

Request: POST https://api.amo.io/v1.3/import

Content-Type: application/json

Body: -

Response

Content-Type: application/json

Body: Import

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Импорт пользователя

curl -X POST 'https://api.amo.io/v1.3/import/{IMPORT_ID}/users' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "name": "Иван Петров",
  "phone": "+79998887766",
  "email": "ivan.petrov@mail.ru",
  "position": "Генеральный директор",
  "department_id": "7ff9da4e-7929-11f0-b12d-325096b39f47"
}'

Импортирует пользователя в мессенджер. Пользователь не получит СМС при импорте по телефону. Если пользователь с такими авторизационными данными уже есть в amo, он будет добавлен в аккаунт с именем и аватаркой из amo.

Request: POST https://api.amo.io/v1.3/import/{IMPORT_ID}/users

Idempotency key:

К этому запросу можно приложить ключ идемпотентности. Ключ передаётся в заголовке X-Idempotency-Key и представляет из себя UUID.

Content-Type: application/json

Body:

Поле Обязательно Тип Описание
name Да string Имя пользователя
phone Да, если не передано email string Номер телефона в международном формате
email Да, если не передано phone string Адрес электронной почты
position Нет string Должность
department_id Нет string (uuid) ID отдела
avatar_url Нет string (url) Ссылка на аватар пользователя

Response

Content-Type: application/json

Body: User

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
400 https://developers.amo.tm/docs/handle-errors/#avatar-link-is-not-image Ссылка на аватарку ведёт не на изображение
400 https://developers.amo.tm/docs/handle-errors/#validation-error Некорректный запрос
403 https://developers.amo.tm/docs/handle-errors/#import-belongs-to-another-app Импорт создан другим приложением
404 https://developers.amo.tm/docs/handle-errors/#import-not-found Импорт не найден
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Импорт канала

curl -X POST 'https://api.amo.io/v1.3/import/{IMPORT_ID}/channels' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "title": "My channel",
  "created_at": 1741190625,
  "avatar_url": "https://st1.amo.tm/account/fa0bddfe-72a2-11f0-bd06-a2b42a79b522.jpg?temp_url_sig=765782244a984a00b0ee8e5939b66dbd7b7a29b6&temp_url_expires=1754556907",
  "members": [
    {
      "user_id": "30ce69da-d8ac-11ef-86ff-ea9d37b1270e"
    },
    {
      "user_id": "c6a77c76-7929-11f0-a760-325096b39f47"
    }
  ]
}'

Импортирует групповой чат в мессенджер.

Request: POST https://api.amo.io/v1.3/import/{IMPORT_ID}/channels

Idempotency key:

К этому запросу можно приложить ключ идемпотентности. Ключ передаётся в заголовке X-Idempotency-Key и представляет из себя UUID.

Content-Type: application/json

Body:

Поле Обязательно Тип Описание
title Да string Имя пользователя
created_at Да int Дата создания канала
avatar_url Нет string (url) Ссылка на аватар пользователя
members Да Recipient Участники канала

Response

Content-Type: application/json

Body: Channel

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
400 https://developers.amo.tm/docs/handle-errors/#avatar-link-is-not-image Ссылка на аватарку ведёт не на изображение
400 https://developers.amo.tm/docs/handle-errors/#validation-error Некорректный запрос
403 https://developers.amo.tm/docs/handle-errors/#import-belongs-to-another-app Импорт создан другим приложением
404 https://developers.amo.tm/docs/handle-errors/#import-not-found Импорт не найден
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Импорт сообщений

Импортирует сообщения в мессенджер.

Request: POST https://api.amo.io/v1.3/import/{IMPORT_ID}/messages

Idempotency key:

К этому запросу можно приложить ключ идемпотентности. Ключ передаётся в заголовке X-Idempotency-Key и представляет из себя UUID.

Content-Type: application/json

Body: ImportMessagesRequest

Response

Content-Type: application/json

Body: ImportMessagesResponse

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
403 https://developers.amo.tm/docs/handle-errors/#import-belongs-to-another-app Импорт создан другим приложением
404 https://developers.amo.tm/docs/handle-errors/#import-not-found Импорт не найден
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Завершение импорта

curl -X POST 'https://api.amo.io/v1.3/import/{IMPORT_ID}/complete' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "success": false,
  "error_message": "Импорт прерван пользователем"
}'

Завершение импорта.

Request: POST https://api.amo.io/v1.3/import/{IMPORT_ID}/complete

Content-Type: application/json

Body:

Поле Обязательно Тип Описание
success Да bool Успешно ли завершён импорт
error_message Нет string Причина завершения импорта с ошибкой

Response

Content-Type: application/json

Body: Import

Codes:

Код Тип (опционально) Описание
200 - OK
401 - Невалидный токен авторизации
403 - Действие запрещено (нет разрешения)
400 https://developers.amo.tm/docs/handle-errors/#validation-error Некорректный запрос
403 https://developers.amo.tm/docs/handle-errors/#import-belongs-to-another-app Импорт создан другим приложением
404 https://developers.amo.tm/docs/handle-errors/#import-not-found Импорт не найден
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

Webhooks

Интеграция может подписываться на события по своим объектам обсуждения. Сервер интеграции должен ответить на запрос HTTP статусом 200..299. Время обработки запроса не должно превышать 30 сек. События отправляются в формате json.

Если сервер интеграции ответит не валидным кодом, отправка событий приостановится на 10 секуннд. Каждый последующий ошибочный запрос увеличивает время простоя в 2 раза.

При первой ошибке отправится уведомление на почту и в ЛК разарботчика.

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

События хранятся 24 часа. Если в течение 24 часов проблема не была устранена, есть риск потерять события совсем.

Проверка подлинности запроса

Все запросы от нашего сервера подписываются алгоритмом HMAC sha1. В каждом запросе будет заголовок X-Signature, который содержит подпись. Подпись формируется из тела запроса.

Просмотр объекта

{
    "company_id": "41950cda-ba96-11e8-ad95-1c872c5f1719",
    "event_id": "20b27b43-bb44-11e8-95b1-1c872c5f1719",
    "event_time": 1537201514294,
    "event_type": "object.read",
    "event": {
        "user_id": "20b27b43-bb44-11e8-95b1-1c872c5f1719",
        "object_id": "7cfZDmQIpEemrKAJCrBMABg"
    }
}

Событие формируется, когда объект был просмотрен пользователем.

Новое сообщение

В настройках приложения необходимо подписаться на событие messages

{
  "_embedded": {
    "context": {
      "company_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
    },
    "conversation_identity": {
      "direct_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
    },
    "message": {
      "links": {
        "self": {
          "href": "/v1.3/conversations/2b92db76-9897-11eb-a9d4-00163ef260f3/messages/b5edcbfc-9948-11eb-8344-02420aff0111"
        }
      },
      "id": "b5edcbfc-9948-11eb-8344-02420aff0111",
      "author": {
        "user_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
      },
      "text": "Hello world!!!",
      "created_at": 1617982313388,
      "updated_at": 1617982313388
    }
  },
  "event_id": "5f3c3cb1-c804-468b-8834-b73d01555af0",
  "event_type": "income_message"
}
Поле Тип Описание
event_id string Уникальный идентификатор события
event_type EventType Тип события
_embedded.context Context Описывает где произошло событие.
_embedded.conversation_identity ConversationIdentity Идентификатор сущности, в которой произошло событие
_embedded.message Message Объект сообщения

Новый пользователь

{
  "company_id": "636b704c-11a6-11e8-92bc-02000a040011",
  "event": {
    "admin": false,
    "deleted": true,
    "email": "asldasl@dvsv.com",
    "contact_email": "todelete@gmail.com",
    "group_id": "636cf0d4-11a6-11e8-8d75-02000a040011",
    "name": "asldasl@dvsv.com",
    "phone": "",
    "position": "",
    "user_id": "636d2036-11a6-11e8-8e0b-02000a040011"
  },
  "event_id": "8b4fdfac-f5d3-4a22-8771-0cd7bf2fb8b9",
  "event_time": 1554204952,
  "event_type": "user.created"
}

Событие о появлении в аккаунте нового активного пользователя

Пользователь изменен

{
  "company_id": "636b704c-11a6-11e8-92bc-02000a040011",
  "event": {
    "admin": false,
    "deleted": true,
    "email": "asldasl@dvsv.com",
    "contact_email": "todelete@gmail.com",
    "group_id": "636cf0d4-11a6-11e8-8d75-02000a040011",
    "name": "asldasl@dvsv.com",
    "phone": "",
    "position": "",
    "user_id": "636d2036-11a6-11e8-8e0b-02000a040011"
  },
  "event_id": "8b4fdfac-f5d3-4a22-8771-0cd7bf2fb8b9",
  "event_time": 1554204952,
  "event_type": "user.updated"
}

Событие о изменении данных пользователя

Пользователь деактивирован

{
  "company_id": "636b704c-11a6-11e8-92bc-02000a040011",
  "event": {
    "user_id": "636d2036-11a6-11e8-8e0b-02000a040011"
  },
  "event_id": "8b4fdfac-f5d3-4a22-8771-0cd7bf2fb8b9",
  "event_time": 1554204952,
  "event_type": "user.deleted"
}

Событие о деактивации пользователя, он был удален из аккаунта

Сообщение закреплено

В настройках приложения необходимо подписаться на события pins.

{
   "_embedded":{
      "context":{
         "company_id":"cba98926-e53c-11ee-b017-02420a0001fa",
         "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
      },
      "conversation_identity":{
         "direct_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
      },
      "pin_added":{
         "message_id":"d1c96fa4-12d4-11ef-892d-02420a000017",
         "pinned_by":{
            "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
         },
         "created_at":1715791579175
      }
   },
   "event_id":"6481ff33-462e-4a90-81e2-03e61de4dd5c",
   "event_type":"pin_added",
   "event_time":1715791579
}
Поле Тип Описание
_embedded.Context Context Кто и где инициировал событие
_embedded.conversation_identity ConversationIdentity ID сущности, в которой закреплено сообщение
_embedded.pin_added MessagePin Закрепление сообщения
event_id string(uuid) ID события
event_type EventType Тип события
event_time int Время отправки события

Сообщение откреплено

В настройках приложения необходимо подписаться на события pins.

{
  "_embedded":{
    "context":{
      "company_id":"cba98926-e53c-11ee-b017-02420a0001fa",
      "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
    },
    "conversation_identity":{
      "direct_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
    },
    "pin_removed":{
      "message_id":"a51465cc-12d4-11ef-892d-02420a000017",
      "unpinned_by":{
        "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
      }
    }
  },
  "event_id":"b2032e54-5e0e-4e00-ab8c-3ac94b85ed7e",
  "event_type":"pin_removed",
  "event_time":1715848174
}
Поле Тип Описание
_embedded.Context Context Кто и где инициировал событие
_embedded.conversation_identity ConversationIdentity ID сущности, в которой откреплено сообщение
_embedded.pin_removed MessagePin Открепление сообщения
event_id string(uuid) ID события
event_type EventType Тип события
event_time int Время отправки события

Боты в заявках

Разработка виджета для конструктора бота

Вы можете расширить возможности конструктора разработав один или несколько виджетов. Все разработанные вами виджеты будут доступны администратору компании для добавления в конструктор.

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

Начало работы

Регистрация нового виджета

Вам нужно зарегистрировать новый виджет в разделе "Виджеты" на портале разработчика. (в разработке. Сейчас зарегистрировать новый виджет можно по запросу в чат ТП)

При регистрации виджета нужно указать все возможные коды возврата. Например "Успех" и "ошибка"

Разработка интерфейса настройки виджета

При добавлении виджета в конструктор отправляется запрос iframe на URL компонетов , указанный в настройках приложения.

    POST: /<your app sheets url location>
    Host: <your app sheets url host>
    Origin: https://sheets.amo.tm
    Content-Type: application/x-www-form-urlencoded

    context.company_id=<Идентификатор команды>&context.user_id=<Идентификатор юзера>&input_values%5Bkey%5D=value&signature=sha1%3D0550cbb0e283f8566680b3610255b1dc23b4c509&widget_id=<Идентификато виджета>

В ответ приложение должно вернуть html код интерфейса настроек виджета.

JS SDK

JS SDK помогает виджету взаимодействовать с конструктором бота:

Инициализация SDK

<script src="https://js.amo.tm/v1/sdk.js"></script>
const amoSDK = window.AmoSDK();

Сохранение произвольного значения в установленном экземпляре виджета

amoSDK.setInputValues({
    'key1': 'value1',
});

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

const amoSDK = window.AmoSDK();

const elements = amoSDK.elements();

const field1 = elements.create('inline-select', {
    className: 'someClassName',
    items: [{id: '', option: '...'}],
    name: 'field1',
    value: '<Initial value>',
    onChange: onValueChanged,
});

amoSDK.request('rpa-fields').then((fields) => {
    const fieldOptions = [{ id: '', option: '...' }].concat(Object.values(fields).map((field) => ({
        id: field.id,
        option: field.title
    })));
    field1.update({items: fieldOptions})
});

amoSDK.on('update:rpa-fields', (fields) => {
    const fieldOptions = [{ id: '', option: '...' }].concat(Object.values(fields).map((field) => ({
            id: field.id,
            option: field.title
        })));
        field1.update({items: fieldOptions});
});

Проверка подписи

Чтобы убедиться, что запрос и правда пришел от сервера amo, можно высчитать хэш сумму параметров запроса и сравнить со значением signature, которое вернуть от сервера. Для этого нужно:

    /**
     * Handle an incoming request.
     *
     * @param Request $request
     * @param \Closure $next
     *
     * @return Response
     */
    public function handle(Request $request, \Closure $next): Response
    {
        $rawPost = file_get_contents('php://input');
        // todo to factory and strategy
        if ($rawPost) {
            $rawPost = explode('&', $rawPost);
            $rawPost = array_map(
                static function (string $value) {
                    return urldecode(str_replace('=', '', $value));
                },
                $rawPost
            );

            $rawPost = array_filter(
                $rawPost,
                static function (string $value) {
                    return !str_starts_with($value, 'signature');
                }
            );

            sort($rawPost);
            $rawPost = implode('', $rawPost);
        }

        $signature = $_POST['signature'] ?? '';
        if (empty($signature)) {
            throw new AccessDeniedHttpException('Signature not found');
        }

        if (!$this->isValid($signature, $rawPost)) {
            //todo exception
            throw new AccessDeniedHttpException('Invalid Signature');
        }

        return $next($request);
    }

    /**
     * @param string $signature
     * @param string $data
     *
     * @return bool
     */
    protected function isValid(string $signature, string $data): bool
    {
        $data = trim($data);
        [$algo, $hash] = explode('=', $signature, 2) + ['', ''];

        if (!in_array($algo, hash_algos(), true)) {
            throw new \RuntimeException('Unsupported algorithm ' . $algo);
        }

        $calculatedHash = hash_hmac($algo, $data, $this->clientSecret);

        return hash_equals($calculatedHash, $hash);
    }

Получение хука о передаче управления

Когда amo передает управление виджету, отправляется вебхук на URL обратного вызова

в input_values передаются данные, сохраненные ранее виджетом в процессе настроек

{
    "links": {
        "self": {
            "href": ""
        }
    },
    "_embedded": {
        "rpa_bot_control_transferred": {
            "links": {
                "self": {
                    "href": ""
                }
            },
            "_embedded": {
                "context": {
                    "links": {
                        "self": {
                            "href": ""
                        }
                    },
                    "company_id": "f15b7faa-e07f-11ea-a653-00163ef260f3"
                },
                "income_message": {
                    "links": {
                        "self": {
                            "href": "/v1.3/conversations/9be50521-6931-49ab-8abb-010f6bd343c8/messages/181f2949-e08f-11ea-a1cd-02420aff008a"
                        }
                    },
                    "id": "181f2949-e08f-11ea-a1cd-02420aff008a",
                    "author": {
                        "user_id": "6f7733fc-9a37-11e8-9cba-1866da4cd631"
                    },
                    "text": "efew",
                    "created_at": 1597671577786,
                    "updated_at": 1597671577809
                },
                "request": {
                    "links": {
                        "self": {
                            "href": "/v1.3/rpa/request/9be50521-6931-49ab-8abb-010f6bd343c8"
                        }
                    },
                    "id": "9be50521-6931-49ab-8abb-010f6bd343c8",
                    "status_id": "c687ae20-e08e-11ea-854a-0123456789ab",
                    "title": "Новый бот",
                    "author_id": "6f7733fc-9a37-11e8-9cba-1866da4cd631"
                }
            },
            "bot_id": "0d3dc328-e08f-11ea-88f7-0242c0a87970",
            "widget_id": "a373875d-d731-11ea-aa9a-02420aff004d",
            "input_values": {
                "instance_id": "053abfa3-e08f-11ea-8470-02420aff0085"
            }
        }
    },
    "event_id": "d2732c1e-1c1d-45da-9292-318a7cec9df4",
    "event_type": "rpa_bot_control_transferred"
}

Получение ответа пользователя

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

{
    "links": {
        "self": {
            "href": ""
        }
    },
    "_embedded": {
        "rpa_bot_income_message": {
            "links": {
                "self": {
                    "href": ""
                }
            },
            "_embedded": {
                "context": {
                    "links": {
                        "self": {
                            "href": ""
                        }
                    },
                    "company_id": "f15b7faa-e07f-11ea-a653-00163ef260f3"
                },
                "income_message": {
                    "links": {
                        "self": {
                            "href": "/v1.3/conversations/9be50521-6931-49ab-8abb-010f6bd343c8/messages/e5c996f3-e091-11ea-a1cd-02420aff008a"
                        }
                    },
                    "id": "e5c996f3-e091-11ea-a1cd-02420aff008a",
                    "author": {
                        "user_id": "6f7733fc-9a37-11e8-9cba-1866da4cd631"
                    },
                    "text": "112",
                    "created_at": 1597672781829,
                    "updated_at": 1597672781853
                },
                "request": {
                    "links": {
                        "self": {
                            "href": "/v1.3/rpa/request/9be50521-6931-49ab-8abb-010f6bd343c8"
                        }
                    },
                    "id": "9be50521-6931-49ab-8abb-010f6bd343c8",
                    "status_id": "c687ae20-e08e-11ea-854a-0123456789ab",
                    "title": "Новый бот",
                    "author_id": "6f7733fc-9a37-11e8-9cba-1866da4cd631"
                }
            },
            "bot_id": "0d3dc328-e08f-11ea-88f7-0242c0a87970",
            "widget_id": "a373875d-d731-11ea-aa9a-02420aff004d",
            "input_values": {
                "instance_id": "053abfa3-e08f-11ea-8470-02420aff0085"
            }
        }
    },
    "event_id": "c8f889b8-210a-4e2d-a3f0-f46d09f79c69",
    "event_type": "rpa_bot_income_message"
}

Объектная модель

EventType

Тип: enum string

Содержит одно из следующих значений:

Значение Описание
income_message Входящее сообщение от пользователя
app_uninstalled Приложение было удалено
inbox_read Чат прочитан
rpa_bot_income_message Входящее сообщение от бота заявки
rpa_bot_control_transferred Бот заявки передал управление виджету
pin_added Закреплено сообщение
pin_removed Откреплено сообщение

Context

{
  "company_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Тип: object

Поле Тип Описание
company_id string (uuid) Идентификатор команды, где произошло событие
user_id string (uuid) Идентификатор пользователя, который вызвал действие

ConversationIdentity

Идентификатор директ чата

{
  "direct_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор канала

{
  "channel_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор объекта обсуждения

{
  "object_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Тип: object

Заполняется всегда ОДНО из значений.

Поле Тип Описание
direct_id string (uuid) Идентификатор пользователя
channel_id string (uuid) Идентификатор канала
object_id string (uuid) Идентификатор объекта обсуждения

Message

Текстовое сообщение

{
  "links": {
    "self": {
      "href": "/v1.3/conversations/2b92db76-9897-11eb-a9d4-00163ef260f3/messages/b5edcbfc-9948-11eb-8344-02420aff0111"
    }
  },
  "id": "b5edcbfc-9948-11eb-8344-02420aff0111",
  "author": {
    "user_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
  },
  "text": "Hello world!!!",
  "created_at": 1617982313388,
  "updated_at": 1617982313388
}

Изображение

{
  "links": {
    "self": {
      "href": "/v1.3/conversations/2b92db76-9897-11eb-a9d4-00163ef260f3/messages/a6cc16bf-9952-11eb-8344-02420aff0111"
    }
  },
  "id": "a6cc16bf-9952-11eb-8344-02420aff0111",
  "author": {
    "user_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
  },
  "attachments": [
    {
      "type": "photo",
      "photo": {
        "filename": "icon.png",
        "size": 10492,
        "link": "https://api.amo.tm/storage/account/a6730417-9952-11eb-8344-02420aff0111.jpg?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc0ODMsImlzcyI6ImFjY291bnQvYTY3MzA0MTctOTk1Mi0xMWViLTgzNDQtMDI0MjBhZmYwMTExLmpwZyJ9.z6dxinWcppvW-fNILQ2F28cg52-RfyFVvLGi8PAF-kE"
      }
    }
  ],
  "created_at": 1617986582969,
  "updated_at": 1617986582969
}

Документ

{
  "links": {
    "self": {
      "href": "/v1.3/conversations/2b92db76-9897-11eb-a9d4-00163ef260f3/messages/0b51deec-9953-11eb-8344-02420aff0111"
    }
  },
  "id": "0b51deec-9953-11eb-8344-02420aff0111",
  "author": {
    "user_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
  },
  "attachments": [
    {
      "type": "document",
      "document": {
        "filename": "test.xlsx",
        "size": 8263,
        "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/0afdfec3-9953-11eb-8344-02420aff0111.xlsx?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc2NTEsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy8wYWZkZmVjMy05OTUzLTExZWItODM0NC0wMjQyMGFmZjAxMTEueGxzeCJ9.L3vz3aqvgvIz5yIf3fGo4OYPDmFHPMKkevj_KJLodCw"
      }
    }
  ],
  "created_at": 1617986751618,
  "updated_at": 1617986751618
}

Голосовое

{
  "links": {
    "self": {
      "href": "/v1.3/conversations/2b92db76-9897-11eb-a9d4-00163ef260f3/messages/f6525598-9959-11eb-8344-02420aff0111"
    }
  },
  "id": "f6525598-9959-11eb-8344-02420aff0111",
  "author": {
    "user_id": "cd207d02-988a-11eb-bd28-00163ef260f3"
  },
  "attachments": [
    {
      "type": "voice",
      "voice": {
        "size": 17141,
        "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/f5fe5d9a-9959-11eb-8344-02420aff0111.?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5OTA2MjMsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy9mNWZlNWQ5YS05OTU5LTExZWItODM0NC0wMjQyMGFmZjAxMTEuIn0.gdYslllrfdbmK_0fLzJKnY11dC87hmKhuCE8ykSlvuw"
      }
    }
  ],
  "created_at": 1617989722866,
  "updated_at": 1617989722866
}

Тип: object

Поле Тип Описание
id string (uuid) Идентификатор сообщения
author Recipient Идентификатор участника переписки
receiver Recipient Идентификатор участника, которого упомянули в сообщении. Только в каналах и объектах обсуждения
text string Текст сообщения
attachments []Attachment Объекты вложения. На данный момент всегда содержит 1 элемент.
created_at int(timestampMilli) Время создания сообщения (в миллисекундах)
updated_at int(timestampMilli) Время обновления сообщения (в миллисекундах)
reply_markup ReplyMarkup Объект разметки
reply_to MessageRef Указатель на цитируемое сообщение
pin bool Сообщение закреплено

Message v1.0

Текстовое сообщение

{
  "to": {
    "type": "all"
  },
  "from": {
    "type": "thread",
    "id": "9996a615-be28-11eb-ab1c-02420a000088"
  },
  "message": {
    "text": "who am i"
  }
}

Тип: object

Поле Тип Описание
id string (uuid) Идентификатор сообщения
from Participant Идентификатор участника переписки
to Participant Идентификатор участника, которого упомянули в сообщении. Только в каналах и объектах обсуждения
message MessageBody v1.0 Текст сообщения
refer_to ReferTo Идентификатор сообщения для ответа

MessageBody v1.0

Сообщение

{
    "text": "Hello friend"
}

Сообщение с фото

{
  "text": "Hello friend",
  "attachment": {
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c1/Duck_on_Yeadon_Tarn_%2813th_November_2010%29_002.jpg/1200px-Duck_on_Yeadon_Tarn_%2813th_November_2010%29_002.jpg"
    }
  }
}
Поле Тип Описание
text string Текст сообщения
attachment Attachment v1.0 Вложения

ReferTo v1.0

Идентификатор сообщения

{
  "id": "5303654e-92b7-11ef-b1b0-02420a000055"
}
Поле Тип Описание
id string Идентификатор сообщения

Attachment v1.0

Поле Тип Описание
type int Тип вложения
payload AttachmentPayload v1.0 Вложение

AttachmentPayload v1.0

Поле Тип Описание
url string Ссылка на вложение

Participant

Идентификатор участника переписки

Идентификатор пользователя

{
  "type": "user",
  "id": "9996a615-be28-11eb-ab1c-02420a000088"
}

Идентификатор бота

{
  "type": "bot",
  "id": "9996a615-be28-11eb-ab1c-02420a000088"
}

Идентификатор отдела

{
  "type": "group",
  "id": "9996a615-be28-11eb-ab1c-02420a000088"
}

Идентификатор треда

{
  "type": "thread",
  "id": "9996a615-be28-11eb-ab1c-02420a000088"
}

Тип: object

Поле Тип Описание
type string Тип получателя/отправителя
id string (uuid) Идентификатор

Recipient

Идентификатор участника переписки

Идентификатор пользователя

{
  "user_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор бота

{
  "bot_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор отдела

{
  "department_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор треда

{
  "thread_id": "cd26a1dc-988a-11eb-b88e-00163ef260f3"
}

Идентификатор упоминания всех участников чата

{
  "all": true
}

Идентификатор гостя

{
  "guest": {
    "id": "cd26a1dc-988a-11eb-b88e-00163ef260f3",
    "name": "Иван Петров"
  }
}

Гость - отправитель сообщения, не состоящий в аккаунте и чате.

Тип: object

Заполняется всегда ОДНО из значений.

Поле Тип Описание
user_id string (uuid) Идентификатор пользователя
bot_id string (uuid) Идентификатор бота
department_id string (uuid) Идентификатор отдела
thread_id string (uuid) Идентификатор треда
all bool Идентификатор упоминания всех участников чата
guest object Гость

Attachment

Ранее загруженный файл

{
  "file_id": "8e97fddd-8c8f-11ef-a286-089df4ec9762"
}

Изображение

{
  "type": "photo",
  "photo": {
    "filename": "icon.png",
    "size": 10492,
    "link": "https://api.amo.tm/storage/account/a6730417-9952-11eb-8344-02420aff0111.jpg?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc0ODMsImlzcyI6ImFjY291bnQvYTY3MzA0MTctOTk1Mi0xMWViLTgzNDQtMDI0MjBhZmYwMTExLmpwZyJ9.z6dxinWcppvW-fNILQ2F28cg52-RfyFVvLGi8PAF-kE"
  }
}

Документ

{
  "type": "document",
  "document": {
    "filename": "test.xlsx",
    "size": 8263,
    "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/0afdfec3-9953-11eb-8344-02420aff0111.xlsx?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc2NTEsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy8wYWZkZmVjMy05OTUzLTExZWItODM0NC0wMjQyMGFmZjAxMTEueGxzeCJ9.L3vz3aqvgvIz5yIf3fGo4OYPDmFHPMKkevj_KJLodCw"
  }
}

Голосовое

{
  "type": "voice",
  "voice": {
    "size": 17141,
    "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/f5fe5d9a-9959-11eb-8344-02420aff0111.?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5OTA2MjMsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy9mNWZlNWQ5YS05OTU5LTExZWItODM0NC0wMjQyMGFmZjAxMTEuIn0.gdYslllrfdbmK_0fLzJKnY11dC87hmKhuCE8ykSlvuw"
  }
}

Вложение

Тип: object

Модель допускает указание вложения при помощи ссылки или с использованием id ранее загруженного файла

Поле Тип Описание
file_id string(uuid) Идентификатор файла
type AttachmentType Тип вложение
photo AttachmentPhoto Метаданные изображения
document AttachmentDocument Метаданные документа
voice AttachmentVoice Метаданные голосового файла
video AttachmentVideo Метаданные видеофайла

AttachmentType

Тип: enum string

Содержит одно из следующих значений:

Значение Описание
document Документ
photo Изображение
voice Голосовое
video Видео

AttachmentPhoto

{
  "filename": "icon.png",
  "size": 10492,
  "link": "https://api.amo.tm/storage/account/a6730417-9952-11eb-8344-02420aff0111.jpg?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc0ODMsImlzcyI6ImFjY291bnQvYTY3MzA0MTctOTk1Mi0xMWViLTgzNDQtMDI0MjBhZmYwMTExLmpwZyJ9.z6dxinWcppvW-fNILQ2F28cg52-RfyFVvLGi8PAF-kE"
}

Метаданные изображения

Тип: object

Поле Тип Описание
filename string Название файла
size int Размер файл в байтах
link string Ссылка на скачивание файла. Ссылка имеет ограниченное время жизни

AttachmentDocument

{
  "filename": "test.xlsx",
  "size": 8263,
  "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/0afdfec3-9953-11eb-8344-02420aff0111.xlsx?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5ODc2NTEsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy8wYWZkZmVjMy05OTUzLTExZWItODM0NC0wMjQyMGFmZjAxMTEueGxzeCJ9.L3vz3aqvgvIz5yIf3fGo4OYPDmFHPMKkevj_KJLodCw"
}

Метаданные документа

Тип: object

Поле Тип Описание
filename string Название файла
size int Размер файл в байтах
link string Ссылка на скачивание файла. Ссылка имеет ограниченное время жизни

AttachmentVoice

{
  "duration": 5,
  "size": 17141,
  "link": "https://api.amo.tm/storage/cd26a1dc-988a-11eb-b88e-00163ef260f3/f5fe5d9a-9959-11eb-8344-02420aff0111.?s=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTc5OTA2MjMsImlzcyI6ImNkMjZhMWRjLTk4OGEtMTFlYi1iODhlLTAwMTYzZWYyNjBmMy9mNWZlNWQ5YS05OTU5LTExZWItODM0NC0wMjQyMGFmZjAxMTEuIn0.gdYslllrfdbmK_0fLzJKnY11dC87hmKhuCE8ykSlvuw"
}

Метаданные голосового файла

Тип: object

Поле Тип Описание
size int Размер файл в байтах
link string Ссылка на скачивание файла. Ссылка имеет ограниченное время жизни
duration int Длительность голосового сообщения в секундах

AttachmentVideo

{
  "filename": "test.mp4",
  "size": 189281,
  "link": "https://st1.amo.tm/account/4e179cca-6265-11ec-af37-5649ce3b4baf/28c12f6c-a36b-11f0-a29b-aa0ecb70f4fa.mp4?temp_url_sig=6ca9701da719edab7c5ad81153609d3b5f12dca5&temp_url_expires=1759920544"
  "preview_link": "https://st1.amo.tm/account/5e43e08b-a36b-11f0-a29b-aa0ecb70f4fa.jpg?temp_url_sig=cd7a592d33a299a6401dc39ccb2c255eb1e022ba&temp_url_expires=1759920627"
}

Метаданные видеофайла

Тип: object

Поле Тип Описание
filename string Название файла
size int Размер файл в байтах
link string Ссылка на скачивание файла. Ссылка имеет ограниченное время жизни
preview_link string Ссылка на обложку видео. Ссылка имеет ограниченное время жизни

ReplyMarkup

Объект разметки сообщения

Тип: object

Поле Тип Описание
inline_keyboard ReplyMarkupInlineKeyboard Кнопки, встроенные в сообщение

ReplyMarkupInlineKeyboard

Тип: object

Поле Тип Описание
buttons []ReplyMarkupInlineKeyboardButton Массив кнопок

ReplyMarkupInlineKeyboardButton

Тип: object

Поле Тип Описание
text string Текст кнопки

MessageRef

Ссылка на цитируемое сообщение

Тип: object

Поле Тип Описание
type ConversationIdentity Переписка, которой принадлежит цитируемое сообщение
msg_id string(uuid) Идентификатор сообщения

Request

Заявка бота

Тип: object

Поле Тип Описание
id string (uuid) Идентификатор заявки
status_id string (uuid) Идентификатор активного статуса
title string Наименование бота
author_id string (uuid) Идентификатор создателя заявки
created_at int Время создания заявки
updated_at int Время последнего обновления заявки
seq_id string Порядковый номер заявки
responsible_id string (uuid) Идентификатор отвественного пользователя в данный момент
responsible Recipient Идентификатор отвественного пользователя в данный момент
bot_id string (uuid) Идентификатор бота
prototype_id string (uuid) Идентификтор прототипа заявки
field_values map[string]RequestFieldValue Значение полей заявки

RequestField

Поле заявки

Тип: object

Поле Тип Описание
id string (uuid) Идентификтор поля
type int Тип поля
title string Наименование поля
multiple bool Несколько значений для поля
enums []RequestFieldEnum Значение

RequestFieldValue

Значение поля заявки

Тип: object

Поле Тип Описание
string string Строковое значение
enum_id []string Значение перечислений
float float64 Значение числа с точкой
int int64 Значения целого числа или времени
int_range []int64 Значения промежутка времени
currency Currency Значение валюты
date string Значение даты в формате ISO-8601
date_range []string Значение промежутка дат в формате ISO-8601

Таблица соответствия типов и значений полей:

Тип multiple RequestFieldValue Описание
1 false string Строка
2 false string Текст
3 false enum_id Список
5 false int (deprecated)
date
Дата
5 true int_range (deprecated)
date_range
Промежуток дат
7 false int Дата и время
8 false int Целое число
9 false float Число с плавающей точкой
10 false currency Валюта
11 false enum_id Пользователь

Currency

Валюта

Тип: object

Поле Тип Описание
currency int64 Код валюты в ISO 4217
value int64 Сумма, умноженная на 100

RequestFieldEnum

Перечисление для полей заявок

Тип: object

Поле Тип Описание
id string (uuid) Индентификатор перечисления
title string Значение перечисления

RequestStatus

Статус заявки

Тип: object

Поле Тип Описание
id string Идентификатор статуса
title string Наименование статуса
color string Цвета стауса, в формате HEX

Team

Команда

Тип: object

Поле Тип Описание
id string (uuid) Идентификатор команды
title string Название команды

TeamCreateResponse

Ответ на запрос создания команды

Тип: Team

Embedded

-

Profile

Профиль

Тип: object

Наследование от User

Поле Тип Описание
external_id string Внешний уникальный идентификатор в разрезе интеграции

ProfileCreateResponse

Ответ на запрос создания профиля

Тип: Profile

Embedded

-

User

Пользователь

Тип: object

Поле Тип Описание
id string (uuid) Идентификатор пользователя
name string Имя пользователя
email string Электронный адрес пользователя
phone string Номер телефона пользователя
team_props TeamProps Свойства пользователя в команде

TeamProps

Свойства пользователя в команде

Тип: object

Поле Обязательно Тип Описание
is_admin Нет bool Является ли пользователь администратором
position Нет string Должность
updated_at Да int Дата обновления свойств пользователя
invited_at Да int Дата приглашения пользователя в команду
status Нет Status Статус пользователя

Status

Статус пользователя

Тип: object

Поле Обязательно Тип Описание
slug Нет string Идентификатор статуса (для системных статусов)
emoji Нет string Эмодзи статуса
title Да string Название статуса
expired_at Нет int Дата истекания статуса (пустое, если статус бессрочный)

slug - идентификатор системного статуса. У кастомных статусов поле slug отсутствует.

Значения поля slug для системных статусов:

slug Emoji Title (ru) Title (en)
system_status_on_vacation 🏝️ В отпуске On vacation
system_status_out_sick 🤒 На больничном Out sick
system_status_working_from_home 🏠 Работаю удалённо Working from home
system_status_in_a_meeting 📅 На встрече In a meeting
system_status_on_a_lunch_break 🍔 На обеде On a lunch break

MessagePin

Закрепление сообщения

{
  "message_id":"d1c96fa4-12d4-11ef-892d-02420a000017",
  "pinned_by":{
    "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
  },
  "created_at":1715791579175
}

Открепление сообщения

{
  "message_id":"a51465cc-12d4-11ef-892d-02420a000017",
  "unpinned_by":{
    "user_id":"cb7c1748-e53c-11ee-9818-02420a0001fa"
  }
}

Закрепление/открепление сообщения

Тип: object

Поле Обязательно Тип Описание
message_id Да string (uuid) ID сообщения
pinned_by Да, если сообщение закреплено Recipient Кто закрепил сообщение
unpinned_by Да, если сообщение откреплено Recipient Кто открепил сообщение
created_at Нет int Время закрепления сообщения.
_embedded.message Нет Message Сообщение

Pagination

{
  "next_cursor":"eyJMYXN0TWVzc2FnZUlkIjoiYTkxZDBkMWUtZmI0OC0xMWVlLWEzMGQtMDI0MjBhMDAwMDEzIn0="
}

Состояние постраничного получения данных

Тип: object

Поле Обязательно Тип Описание
next_cursor Нет string Значение параметра cursor для получения следующей страницы. Отсутствует, если следующей страницы нет

RPABot

{
  "id": "124bd6f4-7684-11ef-85a0-02420a0001fa",
  "title": "Заявка на отпуск"
}

Бот

Тип: object

Поле Обязательно Тип Описание
id Да string (uuid) Идентификатор бота
title Да string Наименование бота

Channel

{
  "id": "625c76d4-210b-4501-98f7-cca012bb6fb0",
  "title": "My channel",
  "created_at": 1741190625000,
  "updated_at": 1741190629000
}

Канал (групповой чат)

Тип: object

Поле Обязательно Тип Описание
id Да string (uuid) Идентификатор канала
title Да string Название канала
created_at Да int Дата создания канала
updated_at Нет int Дата обновления канала

Import

{
  "id": "6d3d460c-7799-11f0-988a-02420a0001a9",
  "status": "in_progress",
  "users": 10,
  "channels": 2,
  "messages": 143
}

Импорт

Тип: object

Поле Обязательно Тип Описание
id Да string (uuid) Идентификатор импорта
status Да ImportStatus Наименование бота
users Нет uint32 Количество импортированных пользователей
channels Нет uint32 Количество импортированных каналов
messages Нет uint32 Количество импортированных сообщений
error_message Нет string Ошибка интеграции, из-за которой был завершён импорт

ImportStatus

Статус, в котором находится импорт

Тип: enum

Значения:

ImportMessagesRequest

{
  "messages": [...]
}

Тело запроса на импорт сообщений

Тип: object

Поле Обязательно Тип Описание
messages Да []ImportMessagesRequestItem Импортируемые сообщения, от 1 до 50

ImportMessagesRequestItem

{
  "is_top": true,
  "conversation_identity": {
    "direct_id": "bfe89798-792a-11f0-9a7f-325096b39f47"
  },
  "created_at": 1755188512,
  "author": {
    "user_id": "bfe89798-792a-11f0-9a7f-325096b39f47"
  },
  "text": "Отправил фотографию",
  "attachments": [
    {
      "type": "photo",
      "photo": {
        "filename": "photo.jpg",
        "link": "https://st1.amo.tm/account/fa0bddfe-72a2-11f0-bd06-a2b42a79b522.jpg?temp_url_sig=765782244a984a00b0ee8e5939b66dbd7b7a29b6&temp_url_expires=1754556907"
      }
    }
  ]
}

Тело запроса на импорт одного сообщения

Тип: object

Поле Обязательно Тип Описание
is_top Нет bool Должно ли сообщение отображаться на диалоге
conversation_identity Да ConversationIdentity Чат, в который импортируется сообщение. Указывается чат для автора сообщения. Только директ-чаты и каналы.
created_at Да int Дата отправки сообщения
author Да Recipient Автор сообщения
receiver Нет Recipient Пользователь, упомянутый в сообщении. Игнорируется для директ-чатов
text Да, если не переданы attachments или service_message string Текст сообщения
reply_to Нет MessageRef Пересланное/цитируемое сообщение
attachments Да, если не переданы text или service_message []Attachment Вложения. На данный момент всегда содержит 1 элемент.
service_message Да, если не переданы attachments или text ServiceMessage Системное сообщение

ImportMessagesResponse

{
  "items": [...]
}

Тело ответа на импорт сообщений

Тип: object

Поле Обязательно Тип Описание
items Да []ImportMessagesResponseItem Результаты импорта сообщений

ImportMessagesResponseItem

{
  "id": "52eba396-792b-11f0-8267-325096b39f47"
}

Результат импорта одного сообщения. Возвращается одно из полей.

Тип: object

Поле Тип Описание
id string (uuid) ID сообщения в amo
error object (problem+json) Ошибка импорта сообщения

Возможные ошибки:

Код Тип (опционально) Описание
403 "https://developers.amo.tm/docs/handle-errors/#file-storage-limit-overflow" В команде превышен лимит файлового хранилища для импортированных файлов
500 https://developers.amo.tm/docs/handle-errors/#file-link-bad-http-status При скачивании файла по ссылке вернулся некорректный HTTP-статус
500 https://developers.amo.tm/docs/handle-errors/#error-type-not-implemented Внутренняя ошибка сервера

ServiceMessage

{
  "free_form_text": {
    "text": "Это системное сообщение"
  }
}

Системное сообщение. Всегда заполняется одно из значений.

Тип: object

Поле Тип Описание
free_form_text ServiceMessageFreeFormText Системное сообщение со свободным текстом

ServiceMessageFreeFormText

{
    "text": "Это системное сообщение"
}

Системное сообщение со свободным текстом

Тип: object

Поле Тип Описание
text string Текст системного сообщения