Ga naar inhoud

SMSBAT RESTful API-gids

Volledige gids voor de SMSBAT RESTful API – alles wat u moet weten.

Laatst bijgewerkt: 29 augustus 2025

Met SMSBAT RESTful API kunt u verschillende berichttypen verzenden: Viber-carrousel, Viber-enquête, Viber-promo (afbeeldingen, video), Viber zakelijke chats, OTP-berichten (Viber OTP, Flash Call) en hun fallback-varianten.

Opmerking: Dit is de uniforme HTTP API voor uitgaande berichtenuitwisseling. Als u integraties met inkomende bots (Viber Bot / Telegram Bot) nodig heeft, raadpleeg dan de Cascade API.

1. Protocol

  • Protocol: HTTPS
  • Request Body: JSON-object dat een reeks berichten bevat.
  • Methoden:
  • GET om gegevens op te halen (berichtstatus, saldo, enz.)
  • POST om objecten te maken (bijvoorbeeld het initiëren van een uitzending/verzending)
  • PATCH om objecten te wijzigen

2. Autorisatie

Voor uw gemak bieden wij verschillende autorisatiemethoden: - HTTP-basisauthenticatie (login en wachtwoord vanaf uw dashboard). - Aangepaste HTTP-header X-Authorization-Key met een API-token. - HTTP Basic Authentication-wachtwoordveld met daarin het API-token (geef @ door als login).

API-token kan worden gegenereerd in het Dashboard onder Gebruikersprofiel.

Voorbeelden aanvragen

Met basisauthenticatie: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Met X-autorisatiesleutel: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Berichten verzenden

Op het SMSBAT-platform wordt elke verzending van berichten (zelfs een enkel bericht) beschouwd als een "broadcast" (berichtenlijst).

Eindpunt - Methode: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Contenttype: application/json

Basisladingstructuur: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Verplichte velden voor elk berichtobject:

  • van: Geverifieerde alfanaam van de afzender.
  • naar: telefoonnummer van de ontvanger (E.164-formaat).
  • type: Berichttype enum.
  • text: Hoofdtekst van het bericht (optioneel als het type geen tekst vereist).

Ondersteunde type-waarden: - sms - viber_service (of viber_trans) - viber_promo - viber_carrousel - viber_enquête - viber_otp - viber_sessie - flashcall_callback - flitsoproep

Optionele algemene velden:

  • customerMessageId: String ID binnen uw eigen systeem (gebruikt voor het volgen van callbacks). Moet uniek zijn per bericht.
  • dtSend: ISO8601 Datum/tijd van geplande toekomstige verzending.
  • dtExpire: ISO8601 Datum/Tijd van de leveringsdeadline.
  • ttl: Time-To-Live in seconden. (Als dtExpire niet is opgegeven, berekent de API de standaardtoewijzing op basis van het type).

Standaard TTL's (seconden):

  • sms - 86400 (24 uur)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Terugvalroutering (cascadering)

U kunt een reservewachtrij opgeven om ervoor te zorgen dat berichten worden afgeleverd als het primaire kanaal mislukt of verloopt.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
Fallbacks worden geactiveerd wanneer de provider het hoofdbericht afwijst of wanneer de TTL verloopt.

5. Overzicht van berichttypen en berichtgegevens

Voor complexe berichttypen zijn aanvullende configuraties nodig die in de eigenschap messageData worden geïnjecteerd.

5.1 Viber-promotie (viber_promo)

Alleen afbeelding 

"messageData":{
  "img":"https://domain.com/image.png"
}

Tekst + Knop 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Afbeelding + Tekst + Knop Combineert img, buttonText en buttonAction.

Videopayload: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Je kunt video-eigenschappen ook combineren met buttonText en buttonAction).

5.2 Viber Transactioneel/Service (viber_trans, viber_service)

Als u een goedgekeurde sjabloon heeft met een bijgevoegd bestand: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

Vereist een carousel.items array in messageData.

Beperkingen: - Artikellengte: tussen 2 en 5 stuks - Titel: 2 tot 38 tekens - imageUrl: JPEG/PNG aanbevolen formaat 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Viber-enquête/lijst (viber_survey)

Creëert een interactieve peiling binnen de chatweergave. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
De eigenschap 'text' van het bericht fungeert als de titel van de enquête (max. 85 tekens). Je kunt tussen de 2 en 5 opties doorgeven, elk maximaal 50 tekens.

5.5 Viber OTP (viber_otp)

Maakt wereldwijd gebruik van vooraf geregistreerde, gelokaliseerde Viber-sjablonen. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Sjabloonparameters (pin, business_platform_name) zijn strikt hoofdlettergevoelig. De API ondersteunt verschillende ISO-codetaalvarianten (EN, ES, RU, TR, UK, enz.).

5.6 Flitsoproep ("flashcall")

De laatste cijfers van het kiesnummer (de gegenereerde code) moeten via de parameter text worden doorgegeven. Als text wordt weggelaten, wordt de code willekeurig verdeeld en moet u deze extraheren uit de synchrone 200 OK Response-tekst van de API (messages/text).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}