Инструменты коннектора

Коннектор https://mcp.alphasms.net/mcp отдаёт ассистенту 11 инструментов. Ниже — что делает каждый и какие параметры принимает. Жирным отмечены обязательные.

Инструменты чтения выполняются сразу. Инструменты отправки требуют confirm: true — без него коннектор отвечает отказом и в API не обращается.

Чтение

balance

Остаток на счету и валюта. Параметров нет.

senders_list

Зарегистрированные имена отправителя со статусом каждого. Параметров нет. Отправлять можно только с активного имени.

message_status

Статус отправленного сообщения. Возвращает числовой код и расшифровку.

Параметр	Тип	Описание
id	число	Идентификатор, под которым сообщение отправлялось

Полный перечень кодов — Статусы сообщений.

hlr_lookup

HLR-запрос: существует ли номер, в какой он сети, не перенесён ли к другому оператору. Услуга платная, один запрос на номер.

Параметр	Тип	Описание
phone	строка	Номер в международном формате, только цифры
id	число	Ваш идентификатор запроса

Отправка

Общее для всех инструментов отправки:

• confirm: true обязателен;
• один вызов — один номер, массовых рассылок нет;
• phone — только цифры, в международном формате;
• имя отправителя должно быть зарегистрировано и активно;
• id — ваш идентификатор сообщения; если не задан, коннектор сгенерирует его сам и вернёт в ответе, иначе сообщение станет неотслеживаемым;
• hook — URL, куда платформа пришлёт статус доставки;
• в ответе приходит идентификатор, а не факт доставки — статус спрашивайте через message_status.

send_sms

Одно SMS на один номер. 160 символов латиницей или 70 кириллицей в первом сообщении, дальше делится на части, каждая тарифицируется отдельно.

Параметр	Тип	Описание
phone	строка	Номер получателя
signature	строка	Зарегистрированное имя отправителя
message	строка	Текст сообщения
confirm	булево	Обязательно true
lifetime	число	Срок жизни сообщения в секундах
short_link	булево	Сокращать и отслеживать ссылки, по тарифу
unsubscribe_link	булево	Добавить ссылку отписки, по тарифу
id, hook		См. общие правила выше

send_viber

Тип сообщения коннектор собирает сам по переданным полям: текст, текст с картинкой или текст с картинкой и кнопкой.

Параметр	Тип	Описание
phone	строка	Номер получателя
signature	строка	Имя отправителя в Viber
message	строка	Текст, до 1000 символов
confirm	булево	Обязательно true
image	строка	URL картинки
link	строка	URL перехода по кнопке
button	строка	Надпись на кнопке
lifetime	число	Срок жизни в секундах
id, hook		См. общие правила выше

send_viber_with_sms_fallback

Каскад: сначала Viber, если он не доставлен — SMS. Списывается за то, что реально ушло, поэтому недоставленный Viber с досылкой стоит дороже одиночного SMS. Тексты задаются отдельно — в SMS обычно нужен более короткий.

Параметр	Тип	Описание
phone	строка	Номер получателя
viber_signature	строка	Имя отправителя в Viber
viber_message	строка	Текст для Viber
sms_signature	строка	Имя отправителя для SMS
sms_message	строка	Текст для SMS
confirm	булево	Обязательно true
image, link, button	строка	Картинка и кнопка для Viber
id, hook		См. общие правила выше

send_rcs

Доходит только на устройства с поддержкой RCS — для остальных нужен отдельный запасной канал.

Параметр	Тип	Описание
phone	строка	Номер получателя
signature	строка	Зарегистрированное имя отправителя
message	строка	Текст сообщения
confirm	булево	Обязательно true
image	строка	URL картинки
link	строка	URL перехода по кнопке
button	строка	Надпись на кнопке
lifetime	число	Срок жизни в секундах
id, hook		См. общие правила выше

send_voice

Синтезированный голосовой вызов с зачитыванием текста.

Параметр	Тип	Описание
phone	строка	Номер получателя
message	строка	Текст, который будет зачитан
confirm	булево	Обязательно true
language	строка	Язык озвучивания, например uk или ru
gender	строка	Пол голоса
name	строка	Имя голоса, если у тарифа их несколько
dtmf	булево	Собирать ответ абонента кнопками телефона
id, hook		См. общие правила выше

send_whatsapp

Работает, только если получатель ранее написал первым или дал согласие, и требует отдельно зарегистрированного имени и верифицированного аккаунта Facebook.

Параметр	Тип	Описание
phone	строка	Номер получателя
message	строка	Текст сообщения
confirm	булево	Обязательно true
id, hook		См. общие правила выше

send_verification_code

Отправляет одноразовый код и сам его генерирует. У операции отдельный адрес и свой набор полей: возвращается verify_id, по которому код потом сверяется.

Параметр	Тип	Описание
phone	строка	Номер получателя
signature	строка	Имя отправителя
confirm	булево	Обязательно true
channel	строка	Канал доставки: sms, viber или voice
code_length	число	Длина кода, по умолчанию 6
code_type	строка	Состав кода: numeric или alphanumeric
lang	строка	Язык шаблона, например uk
custom_id	строка	Ваш идентификатор для сверки
hook	строка	URL для статуса

Ответ при отказе

Если инструмент отправки вызван без подтверждения, коннектор возвращает отказ и не обращается к API:

{
  "refused": true,
  "reason": "Отправка тратит деньги клиента и требует явного подтверждения",
  "how_to": "Спросите человека и передайте confirm: true только после его согласия"
}

Если отправка отключена для вашего домена, инструменты отправки в списке не появляются вовсе.

Ошибки

Коннектор передаёт ошибки API как есть, без переформулирования. Частые случаи:

Что видно	Причина
Ошибка авторизации	неверный или отозванный ключ в заголовке Authorization
Имя отправителя недоступно	имя не зарегистрировано или ещё на модерации
Недостаточно средств	нулевой или отрицательный баланс
Неверный номер	номер не в международном формате или не существует

Коды совпадают с обычным API — см. Статусы сообщений.