Помощен център Съвместимост с API на Messagio

Съвместимост с API на Messagio

SMSBAT поддържа слой за съвместимост с Messagio API. Това ви позволява да мигрирате вашите съществуващи Viber интеграции, предназначени за Messagio, директно към SMSBAT, без да се налага да пренаписвате структурата на полезния си товар или да променяте логиката на интегриране.

Настройки на връзката

За да маршрутизирате заявки през SMSBAT, актуализирайте основния URL адрес и идентификационните данни за удостоверяване във вашата интеграция:

  • Основен URL: https://restapi.smsbat.com
  • Крайна точка: POST /api/SendMessage
  • Формат на заявката: application/x-www-form-urlencoded (Данни на формуляра)

Удостоверяване и идентификационни данни

Заявките се удостоверяват с помощта на параметри, изпратени директно в рамките на данните от формуляра на тялото на заявката:

ПараметърТипЗадължителноОписание
userнизДаВашето име за вход в SMSBAT акаунт или потребителски идентификатор.
signнизДаAPI тайна или подпис, регистриран за името на изпращача.
fromнизДаАлфа име на регистриран подател.
sending_methodнизДаТип канал. Използвайте viber за обикновени Viber Business съобщения или viber_otp за Viber OTP шаблони.
phoneнизДаТелефонен номер на получателя в международен формат (напр. 380501234567).

Типове съобщения във Viber

Изберете раздел по-долу, за да видите конкретните параметри и да заявите полезни данни за различни структури на съобщения във Viber:

Изпраща обикновено текстово съобщение.

Допълнителни параметри:

ПараметърТипЗадължителноОписание
txtнизДаТекст на съобщението.

Пример за заявка на полезен товар:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

=== „Съобщение от въртележка“

Изпраща интерактивна карта със съобщение, съдържаща множество слайдове (карти), през които потребителят може да плъзне.

Допълнителни параметри:

| Параметър | Тип | Задължително | Описание |
| :--- | :--- | :--- | :--- |
| `txt` | низ | **Да** | Заглавен текст на въртележката. |
| `carousel[N].title` | низ | **Да** | Заглавие на картата `N` (започващо от 0). |
| `carousel[N].image_url` | низ | **Да** | Обществен HTTPS URL адрес на изображение на карта `N`. |
| `carousel[N].primary_label` | низ | **Да** | Надпис на главния бутон на карта `N`. |
| `carousel[N].primary_url` | низ | **Да** | URL връзка към главния бутон на картата `N`. |
| `carousel[N].secondary_label` | низ | Не | Надпис на втори бутон на карта `N`. |
| `carousel[N].secondary_url` | низ | Не | URL адрес на връзка към вторичен бутон на карта `N`. |

**Пример за заявка на полезен товар:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2
```

=== „Съобщение от анкетата“

Изпраща съобщение, съдържащо интерактивна анкета или въпрос от анкета.

**Допълнителни параметри:**

| Параметър | Тип | Задължително | Описание |
| :--- | :--- | :--- | :--- |
| `txt` | низ | **Да** | Текст на въпроса за анкетата. |
| `survey_options[N]` | низ | **Да** | Текст на опцията за проучване за артикул `N` (индекс, започващ от 0). Необходими са поне 2 опции. |
| `option_type` | цяло число | **Да** | Тип селектор: `1` (RadioButtons) или `2` (обикновени бутони). |

**Пример за заявка на полезен товар:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1
```

Формат на отговора

Крайната точка за съвместимост на API на Messagio връща отговори във XML формат с код на състоянието HTTP 200 OK.

Приет (успешен) отговор

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Отговори за грешка

Ако валидирането на параметри на заявка е неуспешно или удостоверяването е неуспешно, отговорът ще върне различен от нула код.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

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

URL адресите за обратно извикване трябва да бъдат внедрени и хоствани на вашата платформа. SMSBAT изпраща HTTP обратни извиквания, за да актуализира вашата система относно събития за доставка, отговори на анкети и потребителски отговори.

1. Обратно повикване за статус на доставка

Изпраща се, когато дадено съобщение премине в състояние (доставено, прочетено, неуспешно).

  • Тип съдържание: application/x-www-form-urlencoded
  • Метод: POST

Поискване на формати на полезен товар:

  • Доставено: 
    msg_id=MESSAGE_GUID&status=delivered
  • Видяно/Прочетено: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Недоставено/Неуспешно: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Описание на полетата:

  • msg_id: SMSBAT уникален идентификатор на съобщение (GUID), върнат в отговора SendMessage.
  • status: Резултат от доставката (delivered, undelivered или status unknown).
  • type: Задайте на seen, когато съобщението е било прегледано от получателя.
  • status_extended: Конкретна техническа причина за статуса на недоставено (напр. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Обратно повикване за отговор на анкета

Задейства се, когато потребител избере опция за отговор в съобщение от Viber Survey.

  • Тип съдържание: application/x-www-form-urlencoded
  • Метод: POST

Формат на заявката за полезен товар:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Обратно извикване на входящо потребителско съобщение

Задейства се, когато потребител изпрати текстово съобщение или медиен отговор обратно към вашата услуга Viber Business.

  • Тип съдържание: application/json
  • Метод: POST

Формат на заявката за полезен товар:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Описание на полетата:

  • msg_id: Уникалният идентификатор на съобщението, генериран за входящия отговор.
  • text: Текстово съдържание, изпратено от потребителя (може да бъде null, ако е изпратил само мултимедия).
  • media: Директен URL за изтегляне на всички медийни прикачени файлове, изпратени от потребителя (може да бъде null, ако е само текст).
  • phone: Телефонен номер на изпращача в международен формат.
  • sender_bm_id: ID на изпращача на Viber Business.