Front SMS Gateway API (Produktbeskrivelse)

Front tilbyr SMS Gateway API med et http-basert grensesnitt. Ved å sende HTTP-baserte kommandoer kan kunden sende og motta meldinger via Front sin meldingstjeneste/gateway til en sluttbrukers mobil eller en applikasjon.

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.

Engelsk versjon av produktbeskrivelsen finnes her: gw-productdescription.

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 e-postadresser 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.

Parameter	Beskrivelse	Lovlige verdier	Kommentar
serviceid	Server identifikator	Unik kunde ID	Obligatorisk
password	Passord for gateway	Ingen restriksjoner	Ikke nødvendig når IP-autentisering brukes
phoneno	Telefonnummer til mottaker.	Internasjonalt telefonnr. med landskode (004799999999 eller +4799999999)	Obligatorisk
txt	Meldingen 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 1530 tegn.
fromid	Unik avsender ID	Et tildelt nummer / nummerserie av Front eller tildelt avsendertekst, maks 11 tegn.	Obligatorisk – Unikt nummer for å kunne motta respons eller en tekst.
price	Takserte meldinger	Hele 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
unicode	Tillatt Unicode tekstmeldinger	true, false	Ikke 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.
encoding	Tegnsett benyttet til URL prosentkoding	iso-8859-1, utf8, utf-8	Ikke 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. (Denne parameteren benyttes ikke ved JSON-request, da JSON er alltid UTF-8)
ref	Deres ID eller referanse	Deres meldingsreferanse, maks 100 tegn eller et heltall	Ikke obligatorisk. Hvis ref er inkludert med meldingen, blir ref og phoneno også sendt som parametere ved leveringsstatus
scheduled	Fremtidig tidspunkt for utsendelse	ISO 8601 dato med klokkeslett, f.eks. 2024-01-30T14:40:00Z	Ikke obligatorisk. Må være fremtidig. Standardverdi: umiddelbar utsendelse. UTC benyttes dersom tidssone ikke er angitt.
validity	Gyldighetsperiode i minutter	positivt heltall	Ikke obligatorisk. Standardverdi: en uke i minutter. Hvor lenge operatøren skal forsøke å levere meldingen før den feiler når mobilen er frakoblet mobilnett (avslått, ikke dekning, SIM-kort fjernet, osv.). Operatørens maksimale gyldighetsperiode benyttes når dette er kortere enn angitt verdi.
flash	Send som flashmelding	true, false	Ikke obligatorisk. Standardverdi: false. Hvis true, forsøk å sende melding som flashmelding som vises direkte på hovedskjermen uten brukerinteraksjon. Ikke støttet til alle operatører
protocolid	GSM Protocol Identifier (TP-PID)	0 – 255	Ikke obligatorisk. Standardverdi: 0. Forsøk å sende med GSM Protocol Identifier (TP-PID) som kan benyttes f.eks. til Replace Type 1-7 (65-71)
— EKSTRA PARAMETERE FOR FORHÅNDSGODKJENTE MALER (VALGFRITT) — Se §2.1.3 API for OTP, bestillinger og bookinger
type	Meldingstype	otp, order_confirmation, order_ready, conf_booking, conf_reminder	Ikke obligatorisk. Kan benyttes for å øke levering ved bruk av forhåndsgodkjente avsender og/eller meldingstekst til enkelte land. Ignoreres dersom valgt rute/operatør ikke krever forhåndsgodkjent avsender eller mal.
sendername	Navn på firma eller tjeneste som sender meldingen	Tekst inntil 50 tegn	Obligatorisk kun dersom type er en av order_confirmation, order_ready, conf_booking, conf_reminder, og når forhåndsgodkjent mal aktiveres. Benyttes kun til land som krever forhåndsgodkjent tekstmal.
code	Engangskode / passord	Antall tegn 4-15 Tillatte tegn: A-Z, a-z, 0-9, ! @ # $ % & * – _	Obligatorisk kun dersom type er otp. Benyttes kun til land som krever forhåndsgodkjent tekstmal. For best kompatibilitet med automatisk gjenkjenning av engangskoder på Android og iOS anbefales numeriske koder (0–9) på 4–8 tegn.
username	Brukernavn for engangskode	Tekst inntil 255 tegn. Kan inneholde valgfri tekst (brukernavn, e-post eller annen identifikator). URL (http:// eller https://) er ikke tillatt.	Ikke obligatorisk. Benyttes kun i OTP-meldinger til land som krever forhåndsgodkjent tekstmal. Hvis parameter ikke sendes eller er tom, fjernes tilhørende tekstsegment automatisk fra meldingen.
orderno	Ordrenummer for bestillinger	Tekst inntil 50 tegn. a-z 0-9 – eller _	Ikke obligatorisk. Benyttes kun i bestillingsbekreftelser og hentemeldinger til land som krever forhåndsgodkjent tekstmal.
amount	Totalbeløp for en bestilling	Tekst inntil 50 tegn. 0-9 , . – _ eller mellomrom	Ikke obligatorisk. Benyttes kun i bestillingsbekreftelser til land som krever forhåndsgodkjent tekstmal.
currency	Valutakode eller symbol for en bestilling (NOK, € osv).	Tekst inntil 10 tegn	Ikke obligatorisk. Benyttes kun i bestillingsbekreftelser til land som krever forhåndsgodkjent tekstmal.
orderurl	Lenke til en bestilling	Tekst. Domenet må være forhåndsgodkjent. Kan sendes både som full URL (https://…) eller uten skjema (firmanavn.no/…).	Ikke obligatorisk. Benyttes kun i bestillingsbekreftelser til land som krever forhåndsgodkjent tekstmal.
pax	Antall personer for en booking	Tekst inntil 10 tegn. 0-9 , . eller mellomrom	Ikke obligatorisk. Benyttes kun i bookingbekreftelser og påminnelser til land som krever forhåndsgodkjent tekstmal.
date	Bookingdato	Dato i ÅÅÅÅ-MM-DD format f.eks. 2030-01-31	Ikke obligatorisk. Benyttes kun i bookingbekreftelser og påminnelser til land som krever forhåndsgodkjent tekstmal.
time	Tidspunkt for en booking	Tid i TT:MM eller TT:MM:SS format, f.eks. 18:30 eller 18:30:00	Ikke obligatorisk. Benyttes kun i bookingbekreftelser og påminnelser til land som krever forhåndsgodkjent tekstmal.
datetime	Dato og tid for en booking	ISO 8601 dato med klokkeslett, f.eks. 2030-01-31T18:30:00 eller 2030-01-31T18:30:00+01:00 Merk! Tidssoner blir ikke konvertert.	Ikke obligatorisk. Benyttes kun i bookingbekreftelser og påminnelser til land som krever forhåndsgodkjent tekstmal.

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 på å sende en melding med samtlige parametere:

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,
  "ref": "3d56c6bd-ffcc-49bb-a815-81b21f082606",
  "scheduled": "2024-01-30T13:50:00Z",
  "validity": 60,
  "flash": false,
  "protocolid": 0
}

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

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&validity=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.1.3 API for OTP, bestillinger og bookinger

For å bedre levering av standardmeldinger globalt har Front utvidet vår SMS Gateway med ekstraparametere som muliggjør bruk av forhåndsgodkjent avsender og/eller meldingsmal til land / operatører som krever dette.

Flow:

1. Kunden sender txt + fromid som normalt (valgfritt: type + mal-parametere)

2. Front vurderer land, operatør og valgt rute

3a. Ingen restriksjoner → original melding sendes

3b. Restriksjoner → godkjent mal benyttes

Original txt ignoreres kun i de tilfeller der forhåndsgodkjent mal er påkrevd av rute/operatør.

Viktig: Parameteren "type" er et tillegg til eksisterende API og påvirker kun meldinger sendt til land/ruter som krever forhåndsgodkjent avsender eller tekstmal.

Hvis valgt rute og operatør for mottakernummeret ikke har krav til forhåndsgodkjent avsender eller mal, sendes meldingen alltid slik dere har sendt den (txt + fromid).

Bruk av denne funksjonen er valgfritt. Dersom parameter "type" sendes, kan Front – når det kreves av valgt rute/operatør – benytte forhåndsgodkjent avsender og standardisert meldingsmal i stedet for kundens opprinnelige tekst.

Hvis andre valgfrie parametere ikke benyttes, vil heller ikke teksten til parameter bli med i meldingen. Eksempelvis hvis man ikke benytter parameter "username", at det står blankt eller at parameter ikke er tatt med, så vil heller ikke teksten "Username: " bli inkludert i meldingen. Tekstsegmenter som inneholder manglende parameter blir automatisk fjernet.

Eksempel, mal:

Your code is <code> Username: <username>. Regards <sendername>.

Hvis kun "code" sendes: "Your code is 123456"

NB: Denne funksjonaliteten er beregnet for kunder som ønsker en universell løsning uten å forhåndsregistrere egen trafikk hos operatører i hvert enkelt land.

2.1.3.1 OTP – Engangskode / verifiseringskode

Mal: “Your code is <code> Username: <username> Regards <sendername>»

Eksempel JSON

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Din engangskode er 123456\n\nHilsen Firmanavn AS",
  "type": "otp",
  "code": "123456",
  "sendername": "Firmanavn AS",
  "username": "bruker@eksempel.no"
}

Eksempel melding (kun for rute/operatør i land som krever forhåndsgodkjenning, eller original tekst)

Avsender: FrontOTP

Your code is 123456

Username: bruker@eksempel.no

Regards Firmanavn AS

NB! For OTP-meldinger er "code" påkrevd. Øvrige linjer sløyfes når tilsvarende parameter mangler.

2.1.3.2 Bestillingsbekreftelse

Mal: Order <orderno> received. Total <currency> <amount>. Link: <orderurl> Thank you from <sendername>.

Eksempel JSON

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Takk for handelen hos Firmanavn. Bestillingsnr 123456789, kr 1234,59\nDu finner kvitteringen her:\n tjeneste.no/ordre/123456789",
  "type": "order_confirmation",
  "sendername": "Firmanavn AS",
  "orderno": "123456789",
  "amount": "1,234.59",
  "currency": "NOK",
  "orderurl": "firmanavn.no/123456789"
}

Eksempel melding (kun for rute/operatør i land som krever forhåndsgodkjenning, eller original tekst)

Avsender: FrontOrder

Order 123456789 received. Total NOK 1,234.59. Link: firmanavn.no/123456789

Thank you from Firmanavn AS

NB! For en bestillingsbekreftelse er "sendername" påkrevd. Andre deler av teksten sløyfes når tilsvarende parameter mangler.

2.1.3.3 Hentemelding

Mal: Hello! Your order <orderno> is ready for pick up. Best regards, <sendername>.

Eksempel JSON

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Bestillingsnr 123456789 er klar og kan hentes. Mvh Firmanavn AS",
  "type": "order_ready",
  "sendername": "Firmanavn AS",
  "orderno": "123456789"
}

Eksempel melding (kun for rute/operatør i land som krever forhåndsgodkjenning, eller original tekst)

Avsender: FrontOrder

Hello! Your order 123456789 is ready for pick up. Best regards, Firmanavn AS.

NB! For en hentemelding er "sendername" påkrevd. Bestillingsnummer sløyfes når tilsvarende parameter mangler.

2.1.3.4 Booking / bordbestilling

Mal: Your reservation for <pax> at <sendername> on <date> at <time> is confirmed. Welcome!

Eksempel JSON med datetime

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Takk for din reservasjon den 31.01.2030 kl 1915 for 4 personer. Mvh Firmanavn AS",
  "type": "conf_booking",
  "sendername": "Firmanavn AS",
  "pax": 4,
  "datetime": "2030-01-31T19:15:00+01:00"
}

Eksempel JSON med date og time

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Takk for din reservasjon den 31.01.2030 kl 1915 for 4 personer. Mvh Firmanavn AS",
  "type": "conf_booking",
  "sendername": "Firmanavn AS",
  "pax": 4,
  "date": "2030-01-31",
  "time": "19:15"
}

Eksempel melding (kun for rute/operatør i land som krever forhåndsgodkjenning, eller original tekst)

Avsender: FrontConf

Your reservation for 4 at Firmanavn AS on 31 January 2030

at 19:15 is confirmed. Welcome!

NB! For en booking er "sendername" påkrevd. Andre deler av teksten sløyfes når tilsvarende parametere mangler. Merk at tidssone ikke konverteres; benytt lokaltid, ikke UTC. Hvis både datetime og date/time sendes, benyttes datetime.

2.1.3.5 Booking påminnelse

Mal: We look forward to seeing your party of <pax> on <date> at <time>. Please contact us if there are changes. See you at <sendername>!

Eksempel JSON med datetime

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Vi minner om din reservasjon den 31.01.2030 kl 1915 for 4 personer. Dere har bordet til klokken 21:15. Ta kontakt om det er noen endringer. Vi sees, hilsen oss på Firmanavn AS",
  "type": "conf_reminder",
  "sendername": "Firmanavn AS",
  "pax": 4,
  "datetime": "2030-01-31T19:15:00+01:00"
}

Eksempel JSON med date og time

{
  "serviceid": 3,
  "fromid": "Firmanavn",
  "phoneno": "+4799999999",
  "txt": "Vi minner om din reservasjon den 31.01.2030 kl 1915 for 4 personer. Dere har bordet til klokken 21:15. Ta kontakt om det er noen endringer. Vi sees, hilsen oss på Firmanavn AS",
  "type": "conf_reminder",
  "sendername": "Firmanavn AS",
  "pax": 4,
  "date": "2030-01-31",
  "time": "19:15"
}

Eksempel melding (kun for rute/operatør i land som krever forhåndsgodkjenning, eller original tekst)

Avsender: FrontConf

We look forward to seeing your party of 4 on 31 January 2030 at 19:15. Please contact us if there are changes. See you at Firmanavn AS!

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.

Respons	Beskrivelse
errorcode=0	OK (Melding sendt)
errorcode=1	Ugyldig mobilnummer
errorcode=2	Melding sendt fra illegal IP adresse
errorcode=3	Ugyldig fromid
errorcode=4	Ugyldig takstklasse SMS
errorcode=5	Ingen resterende SMS meldinger på konto
errorcode=6	Ikke tilgang til taksert SMS
errorcode=7	Kontoen er sperret av Front, eller feil serviceid
errorcode=8	serviceid er blank/parameter mangler
errorcode=9	phoneno er blank/parameter mangler
errorcode=10	txt er blank/parameter mangler
errorcode=11	fromid er blank/parameter mangler
errorcode=12	Ugyldig mobilnummer for taksert SMS
errorcode=13	Ugyldig passord
errorcode=14	Meldingen er for lang (maks 1530 tegn)
errorcode=15	Taksert melding er for lang (maks 160 tegn). Gjelder kun takserte meldinger (price > 0)
errorcode=16	txt 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=17	Duplikatmelding. Melding med samme fromid, phoneno og txt sendt i løpet av 120 sekunder.
errorcode=18	Mangler kryptering. Bruk https i stedet for http.
errorcode=19	Ugyldig verdi for encoding-parameter
errorcode=20	unicode må være "true" eller "false"
errorcode=21	Mobilnummer er svartelistet. Nummeret er kjent som ugyldig for mottak av SMS eller er tidligere benyttet i forbindelse med misbruk.
errorcode=22	flash må være "true" eller "false"
errorcode=23	protocol id må være et heltall mellom 0 og 255
errorcode=24	validity må være et positivt heltall
errorcode=25	ref kan ikke overskride 100 tegn
errorcode=26	scheduled må være en fremtidig dato i ISO 8601-format med klokkeslett
errorcode=27	gruppe må være navnet på en kontaktgruppe som inneholder minst én kontakt
errorcode=28	type må være en av "otp", "order_confirmation", "order_ready", "conf_booking", "conf_reminder"
errorcode=29	code er påkrevd for otp-meldinger og må være 4-15 tegn
errorcode=30	sendername mangler eller ugyldig
errorcode=31	orderno ugyldig
errorcode=32	amount ugyldig
errorcode=33	currency ugyldig
errorcode=34	orderurl ugyldig
errorcode=35	pax ugyldig
errorcode=36	date ugyldig
errorcode=37	time ugyldig
errorcode=38	datetime ugyldig
errorcode=39	username ugyldig

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.

Parameter	Beskrivelse	Lovlige verdier	Kommentar
status	Ny status på SMS	-1, 4, 5	Se under
origid	ID Referansenummer	Samme siffer som bekreftelse ID’en når meldingen ble sendt	Unikt nummer for hver enkelt tekstmelding
ref	Deres referanse	tekst inntil 100 tegn	ref som ble angitt da meldingen ble sendt
phoneno	Mobilnummeret meldingen ble sendt til	E164 mobilnummer	Kun inkludert når ref er inkludert

Eksempel på status: https://kunde.no/dr?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 teleoperatø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:

Parameter	Beskrivelse	Lovlige verdier	Kommentar
serviceid	Server identifikator	Unik kunde ID	Obligatorisk; nummer
phoneno	Mobilnummer til mottakere	Internasjonalt telefonnr. med landskode 004799999999	Ikke obligatorisk; string array. Det er obligatorisk å bruke enten parameter "phoneno" eller "group"
group	Kontaktgruppenavn	Nøyaktig navn på en kontaktgruppe som inneholder minst én aktiv kontakt.	Ikke obligatorisk; string. Det er obligatorisk å bruke enten parameter "phoneno" eller "group"
txt	Meldingen 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 1530 tegn.
fromid	Unik avsender ID	Et tildelt nummer / nummerserie av Front eller tildelt avsendertekst, maks 11 tegn	Obligatorisk; string. Unikt nummer for å kunne motta respons eller en tekst.
unicode	Tillatt Unicode tekstmeldinger	true, false	Ikke 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.
ref	Deres ID eller referanse	Deres meldingsreferanse, maks 100 tegn eller et heltall	Ikke obligatorisk. Hvis ref er inkludert med meldingen, blir ref og phoneno også sendt som parametere ved leveringsstatus
scheduled	Fremtidig tidspunkt for utsendelse	ISO 8601 dato med klokkeslett, f.eks. 2024-01-30T14:40:00Z	Ikke obligatorisk. Må være fremtidig. Standardverdi: umiddelbar utsendelse. UTC benyttes dersom tidssone ikke er angitt.
validity	Gyldighetsperiode i minutter	positivt heltall	Ikke obligatorisk. Standardverdi: en uke i minutter. Hvor lenge operatøren skal forsøke å levere meldingen før den feiler når mobilen er frakoblet mobilnett (avslått, ikke dekning, SIM-kort fjernet, osv.). Operatørens maksimale gyldighetsperiode benyttes når dette er kortere enn angitt verdi.
flash	Send som flashmelding	true, false	Ikke obligatorisk. Standardverdi: false. Hvis true, forsøk å sende melding som flashmelding som vises direkte på hovedskjermen uten brukerinteraksjon. Ikke støttet til alle operatører
protocolid	GSM Protocol Identifier (TP-PID)	0 – 255	Ikke obligatorisk. Standardverdi: 0. Forsøk å sende med GSM Protocol Identifier (TP-PID) som kan benyttes f.eks. til Replace Type 1-7 (65-71)

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 bulk-request med samtlige parametere:

{
  "serviceid": 1234,
  "phoneno": ["004799999999", "004799999998"],
  "txt": "Test 🤣",
  "unicode": true,
  "fromid": "Mitt Firma",
  "ref": "3d56c6bd-ffcc-49bb-a815-81b21f082606",
  "scheduled": "2024-01-30T13:50:00Z",
  "validity": 60,
  "flash": false,
  "protocolid": 0
}

Eksempel på respons:

{
  "errorcode": 0,
  "description": "OK",
  "invalidPhoneno": [],
  "duplicatePhoneno": []
}

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 med ”Modul for toveis”)

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:

Parameter	Type	Description
id	Number	Front's unik meldingidentifikator
to	String	Telefonnummer 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").
from	String	Telefonnummer 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.
text	String	Meldingsteksten. 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.
sent	String	Tidspunktet melding ble sendt eller ble mottatt av Front i ISO 8601-format (f. eks. "2020-12-31T23:59:59Z")
counter	Number	En tellefunksjon som teller antall mottatte meldinger per kunde. Denne kan benyttes til å undersøke om man mangler innkommende SMS.
keyword	String	Første ord i meldingteksten. Kodeord blir ofte benyttet for å rute meldinger sendt til et kortnummer til riktig mottaker.
files	Array	Filene 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:

Parameter	Type	Description
id	Number	Front's unik identifikator for filen
contentType	String	Filens MIME-type som spesifisert i MMSen
fileName	String	Filens navn som spesifisert i MMSen.
fileData	String	Filens 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": "PD94bWwgdmVyc2lvbj0iMS4wIj48c21pb..."
  },
  {
    "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/w4PCoAAQSkZJRgABAQ..."
  }]
}

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:

Parameter	Description
fromid	Telefonnummer 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").
phonenr	Telefonnummer 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.
txt	Teksten i meldingen
time	Tidspunkt meldingen ble mottatt, unix kode
countnr	En tellefunksjon som teller antall mottatte meldinger per kunde. Denne kan benyttes til å undersøke om man mangler innkommende SMS.
code	Fø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 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.

v3.05 (01.03.2026): API for engangskoder, bestillinger og bookinger (valgfrie tilleggsparameter)

Front SMS Gateway API (Produktbeskrivelse)

1 Konto

1.1 Brukere

1.2 Oppsett av SMS Gateway API

2 PARAMETER INDEKS

2.1 UTGÅENDE MELDINGER

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

2.1.2 Send melding – Eksempler på HTTP GET

2.1.3 API for OTP, bestillinger og bookinger

2.1.3.1 OTP – Engangskode / verifiseringskode

2.1.3.2 Bestillingsbekreftelse

2.1.3.3 Hentemelding

2.1.3.4 Booking / bordbestilling

2.1.3.5 Booking påminnelse

2.2 FEILKODER PÅ UTGÅENDE MELDINGER

2.3 LEVERINGSSTATUS PÅ UTGÅENDE PUSH MELDINGER

2.4 UTGÅENDE MELDINGER – BULK

2.5 INNKOMMENDE MELDINGER (Kun med ”Modul for toveis”)

2.5.1 INNKOMMENDE MELDINGER – HTTP POST JSON API

2.5.2 INNKOMMENDE MELDINGER – HTTP GET API

3 Historikk

Prøv vår kraftige plattform for SMS-tjenester gratis.

Adresse

Telefon

Org. nr.