Действия в SmartApp API

Обновлено 20 декабря 2023

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

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

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

object

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

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

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

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

Пример
Описание

type	string Тип дейсвия Value: "text"
text required	string Текст сообщения от имени пользователя
should_send_to_backend	boolean Default: true Указывает, что сообщение нужно не только отобразить в чате с ассистентом, но и отправить в бэкенд смартапа

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

type	string Тип дейсвия Value: "text"
text required	string Текст сообщения от имени пользователя
should_send_to_backend	boolean Default: true Указывает, что сообщение нужно не только отобразить в чате с ассистентом, но и отправить в бэкенд смартапа

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

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

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

Пример
Описание

type	string Тип действия Value: "deep_link"
deep_link required	string Диплинк, который нужно открыть. Работает только при вызове смартапа в мобильном приложении и в SberPortal

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

type	string Тип действия Value: "deep_link"
deep_link required	string Диплинк, который нужно открыть. Работает только при вызове смартапа в мобильном приложении и в SberPortal

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

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

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

Пример
Описание

type	string Тип действия Value: "server_action"
message_name	string Default: "SERVER_ACTION" Название сообщения
required	object

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

type	string Тип действия Value: "server_action"
message_name	string Default: "SERVER_ACTION" Название сообщения
required	object

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

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

Действия типа 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 — оплата для данной поверхности недоступна.

Действия в SmartApp API

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

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

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

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