Messagio API-compatibiliteit

SMSBAT ondersteunt een compatibiliteitslaag met de Messagio API. Hierdoor kunt u uw bestaande Viber-integraties, ontworpen voor Messagio, rechtstreeks naar SMSBAT migreren zonder dat u uw payload-structuur hoeft te herschrijven of de integratielogica hoeft te wijzigen.

Verbindingsinstellingen

Om verzoeken via SMSBAT te routeren, updatet u de basis-URL en authenticatiegegevens in uw integratie:

Basis-URL: https://restapi.smsbat.com
Eindpunt: POST /api/SendMessage
Verzoekformaat: application/x-www-form-urlencoded (formuliergegevens)

Authenticatie en inloggegevens

Verzoeken worden geverifieerd met behulp van parameters die rechtstreeks in de formuliergegevens van het verzoek worden verzonden:

Parameter	Typ	Vereist	Beschrijving
`gebruiker`	tekenreeks	Ja	Uw SMSBAT-accountaanmelding of gebruikers-ID.
`teken`	tekenreeks	Ja	API-geheim of handtekening geregistreerd voor de afzendernaam.
`van`	tekenreeks	Ja	Alfanaam van geregistreerde afzender.
`verzendmethode`	tekenreeks	Ja	Kanaaltype. Gebruik `viber` voor gewone Viber Business-berichten of `viber_otp` voor Viber OTP-sjablonen.
`telefoon`	tekenreeks	Ja	Telefoonnummer van de ontvanger in internationaal formaat (bijvoorbeeld '380501234567').

Viber-berichttypen

Kies hieronder een tabblad om de specifieke parameters te bekijken en payloads aan te vragen voor verschillende Viber-berichtstructuren:

SMS-berichtTekst + knopAfbeeldingsberichtTekst + Afbeelding + KnopVideoberichtOTP-sjabloon

Verzendt een eenvoudig sms-bericht.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`txt`	tekenreeks	Ja	Berichttekst.

Vraag Payload-voorbeeld aan:

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

Stuurt een sms-bericht met een interactieve call-to-action-knop.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`txt`	tekenreeks	Ja	Berichttekst.
`knop_tekst`	tekenreeks	Ja	Tekst weergegeven op de knop.
`knop_link`	tekenreeks	Ja	Bestemmings-URL wanneer op de knop wordt geklikt.

Vraag Payload-voorbeeld aan:

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

Verzendt een openbaar afbeeldingsbestand.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`afbeelding_link`	tekenreeks	Ja	Openbare HTTPS-URL van de afbeelding.
`txt`	tekenreeks	Nee	Optionele bijschrifttekst om onder de afbeelding weer te geven.

Vraag Payload-voorbeeld aan:

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

Verzendt een uitgebreide kaart met tekst, een afbeelding en een knop.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`txt`	tekenreeks	Ja	Onderschrifttekst.
`afbeelding_link`	tekenreeks	Ja	Openbare HTTPS-URL van de afbeelding.
`knop_tekst`	tekenreeks	Ja	Tekst weergegeven op de knop.
`knop_link`	tekenreeks	Ja	Bestemmings-URL wanneer op de knop wordt geklikt.

Vraag Payload-voorbeeld aan:

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

Verzendt een videobestand met optioneel tekstbijschrift en actieknoppen.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`video.url`	tekenreeks	Ja	Openbare HTTPS-URL van het videobestand.
`video.miniatuur`	tekenreeks	Ja	Openbare HTTPS-URL van de videovoorbeeldafbeelding.
`video.grootte_mb`	geheel getal	Ja	Geschatte videobestandsgrootte in megabytes.
`video.duur_sec`	geheel getal	Ja	Videoduur in seconden.
`txt`	tekenreeks	Nee	Optionele beschrijvingstekst.
`knop_tekst`	tekenreeks	Nee	Optionele knoptekst (kan fungeren als bijschrift of link).
`knop_link`	tekenreeks	Nee	Optionele knoplink-URL.

Vraag Payload-voorbeeld aan:

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

Verzendt Viber eenmalige wachtwoorden (OTP) met behulp van een vooraf goedgekeurde sjabloon.

Opmerking

Wanneer u OTP-berichten verzendt, moet u sending_method instellen op viber_otp.

Extra parameters:

| Parameter | Typ | Vereist | Beschrijving |
| :--- | :--- | :--- | :--- |
| `sjabloon.id` | tekenreeks | **Ja** | Vooraf goedgekeurde Viber OTP-sjabloon-ID. |
| `sjabloon.lang` | tekenreeks | **Ja** | Sjabloontaalcode (bijvoorbeeld `en`, `uk`). |
| `sjabloon.params.pin` | tekenreeks | **Ja** | De OTP-pinwaarde die in de sjabloon moet worden geïnjecteerd. |
| `sjabloon.params.business_platform_naam` | tekenreeks | **Ja** | De tijdelijke aanduiding voor de bedrijfsnaam in de sjabloon. |
| `sjabloon.params.code_validity_time` | tekenreeks | **Ja** | Geldigheidsduur van de pincode in minuten. |

**Vraag Payload-voorbeeld aan:**
```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
```

CarrouselberichtEnquêtebericht

Verzendt een interactieve berichtenkaart met meerdere dia's (kaarten) waar de gebruiker doorheen kan vegen.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`txt`	tekenreeks	Ja	Titeltekst van de carrousel.
`carrousel[N].titel`	tekenreeks	Ja	Titel van kaart `N` (beginnend bij 0).
`carrousel[N].image_url`	tekenreeks	Ja	Openbare HTTPS-afbeeldings-URL van kaart 'N'.
`carrousel[N].primair_label`	tekenreeks	Ja	Hoofdknopbijschrift van kaart 'N'.
`carrousel[N].primaire_url`	tekenreeks	Ja	Hoofdknoplink-URL van kaart `N`.
`carrousel[N].secundair_label`	tekenreeks	Nee	Secundaire knopbijschrift van kaart 'N'.
`carrousel[N].secundaire_url`	tekenreeks	Nee	Secundaire knoplink-URL van kaart 'N'.

Vraag Payload-voorbeeld aan:

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

Verzendt een bericht met een interactieve opiniepeiling of enquêtevraag.

Extra parameters:

Parameter	Typ	Vereist	Beschrijving
`txt`	tekenreeks	Ja	Enquêtevraagtekst.
`enquête_opties[N]`	tekenreeks	Ja	Enquêteoptietekst voor item `N` (index beginnend bij 0). Er zijn minimaal 2 opties vereist.
`optie_type`	geheel getal	Ja	Type selector: `1` (RadioButtons) of `2` (gewone knoppen).

Vraag Payload-voorbeeld aan:

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

Antwoordformaat

Het Messagio API-compatibiliteitseindpunt retourneert antwoorden in XML-indeling met de statuscode 'HTTP 200 OK'.

Geaccepteerde (succes)reactie

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

Foutreacties

Als de validatie van een aanvraagparameter mislukt of de authenticatie mislukt, retourneert het antwoord een code die niet nul is.

Ontbrekende handtekeningOngeautoriseerd

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

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

Terugbelgesprekken

Callback-URL's moeten op uw platform worden geïmplementeerd en gehost. SMSBAT verzendt HTTP-callbacks om uw systeem op de hoogte te houden van bezorgingsgebeurtenissen, enquêtereacties en gebruikersantwoorden.

1. Terugbellen bezorgstatus

Wordt verzonden wanneer een bericht van status verandert (bezorgd, gelezen, mislukt).

Inhoudstype: application/x-www-form-urlencoded
Methode: POST

Vraag payloadformaten aan:

Bezorgd:
```
msg_id=MESSAGE_GUID&status=delivered
```

Gezien/Lezen:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Niet afgeleverd/mislukt:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Veldenbeschrijving:

msg_id: SMSBAT unieke bericht-ID (GUID) geretourneerd in het SendMessage-antwoord.
status: Leveringsresultaat (afgeleverd, niet afgeleverd of status onbekend).
type: Zet op gezien wanneer het bericht door de ontvanger is bekeken.
status_extended: specifieke technische reden voor niet-geleverde status (bijv. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Terugbellen op enquêteantwoord

Wordt geactiveerd wanneer een gebruiker een antwoordoptie selecteert in een Viber Survey-bericht.

Inhoudstype: application/x-www-form-urlencoded
Methode: POST

Vraag Payload-formaat aan:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Terugbellen via inkomende gebruikersboodschap

Wordt geactiveerd wanneer een gebruiker een sms- of media-antwoord terugstuurt naar uw Viber Business-service.

Inhoudstype: application/json
Methode: POST

Vraag Payload-formaat aan:

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

Veldenbeschrijving:

msg_id: De unieke bericht-ID die is gegenereerd voor het inkomende antwoord.
text: Tekstinhoud verzonden door de gebruiker (kan null zijn als deze alleen media heeft verzonden).
media: Directe URL om alle mediabijlagen te downloaden die door de gebruiker zijn verzonden (kan null zijn als er alleen tekst is).
telefoon: het telefoonnummer van de afzender in internationaal formaat.
sender_bm_id: de afzender-ID van Viber Business.