Інструменти конектора

Конектор 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 — див. Статуси повідомлень.