SMS Gateway

SMS


Introduktion RESTful

Kom igång

Vårt SMS API låter dig koppla upp dina webbtjänster och applikationer mot mobiloperatörer världen över och är designat för att hantera höga volymer av SMS-trafik och lämpar sig perfekt för bland annat större grupputskick vid exempelvis marknadsföring, men även singelutskick för automatiserade SMS-larm etc.

Skapa konto

För att komma igång behöver du först och främst ett konto, vilket du kan skapa här.

När du skapat ditt konto loggar du in i vår användarportal för att få tillgång till dina autentiseringsuppgifter, som beskrivs närmare i steget nedan.

API Endpoint

Bas-url:en för endpoints enligt API-referens i vårt RESTful API är: https://api.ip1sms.com

Alla requester måste göras genom HTTPS.

Autentisering

Alla våra API endpoints är skyddade av autentisering via HTTP Bearer tokens, som vi tillhandahåller. Varje konto du skapar kan ha flera nycklar med olika restriktioner på tillåtna IP-adresser som du själv anger. API-nycklarna hanterar du i vår Användarportal.

1. Logga in i användarportalen med din iP.1-användare som skapades i samband med kontoregistrering.

2. gå till Konton (se bild)

3. tryck på överblick och gå till filken API-nycklar (se bild)

4. Klicka på Lägg till ny nyckel, ge nyckeln ett namn och sätt eventuell nätverksintervall om du vill begränsa nyckeln till ett specifikt IP-adress-spann. Slutför genom att trycka på skapa nyckel.

Paginering

Alla endpoints under /v2/ som returnerar en samling av dokument (Batcher, meddelanden etc.) har paginering aktiverat. Vi använder oss av databas-stilen av paginering med start, limit och order som parameternamn. start, limit och order är sätt till 0, 50 och ASC i respektive ordning, men du kan ändra dem genom att ange dem som query-parametrar när du gör ett HTTP-anrop på detta vis: ?start=0&limit=200&order=DESC

Du kommer också ta emot ett länk-huvud som innehåller paginerings-information.

                        
Link: <https://api.ip1sms.com/v2/batches?start=201&limit=100&order=ASC> rel="next",
<https://api.ip1sms.com/v2/batches?start=4901&limit=100&order=ASC> rel="last"
                        
                    

Detta exempel innehåller radbryt för läsbarhetens skull.

Möjliga värden för rel är följande:

Namn Beskrivning
self Länkrelationen för den begärda resultatsidan.
first Länkrelationen för den första resultatsidan.
prev Länkrelationen för den omedelbart föregående resultatsidan.
next Länkrelationen för den omedelbart nästa resultatsidan.
last Länkrelationen för den sista resultatsidan.

Registrera avsändare

Unik för REST SMS V2

Innan du kan använda vårt API behöver du registrera en eller flera avsändare. Du kan ha så många avsändare du vill och du kan sedan avregistrera de du inte behöver.

Läs registrerade avsändare

Endpoint: GET /v2/me/senders

Denna endpoint listar alla dina registrerade avsändare som är knutna till ditt konto, sorterade i alfabetisk ordning.

Registrera en avsändare

Endpoint: PUT /v2/me/senders/{sender}

Denna endpoint tillåter dig att registrera en ny avsändare.

Avregistrera en avsändare

Endpoint: DELETE /v2/me/senders/{sender}

Den här endpointen låter dig avregistrera en avsändare. Outputen är densamma som vid registrering av avsändare.

Responsdata-typ
                          
{
    "sender": "TestNOS",
    "created": "2018-10-23T17:43:19Z"
}
                        
                    

Du kan också registrera och ta bort avsändare via vår webbapplikation Capacity SMS.


Skicka SMS


Endpoint

Endpoint: POST /v2/batches

Request data type

I sin kärna behöver enpointen för Skicka SMS följande värden:

                            
{
    "sender": "TestNOS",
    "recipients":[
        "456189040623",
        "175368927054",
        "392094880589",
        "568798567631"
    ],
    "body": "A very nice message",
}
                            
                        

Dessa värden kommer att direkt att skicka ett meddelande till varje mottagare med meddelande-texten "A very nice message". Avsändaren på meddelandet kommer att vara "Testnos"

sender

Ett Anrop kommer att avslås om Sender:

  • Är längre än 15 tecken
  • Inte matchar regex [0-9A-Za-z]{1,11} eller om den inte följer standarden E164

Ett meddelande kanske inte når mottagaren om:

  • Operatören där mottagare står registrerad inte stöder avsändaren.
recipient

Ett Anrop kommer att avslås om Recipient:

  • Är längre än 15 siffror
  • Innehåller andra tecken än siffror

Varje telefonnummer analyseras och valideras där resultatet visas som en status för meddelandet. Om detta steg misslyckas skickas inte meddelandet.

body

Ett anrop kommer att misslyckas om Body:

  • Är null, tomt eller enbart består av blanksteg
  • Är längre än 2000 tecken
extended

Vissa kan kräva ytterligare funktioner som mallar, schemalagd sändning, leveransrapporter och att ställa in sin egen referens.

                        
{
    "sender": "TestNOS",
    "recipients":{
        "456189040623": {
            "sign": "sent by Bob"
        },
        "175368927054": {},
        "392094880589": {},
        "568798567631": {},
        "default":{
            "sign": " sent by iP.1"
        }
    },
    "body": "A very nice message{sign}",
    "type": "sms",
    "datacoding": "gsm",
    "priority": 1,
    "deliveryWindows": [
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        },
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        }
    ],
    "deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
    "reference": "A client reference",
    "tags": ["marketing", "ux", "design"]
}
                        
                    
recipients - templating

För att använda vårt mallsystem måste du konvertera din tidigare mottagar-array till en dictionary av dictionaries. Övrenivå-nyckeln är mottagarens MSISDN (telefonnummer). Andranivå-nyckeln eftersöks sedan i texten och ersätts med andranivå-värdet.

type

Det finns två typer som ett SMS kan ha: sms och flash. sms är ett vanligt SMS medan flash är ett meddelande som visas en gång på enheten och sedan raderas. Standard-typen är sms.

datacoding

Det finns två typer tillgängliga:

  • gsm är en 7-bitars teckenuppsättning som gör att ett SMS kan vara 160 tecken långt men med ett begränsat antal tecken att välja mellan.
  • ucs är en 2-byte teckenuppsättning som tillåter alla tecken (såsom emoji, kanji etc) men sänker teckenbeloppet till 70 tecken per SMS.

Om gsm är satt, kommer alla meddelanden som kräver den utökade teckenuppsättningen av ucs att nekas från att skickas. Standard är ucs. Mer information om GSM och UCS finns i vår ordlista.

priority

I fall det är ett viktigt att ditt meddelande levereas snabbt och ohindrat från andra i meddelande-kön kan du sätta en högre prioritet på ditt meddelande. Observera att om du sätter en högre prioritet så ökar priset per SMS med 10 öre om du använder ett svenskt konto, eller € 0.01 om du använder ett internationellt konto. Prioritet 1 är standard värdet och även det lägsta tillgängliga värdet, medan prioritet 2 är det högsta tillgänglia värdet. Om prioritet sätts så är 1 och 2 är de enda tillåtna värdena.

deliveryWindows

I de fall där det är nödvändigt att schemalägga ett utskick finns möjligheten att göra så genom våra leverans-tidsfönster.

Du kan ha så många fönster du vill. Detta tillåter dig att skicka meddelanden under specifika tider över flera dagar, exempelvis varje dag mellan 10:00 och 10:15 på arbetsdagar.

Tolkning
  • null i fältet opens kommer att ersättas med aktuellt datum och tid
  • Om closes är null kommer fältet att sättas till 7 dagar (168 timmar) efter fältet opens

Anropet kommer att avslås om tidsfönster överlappar varandra.

Om inget fönster anges kommer det automatisk att skapas ett fönster med tillämpade regler som nämns ovan.

deliveryReportUrl

Om detta tillhandahålls kommer rapporter med statusuppdateringar att skickas till denna URL genom metoden POST. Dessa rapporter är separerade för varje mottagare i ett meddelande och för varje status-uppdatering. Om du vill läsa mer om dessa rapporter kan du göra det på avsnittet Leveransrapporter.

reference

Detta är en egenskap som tillåter användaren att sätta ett eget ID eller referens om lagring av standard-genererade ID´n ogillas.

Restriktioner
  • Får bestå av max 40 tecken
  • Får inte bestå av en tom string, eller blanksteg
tags

En array av taggar som används för att kategorisera eller sortera bland dina bastcher. När du listar dina batcher kan du filtrera efter dessa.

Respons

Om anropet blir accepterat kommer API:et att returnera en sammanfattning för batchen, som sedan går att hitta genom den specifierade platsen som anges i batchens location-header. Detta kan du läsa mer om i avsnitet Läs Batcher.

Vi returnerar våra API-svar innan vi har säkerställt att kontots finannsiella täckning har bekräftats, vilket betyder att en pris-sammanfattning kan utebli.


Lista Batcher

Lista en samling av batcher

Endpoint: GET /v2/batches

Denna endpoint kommer att ge dig en samling av batcher, enligt batch definition nedan. Observera att messageSummary och priceSummary enbart är tillgänglig i endpointen för enskilda batcher. Batcher listas i kronologisk ordning.

Läs enskilda batcher

Endpoint: Get /v2/batches/{batchId}

Den här endpointen kommer att lista en enskild batch, som innehåller total-priset för batchen, samt en summering av status för batchens meddelanden.

Responsdata-typ
                        
{
    "id": "5bc86b6e85c7209830f96936",
    "sender": "46101606060",
    "body": "Hi my name is {name}",
    "owner": "ip1-XXXXX",
    "type": "flash",
    "datacoding": "gsm",
    "priority": 1,
    "templated": true,
    "priceSummary": {
        "total": 0.125,
        "currency": "eur",
        "average": 0.0416
    },
    "messageSummary": {
        "101": {
        "messages": 43,
        "sms": 86
        },
        "102": {
        "messages": 3,
        "sms": 6
        },
        "201": {
        "messages": 142,
        "sms": 284
        }
    },
    "deliveryWindows": [
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        },
        {
            "opens": "ISO-8601 string",
            "closes": "ISO-8601 string"
        }
    ],
    "deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
    "reference": "A client reference",
    "tags": ["marketing", "auth", "etc"],
}
                        
                    
sender

Avsändaren som används för ett eller flera meddelanden.

body

Den ursprungliga bodyn som skickas, före mallar har tillämpats, enligt den ursprungliga requesten.

owner

Kontonumret för SMS-kontot som står som ägare till batchen.

type

Det finns två typer som ett SMS kan ha: sms och flash. sms är ett vanligt SMS medan flash är ett meddelande som visas en gång på enheten och sedan raderas. Standard-typen är sms.

datacoding

Specifierar det största setet datacoding som är tillåtet i batchen

priority

I fall det är ett viktigt att ditt meddelande levereas snabbt och ohindrat från andra i meddelande-kön kan du sätta en högre prioritet på ditt meddelande.

Observera att om du sätter en högre prioritet så ökar priset per SMS med 10 öre om du använder ett svenskt konto, eller € 0.01 om du använder ett internationellt konto.

Prioritet 1 är standard värdet och även det lägsta tillgängliga värdet, medan prioritet 2 är det högsta tillgänglia värdet. Om prioritet sätts så är 1 och 2 är de enda tillåtna värdena.

templated

Om templating användes i batchen eller inte.

priceSummary

priceSummary.total Det totala priset för batchen. Detta värde kan ändras om meddelanden avvisas av nästa operatör uppströms, i vilket fall betalningen för det specifika meddelandet kommer att annulleras.

priceSummary.currency Vilken valuta total och average anges i.

priceSummary.average Genomsnittspriset för ett enskilt meddelande i batchen. Observera att ett meddelande skiljer sig från SMS eftersom ett meddelande kan kräva flera SMS.

messageSummary

Detta är en dictionary där nyckeln är en statuskod och värdet är en count över hur många meddelanden (och deras motsvarande SMS-segment) som har den statuskod som senast lagts till. För mer information om våra statuskoder för meddelanden, se avsnittet om statuskoder.

deliveryWindows

Om det finns ett behov av att planera ett utskick i framtiden finns det möjlighet att göra det med våra leveransfönster. Dessa är de aktuella leveranstidfönstren för specifierad batch.

deliveryReportUrl

Om detta tillhandahålls kommer rapporter med statusuppdateringar att skickas till denna URL genom metoden POST. Dessa rapporter är separerade för varje mottagare i ett meddelande och för varje status-uppdatering. Om du vill läsa mer om dessa rapporter kan du göra det i avsnittet för Leveransrapporter.

reference

Detta är en egenskap som tillåter användaren att sätta ett eget ID eller referens om lagring av standard-genererade ID´n ogillas.

tags

En array av taggar som används för att kategorisera eller sortera bland dina bastcher. När du listar dina batcher kan du filtrera efter dessa.


Lista Meddelanden

När du listar meddelanden är det alltid i kontexten av en batch. Ett meddelande kan inte existera utanför en batch, därför är alltid ett meddelande placerat hierarkiskt underordnat en batch.

Lista en samling av meddelanden

Endpoint: Get /v2/batches/{batch}/messages

Denna endpoint förser dig med alla meddelanden i en batch med senaste tillhörande leveransrapporter enligt responsdata-typen nedan. Sorterad efter skapad datum, kronologisk ordning.

Lista ett enskilt meddelande

Endpoint: Get /v2/batches/{batch}/messages/{messageId}

Denna endpoint förser dig med ett enskillt meddealnde, med full historik över meddelandets leveransrapporterm enligt responsdata-typen nedan.

Responsdata-typ

Förutom att lista batchen kan du också titta på specifika meddelanden.

                        
{
    "id": "5bc86b6e85c7209830f96936",
    "batchId": "5bcf4324ee47dee41a9dbb13",
    "owner": "ip1-XXXXX",
    "sender": "TestNOS",
    "recipient": "175368927054",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"sms",
    "datacoding": "gsm",
    "priority": 1,
    "price": 0.0416,
    "currency": "eur",
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": "201",
            "duration": 0
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "reference": "A client reference",
    "mcc": "431",
    "mnc": "20"
}
                        
                    
id

Ett unikt id för ett detta specifika meddelande.

batchId

Ett id för samtliga meddelanden som skickades i samma request som detta specifika meddelande.

owner

SMS-kontots ID, ägare för det specifika meddelandet.

direction

Talar om ifall det är ett utgående eller inkommande meddelande

mt en akronym för mobile terminated (Utgående). mo (Inkommande) en akronym för mobile originated.

segments

I fall meddelandet består av fler tecken än teckengränsen för ett SMS kommer meddelandet att delas upp i flera SMS, även kallat konkatenerade SMS. Den här egenskapen indikerar om hur många SMS som behövs för att kunna skicka meddelandet

datacoding

Anger det minsta datakodningsschema som behövs för att skicka meddelandet i fråga. Om meddelandetexten innehåller tecken utanför den angivna datakodningen skickas inte meddelandet, vilket den senaste statuskoden ska visa. Detta kan skilja sig från batchens datakodning.

priority

Meddelandets prioritet. Prioritet 1 är standardvärdet och samtidigt den lägsta prioritet som tillhandahålls. Prioritet 2 är den högsta prioriteten.

price
Hela meddelandets pris. Vill du veta priset för ett enskilt SMS i ett meddelande, kan du dela meddelandets pris med antalet segment.
currency

Vilken valuta som meddelandets pris använder.

status

En array bestående av statusuppdateringar.

  • status[].created
    • När statusen lades till
  • status[].code
    • Den specifika statuskoden. Fler koder kan läggas till i framtiden
  • status[].duration
    • Talar om ifall det är den slutgiltiga statusen, eller om det kan tillkomma fler i framtiden.

Om du begär en samling av meddelanden ges endast den senaste statusen. Om du däremot begär ett specifikt meddelande kommer hela statushistoriken att ges. För mer information om våra statuskoder för meddelanden, se vårt avsnitt om statuskoder.

modified

När SMS:et senast uppdaterades

reference

Detta är en egenskap som tillåter användaren att sätta ett eget ID eller referens om lagring av standard-genererade ID´n ogillas.

mcc

Lands-delen av bladoperatören kan specificeras här om den tillhandahålls av uppströms-bäraren.

MCC är en akronym för Mobile Country Code

mnc

Nätverks-delen av bladoperatören kan specificeras här om den tillhandahålls av uppströms-bäraren.

MCC är en akronym för Mobile Network Code


Konversationer

Läs meddelanden eller en summering av meddelanden gällande specifika deltagare. Detta kan exempelvis innebära konversationer mellan dig och en specifik kund.

Meddelanden

Läs meddelanden till och/eller från en tillhandahållen deltagare.

Den returnerade datan är en paginerad lista av samma typ som visas i avsnitet för Läsa Meddelanden. Sorterad kronologiskt efter skapad datum.

  • Alla meddelanden: GET /v2/conversations/{participant}
  • Utgående meddelanden: GET /v2/conversations/{participant}/mt
  • Inkommande meddelanden: GET /v2/conversations/{participant}/mo
participant

Avsändare för den deltagare vars meddelanden är listade.

Sammanfattning

Förutom att läsa meddelanden till och ett specifikt MSISDN (Mobilnummer) tillhandahåller vi också en endpoint som ger dig en aggregerad summering för meddelanden separerat mellan mt och mt

Endpoint: GET /conversations/{participant}/summary

                        
{
    "participant": "46734487112",
    "totalMessageCount": 387,
    "totalSmsCount": 774,
    "mobileTerminatedMessages": {
        "101": {
            "messages": 43,
            "sms": 86
        },
        "102": {
            "messages": 3,
            "sms": 6
        },
        "201": {
            "messages": 142,
            "sms": 284
        }
    },
    "mobileOriginatedMessages": {
        "201": {
            "messages": 199,
            "sms": 398
        }
    }
}
                        
                    
participant

En deltagare är antingen ett MSISDN (Mobilnummer) eller en alfanumerisk avsändare (Textavsändare). Detta fält talar vilken typ av deltagare det handlar om. A participant is either an MSISDN or an alphanumeric sender. This field tells what participant the summary is about.

totalMessageCount

Den totala mängden meddelanden kopplade till deltagaren.

totalSmsCount

Den totala mängden SMS-segment kopplade till deltagaren.

mobileTerminatedMessages

En summering av meddelanden som skickats till deltagaren. Summeringen består av en dictionary där nyckelen är en statuskod och värdet är en count över hur många meddelanden (och meddelandets respektive SMS-segment) som har specifierad statuskod och som den senast tillagda statusen.

mobileOriginatedMessage

En summering av meddelanden som skickats från deltagaren. Summeringen består av en dictionary där nyckelen är en statuskod och värdet är en count över hur många meddelanden (och meddelandets respektive SMS-segment) som har specifierad statuskod och som den senast tillagda statusen.


Ta emot leveransrapporter

Om en URL för leveransrapporter har angetss när en batch skapas, kommer rapporter över statusuppdateringar att skickas till den URL så fort de finns tillgängliga. Innehållet i dessa rapporter är beskrivna nedan.

Systemet skickar ut rapporter genom metoden POST och förväntar sig ett 200 OK i respons om rapporten tagits emot korrekt. Om någon responsen består av en annan status (exempelvis en error status) kommer ett nytt försök att göras vid ett senare tillfälle. Dessa omförsök repeteras med 10 minuters mellanrum till ett 200 OK har tagits emot, upp till 10 gånger. När dessa 10 försök har paserat utan en lyckad status kommer rapporten att raderas.

Report Payload
                        
{
    "messageId": "5c613848879973045cf39ac4",
    "batchId": "5c613848879973045cf39ac3",
    "recipient": "456189040623",
    "code": "102",
    "duration": 0,
    "created": "ISO-8601 string",
    "segments": 2,
    "price": 0.082,
    "currency": "eur",
    "reference": "A client reference"
}
                        
                    
messageId

Ett unikt ID för det specifika meddelandet.

batchId

Ett id för batchens meddelande som skickats i samma request som det specifika meddelandet.

recipient

Meddelandets mottagare

code

Den ny statuskoden för meddelandet. För mer information om våra statuskoder, se avsnittet om statuskoder.

duration

Visar om meddelandets status är permanent/slutlig. Om så är fallet kommer detta vara den sista rapporten som skickas gällande detta meddelande.

created

När statusuppdateringen inträffade (med andra ord, när rapporten genererades).

segments

I det fall där meddelandet innehåller mer tecken än teckengränsen för ett enskilt SMS kommer meddelandet att delas upp flera SMS-delar, aven kallat konkatenerade SMS. Den här egenskapen indikerar hur många SMS meddelandet behöver för att kunna skickas.

price

Hela meddelandets pris. Om du vill få ett pris på ett enskilt SMS kan du dela sumeringen av priset på antal segment i meddelandet.

currency

Vilken valuta som priset anges i.

reference

Detta är en egenskap som tillåter användaren att sätta ett eget ID eller referens om lagring av standard-genererade ID´n ogillas.


Statuskoder


Sammanfattning

Nedan hittar du samtliga statuskoder för RESTful 2.0. Statuskoderna är uppdelade i 4 olika grupper:

Info

Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.

Success

Talar om SMS:ets slutgiltiga status.

Rejection

Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.

Error

Talar om ifall meddelandet är olevererbart eller andra tekniska fel.

Info
Name Code Group description
Accepted 101 Info Meddelandet har accepterats för behandling
Queued 102 Info Meddelandet har satts i kö för att skickas ut
Funded 103 Info Meddelandets kostnad har dragits från saldot och kan skickas ut.
Refunded 104 Info Meddelandets kostnad har återbetalats och lagts till på ditt saldo
Sending 110 Info Meddelandet skickas
DeliveredToGateway 111 Info Meddelandet har levererats till gateway
DeliveredToCarrier 112 Info Meddelandet har levererats till operatören där numret är registrerat
DeliveredToGSM 113 Info Meddelandet har skickats ut till GSM-nätverket
QueuedAtGateway 114 Info Meddelandet har lagts i kö i gateway
Success
Name Code Group description
DeliveredToHandset 201 Success Meddelandet har skickats till den aktuella mottagaren
Expired 202 Success Meddelandets utgångsdatum har paserat före meddelandet hann levereras
Canceled 203 Success Meddelandet avbröts av användaren
Rejection
Name Code Group description
InsufficientFunds 402 Rejection Kontot som försöker skicka har inte tillräckligt med saldo för att skicka SMS:et
SenderRejected 403 Rejection Avsändaren har blivit nekad, ges när avsändaren anses vara bedrägeri-klassad eller att ägarskapet av avsändaren inte har verifierats ordentligt
ContentRejected 404 Rejection Meddelandets innehåll är inte tillåtet hos den specifika operatören och/eller landet, exempelvis hassardspel, vuxet innehåll etc.
RecipientRejected 405 Rejection Mottagaren är ogiltig
GenericRejected 406 Rejection Meddelandet har avvisats av någon annan anledning än ovan nämnda.
InvalidSender 407 Rejection Meddelandets avsändare är ogiltig, exempelvis för lång, innehåller ogiltiga tecken etc.
InvalidContent 408 Rejection Meddelandets innehåll är ogiltigt, exempelvis ogiltiga tecken, för långt etc.
InvalidRecipient 409 Rejection Meddelandets mottagare är ogiltig, exempelvis att mottagaren inte är ett giltigt MSISDN
MissingSmsSubscription 410 Rejection Mottagaren har inte stöd för SMS och kan därför inte ta emot meddelandet.
Error
Name Code Group description
InternalError 500 Error Ett okänt fel inträffade
UnknownSubscriber 501 Error Nätverksabonnenten existerar inte
SubscriberUnreachable 502 Error Nätverksabonnenten var inte tillgänglig och kan därför inte ta emot meddelandet
SubscriberOffline 503 Error Abonnenten är tillfälligt offline, leverans kommer att försökas på nytt så fort abonnenten är tillgänglig
DeliveryToGatewayFailed 511 Error Meddelandet kunte inte lämnas över till nästkommande gateway
DeliveryToCarrierFailed 512 Error Meddelandet kunde inte lämnas över till operatören
DeliveryToGSMFailed 513 Error Meddelandet kunde inte läggas till på GSM-nätverket
DeliveryToHandsetFailed 514 Error Meddelandet kunde inte lämnas över till mottagarens telefon
GenericDeliveryFailure 515 Error Allmänt leveransfel
GatewayError 516 Error Ett okännt fel inträffade vid gateway
Unknown 599 Error Meddelandet levererades uppströms men inget leveranskvitto har mottagits eller ett leveranskvitto som inte kunde tolkas mottogs

Lista blacklist


Endpoint

Endpoint: GET /api/blacklist

Denna endpoint låter dig lista din fullständiga blacklist.

Responsdata-typ
                        
[
    {
        "ID": 0,
        "Created": "string",
        "Phone": "string"
    }
]
                        
                    
ID

En posts unika ID.

Created

Datumet då posten lades till i blacklisten.

Phone

Det tillagda mobilnumret.

Lista enskild post


Endpoint

Endpoint: GET /api/blacklist/{entry}

Denna endpoint låter dig lista en enskild post i din blacklist

Responsdata-typ
                        
{
    "ID": 0,
    "Created": "string",
    "Phone": "string"
}
                        
                    
ID

En enskild posts unika ID.

Created

Datumet då posten lades till i blacklisten.

Phone

Det tillagda mobilnumret.


Skapa post


Endpoint

Endpoint: POST /api/blacklist

Denna endpoint låter lägga till en ny post i din blacklist

Anropsdata-typ
                        
{
    "Phone": "string"
}
                        
                    
Phone

Mobilnumret som ska läggas till i blacklisten


Responsdata-typ
                        
{
    "ID": 0,
    "Created": "string",
    "Phone": "string"
}
                        
                    
Phone

Mobilnumret som ska läggas till i blacklisten.

Created

Mobilnumret som ska läggas till i blacklisten.

Phone

Det tillagda mobilnumret.


Radera post


Endpoint

Endpoint: DELETE /api/blacklist

Denna endpoint låter dig radera en specifik post i din blacklist

Anrops-parametrar
Namn Typ Format Beskrivning
entry integer int32. Blacklist entry ID
Responsdata-typ
                        
{
    "ID": 0,
    "Created": "string",
    "Phone": "string"
}
                        
                    
ID

Den raderade postens ID.

Created

Datumet då den raderade posten lades till.

Phone

Den raderade postens mobilnummer.


Överblick konto


Endpoint

Endpoint: GET /api/me

Denna endpoint ger dig överblick över ett enskilt konto

Responsdata-typ
                        
{
    "Account": "string",
    "Organization": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string"
}
                        
                    
Account

Ett enskily kontos unika ID bestående av prefixet ip1- följt av ett antal siffror.

Organization

Företagets/organisations namn som står som ägare till kontot.

Type

ett enskilt kontos kontotyp, swedish eller international. Konton av typ swedish är enbart lämpat för SMS-trafik inom Sverige. Alla trafik utanför sverige debiteras en krona (1 SEK) extra. Konton av typ international ger ett enskilt styckpris baserat på landskoden.

Balance

Ett enskilt kontos saldonivå. kan bestå av en negativ eller positiv siffra, beroende på vald kostnadsmodell.

Currency

Anger vilken valuta ett enskilt konto debiteras i. SEK eller Euro.


Detaljer konto


Endpoint

Endpoint: GET /api/me/account

Denna endpoint ger dig en detaljlista för ett enskilt konto enligt responsdata-typen nedan.

Responsdata-typ
                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

Ett enskilt kontos API-nyckel.

Parent

Ett enskilt kontos föräldra-konto.

Type

Ett enskilt kontos kontotyp.

Balance

Ett enskilt kontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.

Currency

Ett enskilt kontos valuta.

ID

Ett enskilt kontos ID, består av prefixet ip1- följt av ett antal siffror.

Name

Ett enskilts kontos märkning. Exempelvis avdelning eller referens till kontots syfte.


Skapa underkonto


Endpoint

Endpoint: POST /api/me/children

Denna endpoint låter dig skapa ett nytt underkonto, underordnat ditt huvudkonto.

Anropsdata-typ
                        
{
    "Name": "string"
}
                        
                    
Name

Kontots märkning. Exempelvis avdelningsnamn eller annat namn som anspelar på kontots syfte.

Responsdata-typ
                        
                            
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

Ett underkontots API-nyckel.

Parent

Ett underkontos föräldra-konto.

Type

Ett underkontos konto-typ.

Balance

Ett underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.

Currency

Ett underkontos valuta.

ID

Ett underkontos ID, består av prefixet ip1- följt av ett antal siffror.

Name

Ett underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.


Lista underkonton


Endpoint

Endpoint: GET /api/me/children

Denna endpoint låter dig lista samtliga underkonton kopplade till ett konto.

Responsdata-typ
                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

Ett underkontos API-nyckel.

Parent

Ett underkontos föräldra-konto.

Type

Ett underkontos kontotyp.

Balance

Ett underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.

Currency

Ett underkontos valuta.

ID

Ett underkontos ID, består av prefixet ip1- följt av ett antal siffror.

Name

Ett underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.

Lista enskilt underkonto


Endpoint

Endpoint: GET /api/me/children{child}

Denna endpoint låter dig lista ett enskilt underkonto kopplade till ett konto.

Responsdata-typ
                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
    }
                        
                    
Key

Ett enskilt underkontos API-nyckel.

Parent

Ett enskilt underkontos föräldra-konto.

Type

Ett enskilt underkontos kontotyp.

Balance

Ett enskilt underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.

Currency

Ett enskilt underkontos valuta.

ID

Ett enskilt underkontos ID, består av prefixet ip1- följt av ett antal siffror.

Name

Ett enskilts underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.


Uppdatera ett enskilt underkonto


Endpoint

Endpoint: put /api/me/children/{child}

Denna endpoint låter dig uppdatera ett enskilt underkonto kopplat till ett konto.

Anropsadata-typ
                        
{
    "ID": "string",
    "Name": "string"
}
                        
                    
ID
Ett enskilt underkontons unika konto-ID
Name
Ett enskilt underkontos märkning eller namn.
Responsdata-typ
                        
{
    "Key": "string",
    "Parent": "string",
    "Type": "string",
    "Balance": 0.0,
    "Currency": "string",
    "ID": "string",
    "Name": "string"
}
                        
                    
Key

Ett enskilt underkontots API-nyckel.

Parent

Ett enskilt underkontos föräldra-konto.

Type

Ett enskilt underkontos konto-typ.

Balance

Ett enskilt underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.

Currency

Ett enskilt underkontos valuta.

ID

Ett enskilt underkontos ID, består av prefixet ip1- följt av ett antal siffror.

Name

Ett enskilts underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.


Inkommande SMS

För att ta emot inkommande SMS behöver du ett virtuellt nummer. I vår webshop kan du beställa ett virtuellt nummer med svensk landskod (11 siffror) samt ett prefix till vårt delade kortnummer (5 siffror) till ditt konto. Behöver du ett virtuelt nummer med annan landskod än svensk, kontakta oss för pris och leveranstid.

Kom ihåg att avsändaren inte får bestå av ett nummer längre än 15 tecken och att det bara är möjligt att ta emot meddelanden från vår server om detta krav är uppfyllt.

Callback

Det enklaste sättet att hantera inkommande SMS är att skapa en webb-applikation och sedan registrera en callback-URL för mottagarnumret hos oss.

När ett meddelandet tas emot av vår gateway så genomförs ett HTTP GET till callback-URL:en med följande parametrar:

Parameter Beskrivning Typ
text Meddelandets innehåll Sträng
to Mottagarens telefonnummer Sträng
sender Avsändare Sträng
incsmsid ID-nummer sträng

Exempel: Om din callback-URL är http://www.example.com/smscallback.php ser anropet ut så här:

                        
                        http://www.example.com/smscallback.php?incsmsid=123456789&sender=4673222222&text=testmeddelande&to=4673XXXXXXXXXXX
                        
                    

Det är också möjligt att skapa ett anrop med query-strängar, till exempel: http://www.example.com/smscallback.php?someparam=somevalue

Som svar på ditt callback-anrop ska din applikation returnera ett oformaterat OK (två tecken, utan formatering). Om ditt anrop inte lyckas eller om du får ett annat svar från servern så kommer servern att försöka igen med en intervall på 30 minuter, maximalt tio försök.

Lägg till en Callback-URL

När du har en färdig Callback-url måste du registrera den på https://app.ip1sms.com/settings/#extra. Logga in med din iP.1 Användare. Klistra in din URL i text-fältet ”Callback URL och spara dina inställningar.

Kodexempel

Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att skicka ett enskilt SMS.

Kodexempel C#
                          
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/v2/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key");

    var sms = new
    {
        sender = "iP1",
        recipients = new string[] { "46712345678" },
        body = "Test Message",
        type = "sms",
        datacoding = "gsm",
        priority = 1,
        reference = "Test"
    };

    StringContent content = new StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json");
    HttpResponseMessage response = await client.PostAsync("batches", content);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                        
                    
Kodexemempel PHP
                          
$conf = array(
    'password' => 'API key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'POST',
    'endpoint' => 'batches',
);

$message = array(
    "sender" => "iP1",
    "recipients" => ["46712345678"],
    "body" => "Test message rest v2",
    "type" => "sms",
    "datacoding" => "gsm",
    "priority" => 1,
    "reference" => "Test",
    "tags" => ["Test SMS"],
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Bearer '.$conf['password'],
            'Content-Length: ' . strlen($jsonEncodedMessage)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedMessage,
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                        
                    
Kodexempel VB Script
                          
Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/v2/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", "Insert API Key Here")

Dim sms As New With
{
    Key .sender = "iP1sms",
    Key .recipients = New List(Of String)() From {"46712345678"},
    Key .body = "Test",
    Key .type = "sms",
    Key .datacoding = "gsm",
    Key .priority = 1
}

Dim content = New StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json")
Dim response As HttpResponseMessage = Await client.PostAsync("batches", content)
                        
                    

Hjälpmedel

iP.1 Utils

Ett nuget-paket med olika verktyg. Innehåller bland annat verktyg för att formatera dina mobilnummer och att beräkna antal SMS i ett meddelande.

iP.1 Utils
Is-Disposable Phone numbers

Ett NPM-paket med blacklist för disposable phonenumbers. Innehåller en blacklist med bland annat virtuella engångs-nummer som använts vid kontoregistrering.

Is-Disposable-Phonenumber

Introduktion SMPP

Protokoll
Kom igång

Vårt SMS API låter dig koppla upp dina webbtjänster och applikationer mot mobiloperatörer världen över och är designat för att hantera höga volymer av SMS-trafik och lämpar sig perfekt för bland annat större grupputskick vid exempelvis marknadsföring, men även singelutskick för automatiserade SMS-larm etc.

Skapa konto

För att komma igång behöver du först och främst ett konto, vilket du kan skapa här.

När du skapat ditt konto loggar du in i vår användarportal för att få tillgång till dina autentiseringsuppgifter, som beskrivs närmare i steget nedan.

API Endpoint

Bas-url:en för endpoints enligt API-referens i SMPP API:et är: https://api.ip1sms.com/v2/

Alla requester måste göras genom HTTPS.

Autentisering

Systemet är skyddat av autentisering med ditt kontonummer som System ID samt API-nyckel som lösenord. Varje konto du skapar kan ha flera nycklar med restriktion på IP-adress. Använd en nyckel som minst tillåter 10.0.0.0/8 för anslutning till SMPP systemet. API-nycklarna skapar och hanterar du i vår Användarportal.

1. Logga in i användarportalen med din iP.1-användare som skapades i samband med kontoregistrering.

2. gå till Konton (se bild)

3. tryck på överblick och gå till filken API-nycklar (se bild)

4. Klicka på Lägg till ny nyckel, ge nyckeln ett namn och sätt eventuell nätverksintervall om du vill begränsa nyckeln till ett specifikt IP-adress-spann. Slutför genom att trycka på skapa nyckel.

Paginering

Alla endpoints som returnerar en samling av dokument (Batcher, meddelanden etc.) har paginering aktiverat. Vi använder oss av databas-stilen av paginering med start, limit och order som parameternamn. start, limit och order är sätt till 0, 50 och ASC i respektive ordning, men du kan ändra dem genom att ange dem som query-parametrar när du gör ett HTTP-anrop på detta vis: ?start=0&limit=200&order=DESC

Du kommer också ta emot ett länk-huvud som innehåller paginerings-information.

                        
                        Link: <https://api.ip1sms.com/v2/batches?start=201&limit=100&order=ASC> rel="next",
                        <https://api.ip1sms.com/v2/batches?start=4901&limit=100&order=ASC> rel="last"
                        
                    

Detta exempel innehåller radbryt för läsbarhetens skull.

Möjliga värden för rel är följande:

Namn Beskrivning
self Länkrelationen för den begärda resultatsidan.
first Länkrelationen för den första resultatsidan.
prev Länkrelationen för den omedelbart föregående resultatsidan.
next Länkrelationen för den omedelbart nästa resultatsidan.
last Länkrelationen för den sista resultatsidan.

Statuskoder


Sammanfattning

Nedan hittar du samtliga statuskoder för SMPP. Statuskoderna är uppdelade i 4 olika grupper:

Info

Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.

Success

Talar om SMS:ets slutgiltiga status.

Rejection

Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.

Error

Talar om ifall meddelandet är olevererbart eller andra tekniska fel.

Info
Name Code Group description
Accepted 101 Info Meddelandet har accepterats för behandling
Queued 102 Info Meddelandet har satts i kö för att skickas ut
Funded 103 Info Meddelandets kostnad har dragits från saldot och kan skickas ut.
Refunded 104 Info Meddelandets kostnad har återbetalats och lagts till på ditt saldo
Sending 110 Info Meddelandet skickas
DeliveredToGateway 111 Info Meddelandet har levererats till gateway
DeliveredToCarrier 112 Info Meddelandet har levererats till operatören där numret är registrerat
DeliveredToGSM 113 Info Meddelandet har skickats ut till GSM-nätverket
QueuedAtGateway 114 Info Meddelandet har lagts i kö i gateway
Success
Name Code Group description
DeliveredToHandset 201 Success Meddelandet har skickats till den aktuella mottagaren
Expired 202 Success Meddelandets utgångsdatum har paserat före meddelandet hann levereras
Canceled 203 Success Meddelandet avbröts av användaren
Rejection
Name Code Group description
InsufficientFunds 402 Rejection Kontot som försöker skicka har inte tillräckligt med saldo för att skicka SMS:et
SenderRejected 403 Rejection Avsändaren har blivit nekad, ges när avsändaren anses vara bedrägeri-klassad eller att ägarskapet av avsändaren inte har verifierats ordentligt
ContentRejected 404 Rejection Meddelandets innehåll är inte tillåtet hos den specifika operatören och/eller landet, exempelvis hassardspel, vuxet innehåll etc.
RecipientRejected 405 Rejection Mottagaren är ogiltig
GenericRejected 406 Rejection Meddelandet har avvisats av någon annan anledning än ovan nämnda.
InvalidSender 407 Rejection Meddelandets avsändare är ogiltig, exempelvis för lång, innehåller ogiltiga tecken etc.
InvalidContent 408 Rejection Meddelandets innehåll är ogiltigt, exempelvis ogiltiga tecken, för långt etc.
InvalidRecipient 409 Rejection Meddelandets mottagare är ogiltig, exempelvis att mottagaren inte är ett giltigt MSISDN
MissingSmsSubscription 410 Rejection Mottagaren har inte stöd för SMS och kan därför inte ta emot meddelandet.
Error
Name Code Group description
InternalError 500 Error Ett okänt fel inträffade
UnknownSubscriber 501 Error Nätverksabonnenten existerar inte
SubscriberUnreachable 502 Error Nätverksabonnenten var inte tillgänglig och kan därför inte ta emot meddelandet
SubscriberOffline 503 Error Abonnenten är tillfälligt offline, leverans kommer att försökas på nytt så fort abonnenten är tillgänglig
DeliveryToGatewayFailed 511 Error Meddelandet kunte inte lämnas över till nästkommande gateway
DeliveryToCarrierFailed 512 Error Meddelandet kunde inte lämnas över till operatören
DeliveryToGSMFailed 513 Error Meddelandet kunde inte läggas till på GSM-nätverket
DeliveryToHandsetFailed 514 Error Meddelandet kunde inte lämnas över till mottagarens telefon
GenericDeliveryFailure 515 Error Allmänt leveransfel
GatewayError 516 Error Ett okännt fel inträffade vid gateway
Unknown 599 Error Meddelandet levererades uppströms men inget leveranskvitto har mottagits eller ett leveranskvitto som inte kunde tolkas mottogs