SMS gateway API

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.

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.

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

1{
2    «serviceid»: 3,
3    «fromid»: «26114123450000»,
4    «phoneno»: «004799999999»,
5    «txt»: «Test æøå ÆØÅ»,
6    «unicode»: false
7}

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

POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json

1{
2    «serviceid»: 3,
3    «fromid»: «26114123450000»,
4    «phoneno»: «004799999999»,
5    «txt»: «Test 🤣»,
6    «unicode»: true
7    }

Eksempel på å sende en melding med samtlige parametere:

POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json

 1{
 2    «serviceid»: 3,
 3    «fromid»: «26114123450000»,
 4    «phoneno»: «004799999999»,
 5    «txt»: «Test 🤣»,
 6    «unicode»: true,
 7    «ref»: «3d56c6bd-ffcc-49bb-a815-81b21f082606»,
 8    «scheduled»: «2024-01-30T13:50:00Z»,
 9    «validity»: 60,
10    «flash»: false,
11    «protocolid»: 0
12}

Eksempel svar på vellykket request:

1{
2    «id»: 145099,
3    «errorcode»: 0,
4    «description»: «OK»
5}

Eksempel svar på en request som feilet:

1{
2    «id»: 0,
3    «errorcode»: 1,
4    «description»: «Invalid mobile number»
5}

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

Eksempel på å sende en melding med samtlige parametere:
https://www.pling.as/psk/push.php?serviceid=1234&encoding=utf8&unicode=true&phoneno=004799999999&fromid=26114123450000&txt=Test%20%F0%9F%A4%A3&ref=987654321&valdity=60&flash=false&protocolid=0&scheduled=2024-01-30T15%3A30%3A00Z

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.

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.

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

Eksempel på status med ref: https://kunde.no/dr?status=4&origid=145099&ref=abc&phoneno=%2B4799999999

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:

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:

1{
2    «serviceid»: 1234,
3    «phoneno»: [«004799999999», «004799999998»],
4    «txt»: «Test æøå ÆØÅ»,
5    «fromid»: «Mitt Firma»
6}

Eksempel bulk-request med emoji:

1{
2    «serviceid»: 1234,
3    «phoneno»: [«004799999999», «004799999998»],
4    «txt»: «Test 🤣»,
5    «unicode»: true,
6    «fromid»: «Mitt Firma» 
7}

Eksempel bulk-request med samtlige parametere:

 1{
 2    «serviceid»: 1234,
 3    «phoneno»: [«004799999999», «004799999998»],
 4    «txt»: «Test 🤣»,
 5    «unicode»: true,
 6    «fromid»: «Mitt Firma»,
 7    «ref»: «3d56c6bd-ffcc-49bb-a815-81b21f082606»,
 8    «scheduled»: «2024-01-30T13:50:00Z»,
 9    «validity»: 60,
10    «flash»: false,
11    «protocolid»: 0
12}

Eksempel på respons:

1{
2    «errorcode»: 0,
3    «description»: «OK»,
4    «invalidPhoneno»: [],
5    «duplicatePhoneno»: []
6}

Merk at responsen inneholder ikke referansenummer (ID) for meldingene som blir sendt. Dersom man ønsker å motta leveringsstatus, må man inkludere «ref» på utgående bulkmeldinger slik at man mottar leveringsstatus med «ref» og «phoneno» for å identifisere meldingen

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:

*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:

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:

 1{
 2    «id»: 999999,
 3    «to»: «26114»,
 4    «from»: «+479999999»,
 5    «text»: «Test 123»,
 6    «sent»: «2019-12-31T23:59:59Z»,
 7    «counter»: 7166,
 8    «keyword»: «TEST»,
 9    «files»: []
10}

Eksempel MMS sendt til et mobilnummer:

 1{
 2    «id»: 999999,
 3    «to»: «+4759440000»,
 4    «from»: «+479999999»,
 5    «text»: «Test 123»,
 6    «sent»: «2019-12-31T23:59:59Z»,
 7    «counter»: 7166,
 8    «keyword»: «TEST»,
 9    «files»: [
10        {
11            «id»: 4747,
12            «contentType»: «text/xml;Name=smil.xml;Charset=UTF-8»,
13            «fileName»: «smil.xml»,
14            «fileData»: «PD94bWwgdmVyc2lvbj0iMS4wIj48c21pb…»
15        },
16        {
17            «id»: 4748,
18            «contentType»: «text/plain;Name=text_75329.txt;Charset=UTF-8»,
19            «fileName»: «text_175329.txt»,
20            «fileData»: «VGVzdCAxMjM=»
21        },
22        {
23            «id»: 4749,
24            «contentType»: «image/jpeg;Name=image01.jpg»,
25            «fileName»: «image01.jpg»,
26            «fileData»: «w4PCv8ODwpjDg8K/w4PCoAAQSkZJRgABAQ…»
27        }
28    ]
29}

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:

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 svartelistet

v2.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.

v3.02 (11.07.2023)

• Legg til ref, scheduled, validity, flash og protocolid parametere på utgående meldinger.
• Legg til ref og phoneno på leveringsstatus (kun når ref er spesifisert ved utsendelse).

v3.03 (17.08.2023): Maks. lengde på meldingstekst økt til 1530 tegn.

v3.04 (05.06.2024): Lagt til gruppe for utgående bulkmeldinger.