Sari la conținut

Compatibilitate API Messagio

SMSBAT acceptă un strat de compatibilitate cu Messagio API. Acest lucru vă permite să migrați integrările existente Viber concepute pentru Messagio direct la SMSBAT fără a fi nevoie să rescrieți structura sarcinii utile sau să schimbați logica de integrare.

Setări de conexiune

Pentru a direcționa solicitările prin SMSBAT, actualizați adresa URL de bază și acreditările de autentificare în integrarea dvs.:

  • Adresa URL de bază: https://restapi.smsbat.com
  • Endpoint: POST /api/SendMessage
  • Format de solicitare: application/x-www-form-urlencoded (Date formular)

Autentificare și acreditări

Solicitările sunt autentificate folosind parametrii trimiși direct în datele formularului din corpul cererii:

Parametru Tip Necesar Descriere
utilizator șir Da Autentificarea contului dvs. SMSBAT sau identificatorul de utilizator.
semn șir Da Secretul API sau semnătura înregistrată pentru numele expeditorului.
din șir Da Numele alfa al expeditorului înregistrat.
metoda_trimitere șir Da Tipul de canal. Utilizați viber pentru mesajele obișnuite Viber Business sau viber_otp pentru șabloanele Viber OTP.
telefon șir Da Numărul de telefon al destinatarului în format internațional (de ex., „380501234567”).

Tipuri de mesaje Viber

Alegeți o filă de mai jos pentru a vedea parametrii specifici și pentru a solicita încărcături utile pentru diferite structuri de mesaje Viber:

=== „Mesaj text”

Trimite un mesaj text simplu.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `txt` | șir | **Da** | Textul mesajului. |

**Solicitare exemplu de sarcină utilă:**
```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=Hello+from+SMSBAT%21
```

=== „Text + Buton”

Trimite un mesaj text cu un buton interactiv de îndemn.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `txt` | șir | **Da** | Textul mesajului. |
| `button_text` | șir | **Da** | Text afișat pe buton. |
| `button_link` | șir | **Da** | Adresa URL de destinație când se face clic pe butonul. |

**Solicitare exemplu de sarcină utilă:**
```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=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com
```

=== „Mesaj imagine”

Trimite un fișier imagine public.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `image_link` | șir | **Da** | Adresa URL publică HTTPS a imaginii. |
| `txt` | șir | Nu | Subtitrare opțională pentru afișare sub imagine. |

**Solicitare exemplu de sarcină utilă:**
```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&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png
```

=== „Text + Imagine + Buton”

Trimite un card bogat care conține text, o imagine și un buton.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `txt` | șir | **Da** | Textul subtitrării. |
| `image_link` | șir | **Da** | Adresa URL publică HTTPS a imaginii. |
| `button_text` | șir | **Da** | Text afișat pe buton. |
| `button_link` | șir | **Da** | Adresa URL de destinație când se face clic pe butonul. |

**Solicitare exemplu de sarcină utilă:**
```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=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com
```

=== „Mesaj video”

Trimite un fișier video cu o legendă opțională și butoane de acțiune.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `video.url` | șir | **Da** | Adresa URL publică HTTPS a fișierului video. |
| `video.miniatură` | șir | **Da** | Adresa URL publică HTTPS a imaginii de previzualizare a videoclipului. |
| `video.size_mb` | întreg | **Da** | Dimensiunea aproximativă a fișierului video în megaocteți. |
| `video.duration_sec` | întreg | **Da** | Durata videoclipului în secunde. |
| `txt` | șir | Nu | Text de descriere opțional. |
| `button_text` | șir | Nu | Textul butonului opțional (poate acționa ca o legendă sau link). |
| `button_link` | șir | Nu | Adresa URL a linkului butonului opțional. |

**Solicitare exemplu de sarcină utilă:**
```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=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com
```

=== „Șablon OTP”

Trimite parole unice (OTP) Viber folosind un șablon preaprobat.

!!! notă
    Când trimiteți mesaje OTP, trebuie să setați `sending_method` la `viber_otp`.

Parametri suplimentari:

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `template.id` | șir | **Da** | ID-ul șablonului Viber OTP preaprobat. |
| `template.lang` | șir | **Da** | Codul de limbă al șablonului (de exemplu, `en`, `uk`). |
| `template.params.pin` | șir | **Da** | Valoarea PIN OTP de injectat în șablon. |
| `template.params.business_platform_name` | șir | **Da** | Substituentul numelui comercial din șablon. |
| `template.params.code_validity_time` | șir | **Da** | Perioada de valabilitate a PIN-ului în minute. |

**Solicitare exemplu de sarcină utilă:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

=== „Mesaj carusel”

Trimite un card de mesaj interactiv care conține mai multe diapozitive (carduri) prin care utilizatorul le poate trece.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `txt` | șir | **Da** | Textul titlului caruselului. |
| `carusel[N].titlu` | șir | **Da** | Titlul cardului `N` (începând cu 0). |
| `carusel[N].image_url` | șir | **Da** | Adresa URL publică a imaginii HTTPS a cardului „N”. |
| `carusel[N].primary_label` | șir | **Da** | Legenda butonului principal al cardului „N”. |
| `carusel[N].primary_url` | șir | **Da** | Adresa URL a linkului butonului principal al cardului „N”. |
| `carusel[N].secondary_label` | șir | Nu | Subtitrarea butonului secundar al cardului „N”. |
| `carusel[N].secondary_url` | șir | Nu | Adresa URL a linkului butonului secundar al cardului „N”. |

**Solicitare exemplu de sarcină utilă:**
```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
```

=== „Mesajul sondajului”

Trimite un mesaj care conține un sondaj interactiv sau o întrebare interactivă.

**Parametri suplimentari:**

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `txt` | șir | **Da** | Textul întrebării sondajului. |
| `survey_options[N]` | șir | **Da** | Textul opțiunii de sondaj pentru elementul „N” (index începând cu 0). Sunt necesare cel puțin 2 opțiuni. |
| `opțiune_tip` | întreg | **Da** | Tip de selector: `1` (Butoane Radio) sau `2` (Butoane obișnuite). |

**Solicitare exemplu de sarcină utilă:**
```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
```

Format de răspuns

Punctul final de compatibilitate cu API-ul Messagio returnează răspunsuri în format XML cu un cod de stare HTTP 200 OK.

Răspuns (de succes) acceptat

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

Răspunsuri de eroare

Dacă validarea parametrilor unei cereri eșuează sau autentificarea eșuează, răspunsul va returna un cod diferit de zero.

=== „Lipsește semnătura” 

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

=== „Neautorizat” 

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Reapeluri

Adresele URL de apel invers trebuie implementate și găzduite pe platforma dvs. SMSBAT trimite apeluri HTTP pentru a vă actualiza sistemul cu privire la evenimentele de livrare, răspunsurile la sondaj și răspunsurile utilizatorilor.

1. Starea livrării Apel invers

Trimis atunci când un mesaj trece la starea (livrat, citit, eșuat).

  • Content-Type: application/x-www-form-urlencoded
  • Metodă: POST

Solicitați formate de încărcare utilă:

  • Livrat: 
    msg_id=MESSAGE_GUID&status=delivered
  • Vzut/Citit: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Nelivrat/Eșuat: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Descrierea câmpurilor:

  • msg_id: ID-ul unic al mesajului SMSBAT (GUID) returnat în răspunsul SendMessage.
  • starea: rezultatul livrării (livrat, nelivrat sau starea necunoscută).
  • type: Setați la seen când mesajul a fost vizualizat de destinatar.
  • status_extended: motiv tehnic specific pentru starea nelivrată (de exemplu, VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Răspuns la sondaj

Declanșat atunci când un utilizator selectează o opțiune de răspuns într-un mesaj Viber Survey.

  • Content-Type: application/x-www-form-urlencoded
  • Metodă: POST

Solicitați format de încărcare utilă: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Reapelarea mesajului utilizatorului de intrare

Declanșat atunci când un utilizator trimite un răspuns text sau media înapoi la serviciul dvs. Viber Business.

  • Content-Type: application/json
  • Metodă: POST

Solicitați format de încărcare utilă: 

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

Descrierea câmpurilor:

  • msg_id: ID-ul unic al mesajului generat pentru răspunsul primit.
  • text: conținut text trimis de utilizator (poate fi null dacă a trimis doar media).
  • media: URL direct pentru a descărca orice atașamente media trimise de utilizator (poate fi null numai dacă este text).
  • telefon: numărul de telefon al expeditorului în format internațional.
  • sender_bm_id: ID-ul expeditorului Viber Business.