Действия в SmartApp API

Обновлено 19 февраля 2025

SmartApp API

С помощью объектов массива actions вы можете задать поведение смартапа при получении команды и при нажатии на элемент интерфейса — кнопку или ячейку карточки.

Действия передаются в подсказках и карточках, в массиве items ответа смартапа.

Пример массива buttons (кнопок смартапа), который содержит массив действий actions.

{
  "payload": {
    "suggestions": {
      "buttons": [
        {
          "title": "string",
          "actions": [
            {
              "type": "text",
              "text": "Текст",
              "should_send_to_backend": true
            }
          ]
        }
      ]
    }
  }
}

Типы действий

Отправка текста от лица пользователя

text — действие, которое обозначает отправку сообщения от имени пользователя в чат с ассистентом.

{
  "type": "text",
  "text": "Текст",
  "should_send_to_backend": true
}

Отправяляет сообщение от имени пользователя в чат с ассистентом. Например, по нажатию кнопки карточки.

type

string

Тип дейсвия

text

string

required

Текст сообщения от имени пользователя

should_send_to_backend

boolean

По умолчанию: true

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

Переход по диплинку

deep_link — действие, которое обозначает обработку диплинка ассистентом или хост-приложением.

{
  "type": "deep_link",
  "deep_link": "example://app/profile"
}

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

type

string

Тип действия

deep_link

string

required

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

Действие на бэкенде

server_action — произвольное сообщение для бэкенда смартапа. Действия этого типа позволяют запускать сторонние смартапы.

{
  "type": "server_action",
  "message_name": "SERVER_ACTION",
  "server_action": {
    "action_id": "example_action_name",
    "payload": {}
  }
}

Произвольное сообщение для бэкенда смартапа. Действия этого типа позволяют запускать сторонние смартапы.

type

string

Тип действия

message_name

string

По умолчанию: SERVER_ACTION

Название сообщения

server_action

object

required

action_id

string

Произвольное название действия

payload

object

Объект с произвольными параметрами действия

Запуск сторонних смартапов

Действия типа server_action позволяют запускать сторонние смартапы. Возможность запуска сторонних смартапов согласуется индивидуально на этапе модерации.

Чтобы запустить сторонний смартап, в поле message_name необходимо передать значение RUN_APP. При этом сообщение должно выглядеть следующим образом:

{
    "type": "server_action",
    "message_name": "RUN_APP",
    "server_action": {
        "action_id": "run_app",
        "app_info": {
            "projectId": "example_456",
            "applicationId": "app_456_ios",
            "appversionId": "app_version_456"
        },
        "payload": {
            "example_usefull_field": "example_456",
            "example_text": "Привет"
        }
    }
}

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

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

Бэкенд запускаемого смартапа получит запрос RUN_APP.

Поле payload — необязательный JSON-объект. Поле может содержать произвольные параметры, которые будут обработаны запускаемым смартапом.

Проведение платежей

При завершении оплаты ассистент отправляет server_action c "action_id": "PAY_DIALOG_FINISHED". Это сообщение позволяет определить статус счета, переданного на оплату.

Получение сообщения PAY_DIALOG_FINISHED не означает, что счет перешел в финальный статус.

Пример сообщения:

"payload": {
    ...
    "server_action": {
      "action_id": "PAY_DIALOG_FINISHED",
      "parameters": {
        "payment_response":
            {
                "response_code": 0,
                "invoice_id": "***ID****"
            },
        "app_info":
            {
                "projectId": "**",
                "systemName": "**"
            }
        }
      }
    }
    ...
}

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

• 0 — успешная оплата;
• 1 — неожиданная ошибка;
• 2 — пользователь закрыл смартап. При получении этого кода необходимо дополнительно отправить запрос на проверку статуса платежа, чтобы отобразить результат пользователю;
• 3 — невозможно начать оплату, так как отображается другой сценарий оплаты;
• 4 — время оплаты счета истекло;
• 5 — оплата отклонена бэкендом;
• 6 — состояние оплаты неизвестно;
• 7 — оплата для данной поверхности недоступна.