Gå til indholdet

SMSBAT RESTful API Guide

Komplet guide til SMSBAT RESTful API - alt hvad du behøver at vide.

Sidst opdateret: 29. august 2025

SMSBAT RESTful API giver dig mulighed for at sende forskellige meddelelsestyper: Viber-karrusel, Viber-survey, Viber-promo (billeder, video), Viber business chats, OTP-beskeder (Viber OTP, Flash Call) og deres fallback-varianter.

Bemærk: Dette er den forenede HTTP API til udgående meddelelser. Hvis du har brug for integrationer med indgående bots (Viber Bot / Telegram Bot), se venligst Cascade API.

1. Protokol

  • Protokol: HTTPS
  • Request Body: JSON-objekt, der indeholder en række "meddelelser".
  • Metoder:
  • "GET" for at hente data (meddelelsesstatus, saldo osv.)
  • "POST" for at oprette objekter (f.eks. initiering af en udsendelse/afsendelse)
  • PATCH for at ændre objekter

2. Autorisation

Vi tilbyder flere godkendelsesmetoder for din bekvemmelighed: - HTTP Basic Authentication (login og adgangskode fra dit dashboard). - Brugerdefineret HTTP-header "X-Authorization-Key", der indeholder et API-token. - HTTP Basic Authentication-adgangskodefelt, der indeholder API-tokenet (passer @ som login).

API-token kan genereres i Dashboard under Brugerprofil.

Eksempler på anmodning

Med grundlæggende godkendelse: 

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

Med X-Authorization-Key: 

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. Sende beskeder

I SMSBAT-platformen betragtes enhver meddelelsesforsendelse (selv en enkelt meddelelse) som en "Broadcast" (meddelelsesliste).

Endepunkt - Metode: POST - URL: https://api.smsbat.com/bat/messagelist - Overskrifter: Content-Type: application/json

Grundlæggende nyttelaststruktur: 

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

Påkrævede felter for hvert meddelelsesobjekt:

  • fra: Bekræftet afsenderens alfanavn.
  • til: Modtagerens telefonnummer (E.164-format).
  • type: Meddelelsestype enum.
  • tekst: Beskedens hovedtekst (valgfrit, hvis typen ikke kræver tekst).

Understøttede 'type'-værdier: - 'sms' - viber_service (eller viber_trans) - viber_promo - viber_karrusel - viber_survey - viber_otp - viber_session - flashcall_callback - 'flashcall'

Valgfri almindelige felter:

  • customerMessageId: Streng-id i dit eget system (bruges til at spore tilbagekald). Skal være unik pr. besked.
  • dtSend: ISO8601 Dato/klokkeslæt for planlagt fremtidig afsendelse.
  • dtExpire: ISO8601 Dato/tidspunkt for leveringsfristen.
  • ttl: Time-To-Live på få sekunder. (Hvis dtExpire ikke er angivet, beregner API'et standardmapping fra typen).

Standard TTL'er (sekunder):

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

4. Fallback Routing (Cascading)

Du kan angive en reservekø for at sikre levering af beskeder, hvis den primære kanal fejler eller udløber.

{
  "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 udløses, når udbyderen afviser hovedmeddelelsen, eller når TTL'en udløber.

5. Oversigt over meddelelsestyper og meddelelsesdata

Komplekse meddelelsestyper kræver yderligere konfigurationer indsat i "messageData" egenskaben.

5.1 Viber Promo (viber_promo)

Kun billede 

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

Tekst + knap 

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

Billede + tekst + knap Kombinerer img, buttonText og buttonAction.

Video nyttelast: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Du kan også kombinere videoegenskaber med buttonText og buttonAction).

5.2 Viber Transactional / Service (viber_trans, viber_service)

Hvis du har en godkendt skabelon, der indeholder en vedhæftet fil: 

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

Kræver et "carousel.items"-array inde i "messageData".

Begrænsninger: - Varelængde: mellem 2 og 5 varer - Titel: 2 til 38 tegn - imageUrl: JPEG/PNG anbefalet størrelse 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-undersøgelse/liste (viber_survey)

Opretter en interaktiv afstemning i chatvisningen. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Meddelelsens "tekst" egenskab fungerer som undersøgelsens titel (maks. 85 tegn). Du kan sende mellem 2 og 5 muligheder, hver maks. 50 tegn.

5.5 Viber OTP (viber_otp)

Bruger forudregistrerede lokaliserede Viber-skabeloner globalt. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Skabelonparametre (pin, business_platform_name) skelner strengt mellem store og små bogstaver. API'en understøtter forskellige ISO-kodesprogsvarianter ('EN', 'ES', 'RU', 'TR', 'UK' osv.).

5.6 Flash Call ('flashcall')

De sidste cifre i opkaldsnummeret (den genererede kode) skal videregives via parameteren "tekst". Hvis tekst udelades, er koden randomiseret, og du skal udtrække den fra API'ens synkrone 200 OK Response-legeme (beskeder/tekst).

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