Front SMS Gateway API (Produktbeskrivelse)

Last ned som PDF -

1      Konto

1.1       Brukere

Ved bestilling vil du motta en invitasjon til en administratorbruker. Når man har opprettet denne, vil man få valget om å invitere flere brukere. Har man en egen utvikler eller utviklingsteam, så kan man invitere disse som «Administratorbrukere» så de får tilgang til oppsett av SMS Gateway API, og kan sette dette opp etter ønske. Siden er både på norsk og engelsk.

Man finner også produktinformasjon under https://fro.no/gw-produktbeskrivelse (norsk) og under https://fro.no/gw-productdescription (engelsk).

1.2       Oppsett av SMS Gateway API

Autentisering

Under oppsett av API finner man eksempel både for JSON og HTTP GET.

Det står også opplys om brukeridentifikasjon som skal benyttes (Service ID).

Man kan velge om man ønsker å autentisere på IP adresse(r), eller opprette et passord.

URL for status og innkommende

Man kan sette opp ønsket URL for statusmeldinger. Dette er ikke obligatorisk, men vil kunne gi tilbakemelding som meldinger blir levert til mottakers mobiltelefon, og eventuelt andre statusmeldinger som mottas fra teleoperatørene til mottaker.

Hvis man har støtte for innkommende SMS eller svar, så må man sette opp URL hvor man ønsker å motta disse.

Varsler for feilmeldinger

Man kan sette opp en eller flere epost adresser for mottak av eventuelle feilmeldinger. Vi anbefaler dette særlig i startfasen/utviklingsfasen, da disse meldingen gir nyttig informasjon om feilårsaken (feilkoder).

Det er separate varsler for feil på utgående (sendte) meldinger, og innkommende meldinger der vi ikke klarer å levere til deres server. For varsler på innkommende der vi ikke får levert meldinger, vil meldingene legges i kø. I varslene vil det følge med en link der dere kan starte køen på nytt så fort problemet er løst.

Sikkerhetstiltak

NB: Hvis funksjonalitet for å generere en SMS ligger på et åpent system (tilgjengelig for alle på internett), anbefaler vi at det lages sikkerhet rundt dette. Eksempler er løsninger der man legger inn et mobilnummer for å motta en engangskode eller annen informasjon.

Dette for å unngå at ondsinnede roboter kan masseutsende meldinger via deres konto, og sette dette i loop.

Vi har kunder som har blitt utsatt for dette med utsendelser til ulike land. Vi anbefaler derfor å sette opp logikk for å begrense faren for slike angrep som ofte kommer fra geografiske lokasjoner, stort antall fra samme IP-adresser, eller trafikk av størrelse til land dere ikke opererer i. reCAPTCHA i kombinasjon med andre tiltak kan være en løsning.

2      PARAMETER INDEKS

2.1       UTGÅENDE MELDINGER

Meldinger kan bli sendt enten ved å utføre en HTTP POST request med et JSON-dokument som inneholder parameterne under eller en HTTP GET request to the SMS Gateway som inkluderer parameterne i URLen.

ParameterBeskrivelseLovlige verdierKommentar
serviceidServer identifikatorUnik kunde IDObligatorisk
phonenoTelefonnummer til mottaker.Internasjonalt telefonnr. med landskode 004799999999Obligatorisk
txtMeldingen som blir sendt.Tekst som inneholder kun tegn i GSM-tegnsettet (GSM 03.38). Andre tegn blir erstattet. Dersom unicode-parameter er sendt, godtas alle Unicode-tegn.Obligatorisk. En melding inneholder maks 160 tegn (Unicode: 70). Er det flere tegn telles det som flere SMS. Hver SMS har da en lengde på 153 tegn (Unicode: 67). Maks er 1024 tegn.
fromidUnik avsender IDEt tildelt nummer / nummerserie av Front eller tildelt avsendertekst, maks 11 tegn.Obligatorisk – Unikt nummer for å kunne motta respons eller en tekst.
priceTakserte meldingerHele kroner i øre. Kr 1 til 200 Ekse kr 1=100 / kr 30 =3000 Må aktiveres av Front!Ikke obligatorisk. Ved bruk av taksering blir fromid  ”2401”; maks 160 tegn i tekst. Kan kun sende til norske abonnenter
unicodeTillatt Unicode tekstmeldingertrue, falseIkke obligatorisk. Som standard sendes alle meldinger med GSM-tegnsett (GSM 03.38), og ugyldige tegn blir konvertert. Dersom man legger til «unicode=true» tillates alle tegn (emoji, m.m.). Dersom meldingsteksten da inneholder tegn som ikke finnes in GSM-tegnsettet, sendes meldingen som Unicode.
encodingTegnsett benyttet til URL prosentkodingiso-8859-1, utf8, utf-8Ikke obligatorisk. Som standard må alle URL-parametere kodes med latinsk tegnsett (ISO-8859-1). NB! mange moderne HTTP-biblioteker benytter UTF-8 prosentkoding som standard. (Dette parameteret benyttes ikke ved JSON-request, da JSON er alltid UTF-8)

2.1.1     Send melding – Eksempler på HTTP POST med et JSON-dokument

Eksempel på HTTP POST med et JSON-dokument:

POST /psk/push.php HTTP/1.1

Host: www.pling.as

Content-Type: application/json

{

  «serviceid»: 3,

  «fromid»: «26114123450000»,

  «phoneno»: «004799999999»,

  «txt»: «Test æøå ÆØÅ»,

  «unicode»: false

}

Eksempel på å sende en melding som inneholder en emoji:

POST /psk/push.php HTTP/1.1

Host: www.pling.as

Content-Type: application/json

{

  «serviceid»: 3,

  «fromid»: «26114123450000»,

  «phoneno»: «004799999999»,

  «txt»: «Test 🤣»,

  «unicode»: true

}

Eksempel svar på vellykket request:

{

  «id»: 145099,

  «errorcode»: 0,

  «description»: «OK»

}

Eksempel svar på en request som feilet:

{

  «id»: 0,

  «errorcode»: 1,

  «description»: «Invalid mobile number»

}

Se §2.2 for en oversikt over feilkoder.

2.1.2     Send melding – Eksempler på HTTP GET

Eksempel på en melding som benytter latinsk prosentkoding: 

http://www.pling.as/psk/push.php?serviceid=1234&phoneno=004799999999&fromid=26114123450000&txt=Test%20%E6%F8%E5%20%C6%D8%C5

Eksempel på en melding som benytter UTF-8 prosentkoding:

https://www.pling.as/psk/push.php?serviceid=1234&encoding=utf8&phoneno=004799999999&fromid=26114123450000&txt=Test%20%C3%A6%C3%B8%C3%A5%20%C3%86%C3%98%C3%85

Eksempel på en melding med en emoji som benytter UTF-8 prosentkoding:

https://www.pling.as/psk/push.php?serviceid=1234&encoding=utf8&unicode=true&phoneno=004799999999&fromid=26114123450000&txt=Test%20%F0%9F%A4%A3

Rekkefølgen på parameterne har ingen betydning.

Eksempel svar:

ErrorCode=0, ID=145099

Se §2.2 for en oversikt over feilkoder.

2.2       FEILKODER PÅ UTGÅENDE MELDINGER

Ved utsendelse av melding vil vår gateway returnere en respons på den URL-en du sender. Denne responsen består av et ”errorcode” nummer og et ”ID” referansenummer som er unik for den ene forsendelsen.

ResponsBeskrivelse
errorcode=0OK (Melding sendt)
errorcode=1Ugyldig mobilnummer
errorcode=2Melding sendt fra illegal IP adresse
errorcode=3Ugyldig fromid
errorcode=4Ugyldig takstklasse SMS
errorcode=5Ingen resterende SMS meldinger på konto
errorcode=6Ikke tilgang til taksert SMS
errorcode=7Kontoen er sperret av Front, or feil serviceid
errorcode=8serviceid er blank/parameter mangler
errorcode=9phoneno er blank/parameter mangler
errorcode=10txt er blank/parameter mangler
errorcode=11fromid er blank/parameter mangler
errorcode=12Uglydig mobilnummer for taksert SMS
errorcode=13Ugyldig passord
errorcode=14Meldingen er for lang (maks 1024 tegn)
errorcode=15Taksert melding er for lang (maks 160 tegn). Gjelder kun takserte meldinger (price > 0)
errorcode=16txt inneholder ulovlig(e) tegn. Teksten kan kun inneholde som finnes i GSM-tegnsettet (GSM 03.38). Feilkoden er kun i bruk ved bulk-utsendelser (§2.4).
errorcode=17Duplikatmelding. Melding med samme fromid, phoneno og txt sendt i løpet av 120 sekunder.
errorcode=18Mangler kryptering. Bruk https istendenfor http.
errorcode=19Ugyldig verdi for encoding-parameter
errorcode=20unicode må være «true» eller «false»
errorcode=21Mobilnummer er svartelistet. Nummeret er kjent som ugyldig for mottak av SMS eller er tidligere benyttet i forbindelse med misbruk.

Merk at nye feilkoder kan bli lagt til ved fremtidige versjoner.

2.3       LEVERINGSSTATUS PÅ UTGÅENDE PUSH MELDINGER

Status på sendingen av en melding mot mottaker blir fortløpende postet til den URL som dere ønsker å motta på. Denne tjenesten er ikke obligatorisk, men for de som ønsker dette.

ParameterBeskrivelseLovlige verdierKommentar
statusNy status på SMS-1, 4, 5Se under
origidID ReferansenummerSamme siffer som bekreftelse ID’en når meldingen ble sendtUnikt nummer for hver enkelt tekstmelding

            Eksempel på status:  http://www.kunde.no/sms/?status=4&origid=145099

Status -1:

Meldingen er mottatt av teleoperatøren men ikke levert til mobiltelefon. Denne status kan komme etter status 4 hvis meldingen blir levert umiddelbart.

Status 4:

Meldingen er mottatt hos mottakers mobiltelefon. Man vet ikke om mottaker har lest meldingen, men teleoperatøren har registret selve leveringen.

Status 5:

Meldingen har feilet. I de fleste tilfellene skyldes dette at man har sendt til et mobiltelefonnummer som ikke er i bruk. Det at meldingen feiler kan også komme av driftsfeil hos teleoperatørene.

Hvis det benyttes en annen teleleverandør enn Telenor ved utsendelse indikerer manglende status at meldingen er på vei. Den vanligste årsaken til at man ikke får status med det samme i dette tilfellet, er at mottaker har slått av sin mobiltelefon, eller befinner seg i et område uten dekning. Det hender at man ikke får noen status selv om meldingen faktisk blir levert.

2.4       UTGÅENDE MELDINGER – BULK

For å sende en melding til flere mottakere, benytt en HTTP-post til følgende URL:

https://www.pling.as/psk/push_bulk.php

Request-body skal være et gyldig JSON-dokument (http://json.org) med følgende innhold:

ParameterBeskrivelseLovlige verdierKommentar          
serviceidServer identifikatorUnik kunde IDObligatorisk; nummer
phonenoTelefonnumre til mottakere.Internasjonalt telefonnr. med landskode 004799999999Obligatorisk; string array
txtMeldingen som blir sendt.Tekst som inneholder kun tegn i GSM-tegnsettet (GSM 03.38).Obligatorisk; string. En melding inneholder maks 160 tegn. Er det flere tegn telles det som flere SMS. Hver SMS har da en lengde på 153 tegn. Maks er 1024 tegn.
fromidUnik avsender IDEt tildelt nummer / nummerserie av Front eller tildelt avsendertekst, maks 11 tegnObligatorisk; string. Unikt nummer for å kunne motta respons eller en tekst.
unicodeTillatt Unicode tekstmeldingertrue, falseIkke obligatorisk. Som standard sendes alle meldinger med GSM-tegnsett (GSM 03.38), og tekst med ugyldige tegn blir avvist. Dersom «unicode» er satt til true  tillates alle tegn (emoji, m.m.). Når meldingsteksten inneholder tegn som ikke finnes in GSM-tegnsettet, sendes meldingen som Unicode.

Serveren godtar meldingen dersom det er minst ett gyldig mobilnummer og de øvrige feltene er gyldige.

Serveren svarer med HTTP statuskode 201 (created) dersom meldingen er godtatt. Alle andre statuskoder indikerer at meldingen ikke er godtatt og meldingen vil ikke bli sendt. Respons‐body inneholder en feilkode, beskrivelse, og lister med eventuelle ugyldige og duplikat mobilnumre som et JSON‐dokument.

Eksempler

Eksempel bulk-request:

{

  «serviceid»: 1234,

  «phoneno»: [«004799999999», «004799999998»],

  «txt»: «Test æøå ÆØÅ»,

  «fromid»: «Mitt Firma»

}

Eksempel bulk-request med emoji:

{

  «serviceid»: 1234,

  «phoneno»: [«004799999999», «004799999998»],

  «txt»: «Test 🤣»,

  «unicode»: true,

  «fromid»: «Mitt Firma» 

}

Eksempel på respons:

{

  «errorcode»: 0,

  «description»: «OK»,

  «invalidPhoneno»: [],

  «duplicatePhoneno»: []

}

Merk at responsen inneholder ikke referansenummer (ID) for meldingene som blir sendt. Bulk meldinger er dermed ikke egnet til bruk dersom man ønsker leveringstatus på utgående meldinger (se §2.2 – 2.3).

2.5       INNKOMMENDE MELDINGER (KUN GATEWAY PROFF OG PSK)

SMS Gateway kan konfigureres på https://login.pling.as/pling/gateway (innlogging kreves). URLen der innkommende meldinger blir levert kan konfigureres der, samt APIet som benyttes. For å sikre optimal sikkerhet og overholde personvernregler anbefaler vi at URLen bruker HTTPS og kun godtar tilkoblinger fra Fronts IP-adresser (18.197.36.176, 18.197.110.183 and 18.197.138.46).

2.5.1     INNKOMMENDE MELDINGER – HTTP POST JSON API

Dersom HTTP POST JSON API er valgt i SMS Gateway-innstillinger, blir innkommende meldinger levert til deres URL for innkommende meldinger som et JSON-dokument ved å benytte HTTP POST.

Innkommende meldinger JSON

Meldingen blir levert som et JSON-dokument (http://json.org/) med følgende felter:

ParameterTypeDescription
idNumberFront’s unik meldingidentifikator
toStringTelefonnummer dit meldingen ble sendt, enten i E164-format (f. eks. «+47594400»), et kortnummer (f. eks. «26114»), eller et kortnummer med sub-nummer (PSK-nummer, f. eks. «26114123456789»).
fromStringTelefonnummer til innsenderen i E164-format (f. eks. «+4799999999»). I noen tilfeller kan dette inneholde et nummer i nasjonalformat (f. eks. «26114») eller en tekst (f. eks «Front») bestående av inntil 11 tegn.
textStringMeldingsteksten. I tilfellet MMS, emnet (om det finnes) og alle tekstfiler i meldingen settes sammen med linjeskift for å utforme teksten. Se på meldingens SMIL-fil for å vise meldingens filer korrekt.
sentStringTidspunktet melding ble sendt eller ble mottatt av Front i ISO 8601-format (f. eks. «2020-12-31T23:59:59Z»)
counterNumberEn tellefunksjon som teller antall mottatte meldinger per kunde. Denne kan benyttes til å undersøke om man mangler innkommende SMS.
keywordStringFørste ord i meldingteksten. Kodeord blir ofte benyttet for å rute meldinger sendt til et kortnummer til riktig mottaker.
filesArrayFilene inkludert i en MMS. Se under for spesifikajson av File-objektet. Dette er et tomt array i tilfellet en vanlig SMS. *

* Merk at støtte for MMS er en tilleggstjeneste som ikke er aktivert som standard på deres konto. I dette tilfellet kan «files»-feltet ignoreres, inklusivt Fil-JSON spesifikasjonen under. Vennligst ta kontakt med Front dersom dere trenger tilgang til MMS-mottak.

Fil JSON

Hver fil i «files»-arrayet består av et objekt med følgende felter:

ParameterTypeDescription
idNumberFront’s unik identifikator for filen
contentTypeStringFilens MIME-type som spesifisert i MMSen
fileNameStringFilens navn som spesifisert i MMSen.
fileDataStringFilens binærdata kodet som Base64.

Forventet svar

Alle HTTP-svar sendt med en 2xx-statuskode vil tolkes som en vellykket levering. For eksempel, 200 (OK), 201 (Created), 202 (Accepted) og 204 (No Content) er akseptable HTTP-statuskoder.

Et HTTP-svar sendt med en annen statuskode tolkes som en mislykket levering. Mangel på svar innen 60 sekunder behandles som en timeout og også tolkes som en mislykket levering.

Eksempler

Eksempel SMS sendt til et kortnummer:

{

  «id»: 999999,

  «to»: «26114»,

  «from»: «+479999999»,

  «text»: «Test 123»,

  «sent»: «2019-12-31T23:59:59Z»,

  «counter»: 7166,

  «keyword»: «TEST»,

  «files»: []

}

Eksempel MMS sendt til et mobilnummer:

{

  «id»: 999999,

  «to»: «+4759440000»,

  «from»: «+479999999»,

  «text»: «Test 123»,

  «sent»: «2019-12-31T23:59:59Z»,

  «counter»: 7166,

  «keyword»: «TEST»,

  «files»: [

  {

    «id»: 4747,

    «contentType»: «text/xml;Name=smil.xml;Charset=UTF-8»,

    «fileName»: «smil.xml»,

    «fileData»: «PD94bWwgdmVyc2lvbj0iMS4wIj48c21pbD48L3Nta…»

  },

  {

    «id»: 4748,

    «contentType»: «text/plain;Name=text_75329.txt;Charset=UTF-8»,

    «fileName»: «text_175329.txt»,

    «fileData»: «VGVzdCAxMjM=»

  },

  {

    «id»: 4749,

    «contentType»: «image/jpeg;Name=image01.jpg»,

    «fileName»: «image01.jpg»,

    «fileData»: «w4PCv8ODwpjDg8K/w4PCoAAQSkZJRgABAQEASABIA…»

  }]

}

2.5.2 INNKOMMENDE MELDINGER – HTTP GET API

Dersom HTTP GET API er valgt i SMS Gateway-innstillinger, blir innkommende meldinger levert til deres URL som en HTTP GET request med meldingsdata sendt som spørringsparametere (query string). Parameterverdiene er prosentkodet med latinsk  (ISO-8859-1) tegnsett. Tegn som ikke kan kodes med latisk tegnsett blir konvertert til «?» før de kodes.

Følgende parametere benyttes av HTTP GET API for innkommende meldinger:

ParameterDescription
fromidTelefonnummer dit meldingen ble sendt, enten i E164-format (f. eks. «+47594400»), et kortnummer (f. eks. «26114»), eller sub-nummeret ved et kortnummer med sub-nummer (PSK-nummer, f. eks. «123456789» for «26114123456789»).
phonenrTelefonnummer til innsenderen i internasjonalformat (f. eks. «004799999999»). I noen tilfeller kan dette inneholde et nummer i nasjonalformat (f. eks. «26114») eller en tekst (f. eks «Front») bestående av inntil 11 tegn.
txtTeksten i meldingen
timeTidspunkt meldingen ble mottatt, unix kode
countnrEn tellefunksjon som teller antall mottatte meldinger per kunde. Denne kan benyttes til å undersøke om man mangler innkommende SMS.
codeFørste ord i meldingteksten. Kodeord blir ofte benyttet for å rute meldinger sendt til et kortnummer til riktig mottaker.

Forventet svar når en melding er vellyket behandlet er teksten:

true

Eksempel på en innkommende melding med HTTP GET API:

https://www.customer.no/innkommende/?fromid=123450000&phonenr=004799999999&txt=Test%20%E6%F8%E5%20%C6%D8%C5&time=1077181484&countnr=157&code=TEST

3      Historikk

v2.20 (06.09.2016): Ny funksjonalitet: UTGÅENDE MELDINGER – BULK


v2.21 (15.03.2017): Oppdatert LEVERINGSSTATUS PÅ UTGÅENDE PUSH MELDINGER med riktig maks antall tegn for feilkode 14. Informasjon om feilkoder 15 og 16 lagt til.

v2.22 (05.05.2017): Duplikatsperre. Nye SMS Gateways vil bli konfigurert med sperre for duplikatmeldinger. Informasjon om feilkode17 lagt til.

v2.23 (09.03.2020): Maks. lengde på meldingstekst økt til 1024 tegn.

v2.24 (29.04.2020)

  • Støtte for HTTP POST av JSON-dokument ved utsendelse
  • Støtte for utsendelse av Unicode-meldinger
  • Støtte for UTF-8 koding når man sender meldinger med HTTP GET
  • Flere eksempler på utsendelse av meldinger
  • Informasjon om feilkoder: 18, 19 og 20
  • HTTP POST JSON API for innkommende meldinger
  • Forbedret beskrivelsen av parametere som benyttes av HTTP GET API for innkommende meldinger

v2.25 (15.12.2021): Ny feilkode når mobilnummeret er svartelistetv2.26 (01.02.2022): Fjerne mobilnummer fra registreringsskjema og tilsvarende beskrivelse av varsling på SMS ved innkommende SMS leveringsfeil. Oppdatere beskrivelse av forventet svar til å dekke både HTTP GET og JSON POST APIer.