SMS Gateway

SMS

English docs Swedish docs

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

Registrera avsändare

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.

Obs! Om du utvecklar med av ett testkonto så behöver du använda avsändaren iP1 eller iP1sms.

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.


Kodexempel

Nedan hittar du kodexempel med autentisering och funktionalitet för att registrera en avsändare.

Registrera avsändare 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 sender = "iP1";

    HttpResponseMessage response = await client.PutAsync($"me/senders/{sender}", null);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sender registered");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                        
                    
Registrera avsändare PHP
                         
$conf = array(
    'password' => 'API Key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'PUT',
    'endpoint' => 'me/senders/',
);

$sender = "iP1";

// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Authorization: Bearer '.$conf['password']
        ),
        'method'  => $conf['method']
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'] . $sender;
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                        
                    

Skicka SMS

Skicka ett eller flera SMS

Endpoint

Endpoint: POST /v2/batches

Anropsdata-typ

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

                            
{
    "sender": "iP1",
    "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.
recipients

Ett Anrop kommer att avslås om Recipients:

  • Ä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": "iP1",
    "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.

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.


Kodexempel

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

Skicka ett SMS 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 OutgoingSMS()
    {
        Sender = "iP1",
        Recipients = new List() { "46712345678" },
        Body = "Test message rest v2",
        Type = "sms",
        Datacoding = "gsm",
        Priority = 1,
        Reference = "Test",
        Tags = new List() { "Test SMS" }
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("batches", sms);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
    
public class OutgoingSMS
{
    public string Sender { get; set; }
    public List Recipients { get; set; }
    public string Body { get; set; }
    public string Type { get; set; }
    public string Datacoding { get; set; }
    public int Priority { get; set; }
    public string Reference { get; set; }
    public List Tags { get; set; }
}
                        
                    
Skicka ett SMS 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;
                        
                    

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.

Paginering

Genom att lägga till query för paginering på anropet så sätter du en gräns på hur många batcher du hämtar

                        
https://api.ip1sms.com/v2/batches?start=0&limit=200&order=DESC
                        
                    
Exemplet visar en lista 0 - 200 hämtade batcher

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": "iP1",
    "body": "Hi my name is {name}",
    "owner": "ip1-XXXXX",
    "type": "flash",
    "datacoding": "ucs",
    "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.

Paginering

Genom att lägga till query för paginering på anropet så sätter du en gräns på hur många meddelanden du hämtar

                        
https://api.ip1sms.com/v2/batches/{batch}/messages?start=0&limit=200&order=DESC
                        
                    
Exemplet visar en lista 0 - 200 hämtade meddelanden
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": "ucs",
    "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 inkommande SMS

Om en inkommande leverans-URL anges i kontoinställningarna skickas inkommande SMS-meddelanden till den webbadressen när de är tillgängliga. Innehållet i dessa SMS-meddelanden beskrivs nedan.

Vårt system skickar rapporten med POST och förväntar sig ett svar på 200 OK om rapporten levereras korrekt. Om någon annan status (dvs. en felstatus) tas emot kommer rapporten att skickas igen vid ett senare tillfälle.

Du hanterar din callback-url i användarportalen: https://portal.ip1sms.com/#/accounts/ → Callback (Se bild nedan)

Enter your callback url here

Rapport payload

                        
{
    "id": "5c613848879973045cf39ac4",
    "batchId": "5c613848879973045cf39ac3",
    "owner": "ip1-XXXXX",
    "sender": "TestNOS",
    "recipient": "456189040623",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"SMS",
    "datacoding": "ucs",
    "priority": 1,
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": 201,
            "duration": 1
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "mcc": "431",
    "mnc": "20"
}
                        
                    
id

Ett unikt ID för det specifika meddelandet.

batchId

Ett ID för alla meddelanden som tagits emot i samma begäran som detta meddelande. Detta är vanligtvis bara ett meddelande.

owner

Konto-ID för SMS-kontot som äger meddelandet.

sender

Avsändar-ID för det inkommande meddelandets upphovsman.

recipient

Mottagaren av meddelandet (t.ex. ditt virtuella nummer).

body

Det inkommande meddelandets innehåll.

direction

Avgör om meddelandet skickades eller mottogs av våra system. Bör alltid vara mo här.

mt, en akronym för mobile terminated, mo, en akronym för mobile originated.

segments

Om det inkommande meddelandet innehåller fler tecken än ett enda sms kan innehålla kommer meddelandet att delas upp i flera sms, även känt som sammanhängande sms. Den här egenskapen anger hur många sms meddelandet behöver skickas.

datacoding

Anger datakodningsschemat som används för att skicka meddelandet i fråga.

priority

Den prioritet som meddelandet skickades i. Prioritet 1 är standard och är den lägsta prioritet som är tillgänglig. Prioritet 2 är högre prioritet.

statuses

En lista bestående av statusuppdateringar.

  • statuses[].created
    • När statusen lades till
  • statuses[].code
    • Den specifika statuskoden. Fler kan läggas till i framtiden
  • statuses[].duration
    • Berättar om detta är den senaste statusuppdateringen eller om det kan komma fler statusuppdateringar

Inkommande meddelanden har bara en angiven status då den gick in i våra system utifrån. För mer information om våra statuskoder för meddelanden, se avsnittet om statuskoder.

modified

När det inkommande SMS:et senast uppdaterades.

mcc

Lands-delen av bladoperatören kan specificeras här om den tillhandahålls av operatören.

mcc är en akronym för Mobile Country Code

mnc

Nätverksdelen av bladoperatören kan specificeras här om den tillhandahålls av operatören.

mnc är en akronym för Mobile Network Code


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

Hantera landningssidor

Läs en samling av landningssidor

Endpoint: GET /v2/landings

Denna endpoint ger dig en samling landningssidor för vilka du kan se definitionen av datatypen nedan.

Paginering

Genom att lägga till query för paginering på anropet så sätter du en gräns på hur många landningssidor du hämtar

                        
https://api.ip1sms.com/v2/landings?start=0&limit=10&order=DESC
                        
                    
Exemplet visar en lista 0 - 10 hämtade landningssidor

Läs en enskild landningssida

Endpoint: Get /v2/landings/{landingId}

Denna endpoint ger dig en enda specifik landningssida.

Uppdatera en landningssida

Endpoint: PUT /v2/landings/{landingId}

Denna endpoint kan du uppdatera en specifik landningssida, ändra den lagrade datan. Allt utom element, visningar och länkar byts ut mot den nya datan.

Skapa en landningssida

Endpoint: POST /v2/landings

Denna endpoint låter dig skapa en ny landdningssida.

Radera landdningssida

Endpoint: POST /v2/landings/{landingId}

Denna endpoint låter dig ta bort en specifik landnignssida.

Datatyp

    
        {
            "id": "615d9900792a81c7e32841ee",
            "name": "Welcome Page",
            "views": {
                "2021": 6,
                "2021-10": 4,
                "2021-10-19": 2,
                "2021-10-19 09:00:00": 1,
                "2021-10-19 11:00:00": 1,
                "2021-10-22": 2,
                "2021-10-22 15:00:00": 2,
                "2021-11": 2,
                "2021-11-22": 2,
                "2021-11-22 05:00:00": 2
            },
            "link": "https://landing.ip1.net/615d9900792a81c7e32841ee",
            "shortLink": "https://url.ip1.net/sdkkas",
            "lastModified": "2021-10-06T12:56:30.854Z",
            "elements": [
              {
                "type": "Title",
                "id": "615d9a0b792a81c7e32841ef",
                "order": 0,
                "backgroundColor": "#f7f7f7",
                "foregroundColor": "#111",
                "padding": "2",
                "margin": "0",
                "textAlignment": "Center",
                "font": "Roboto",
                "content": "Welcome to the Landing",
                "level": 1,
                "bold": false,
                "italic": false,
                "underline": false
              }
            ]
        }
    
id

Landningssidans ID, används för att referera till en specifik landdningssida.

name

Landningssidans namn.

views

Antalet gånger som landningssidan har visats av slutanvändare. En dcictionary med nycklar som delar av tidsstämplar (år, månad, dag, timme) och värden som antal gånger landningssidan har visats av slutanvändare under den tiden. Exempel nedan:

    
        {
            "2021": 6,
            "2021-10": 4,
            "2021-10-19": 2,
            "2021-10-19 09:00:00": 1,
            "2021-10-19 11:00:00": 1,
            "2021-10-22": 2,
            "2021-10-22 15:00:00": 2,
            "2021-11": 2,
            "2021-11-22": 2,
            "2021-11-22 05:00:00": 2
        }
    
lastModified

En tidsstämpel för senaste gången landningssidan ändrades.

elements

En samling av landningssidans element. Du kan läsa mer om dessa i avsnittet "Elementtyper".


Hantera sid-element

Läs en samling element

Endpoint: GET /v2/landings/{landingId}/elements

Denna endpoint ger dig en samling av elementen på en specifik landningssida. Se definitionen av datatyp nedan.

Läs ett specifikt element

Endpoint: Get /v2/landings/{landingId}/elements/{elementId}

Denna endpoint ger dig ett specifikt element på en landningssida

Uppdatera ett element

Endpoint: PUT /v2/landings/{landingId}/elements/{elementId}

Denna endpoint låter dig uppdatera ett element på en landningssida och ändra lagrad data. Allt ersätts av nya värden.

Skapa ett nytt element

Endpoint: POST /v2/landings/{landingId}/elements

Denna endpoint låter dig skapa ett nytt element på en landnignssida.

Radera ett element

Endpoint: POST /v2/landings/{landingId}/elements/{elementId}

Denna endpoint låter dig ta bort ett element på en landnignssida.

Datatyp

    
        {
            "type": "Title",
            "id": "615d9a0b792a81c7e32841ef",
            "order": 0,
            "backgroundColor": "#f7f7f7",
            "foregroundColor": "#111",
            "padding": "2",
            "margin": "2,0,2,0",
            "textAlignment": "Center",
            "font": "Roboto",
            "content": "Welcome to the Landing",
            "level": 1,
            "bold": false,
            "italic": false,
            "underline": false
        }
    
type

Elementets typ. Exemplet visar ett titel-element.

id

Elementets ID, används för att referera till en specifikt element.

order

Elementets ordning på sidan, sidan renderas i stigande ordning (ID:n bryter banden). Valfritt, standardvärdet är null.

backgroundColor

Färgen som används som elementets bakgrund (Anges i hexadecimal), om tillämpligt. Standarvärde är #f7f7f7.

foregroundColor

Färgen som används som elementets förgrund (Anges i hexadecimal), om tillämpligt. Standarvärde är #111.

padding

Fyllnaden som lagts till runt elementet. Antingen ett (1) nummer för alla sidor, eller fyra (4) siffror kommaseparerade i ordning (överst, botten, vänster, höger). Alla nummer från 0 till 8. Standard är 2.

margin

Marginalen runt elementet. Antingen ett (1) nummer för alla sidor, eller fyra (4) siffror kommaseparerade i ordning (överst, botten, vänster, höger). Alla nummer från 0 till 8. Standard är 0.


Elementtyper

Här hittar du definitioner och beskrivningar av de olika elementtyper som finns tillgängliga för en landningssida. Alla egenskaper som inte förklaras i Hantera sid-element förklaras här.

Titel-element

                      
{
  "type": "Title",
  "id": "615d9a0b792a81c7e32841ef",
  "order": 0,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Center",
  "font": "Roboto",
  "content": "Welcome to the Landing",
  "level": 1,
  "bold": false,
  "italic": false,
  "underline": false
}
                      
                  
level

En titels nivåer. Giltiga värden är 1 - 5, varav 1 är den största rubrikstorleken, 5 den minsta.

bold

Om titeltexten ska visas i fetstil eller inte. standardvärde är false

italic

Om titeltexten ska visas i kursivt eller inte. standardvärde är false

underline

Om titeltexten ska vara understruken eller inte. standardvärde är false

Textblock-element

                      
{
  "type": "TextBlock",
  "id": "615db88a0f5018f08437bff5",
  "order": 1,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Left",
  "font": "Roboto",
  "content": "One row\n\nAnd another section",
  "fontSize": 16
}
                      
                  
fontSize

Textstorleken i pixlar. Standardvärde är 16 (px)

Knapp-element

                    
{
  "type": "Button",
  "id": "615db9a50f5018f08437bff6",
  "order": 2,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "textAlignment": "Left",
  "font": "Roboto",
  "content": "Click me",
  "link": "https://example.com",
  "buttonType": "Standalone",
  "size": null,
  "buttonColor": "#89b642"
}
                    
                
buttonType

Bestämmer den renderade knapptypen. Giltiga värden är Standalone och block. Standardvärde är Standalone.

size

Ändrar knapp-elementets storlek, större eller mindre. Giltiga värden är sm, lg och null. Standardvärde är null.

color

Knapp-elementets färg (Anges i hexadecimal). Standardvärde är #89b642

Bild-element

                  
{
  "type": "Image",
  "id": "615dba140f5018f08437bff7",
  "order": 3,
  "backgroundColor": "#f7f7f7",
  "foregroundColor": "#111",
  "padding": "2",
  "margin": "2,0,2,0",
  "link": "https://example.com/cool-pic.png",
  "responsive": true,
  "alignment": "Center",
  "height": null,
  "width": null,
  "alt": "Image not available"
}
                  
              

Video-element

                  
{
"type": "Image",
"id": "615dba140f5018f08437bff7",
"order": 3,
"backgroundColor": "#f7f7f7",
"foregroundColor": "#111",
"padding": "2",
"margin": "2,0,2,0",
"link": "https://example.com/cool-pic.png",
"responsive": true,
"alignment": "Center",
"height": null,
"width": null,
"alt": "Image not available"
}
                  
              
showControls

Bestämmer om kontroller för video-element ska visas eller inte. Standardvärde är false

autoplay

Bestämmer om videon ska starta automatiskt så fort sidan laddas eller inte. Standardvärde är false

loop

Bestämmer om videon ska spelas i loop eller inte. Standardvärde är false

muted

Bestämmer om ljudet ska vara avstängt när sidan laddats eller inte. Standardvärde är false

Vanligt förekommande egenskaper

textAlignment

Justeringen av elementets textinnehåll. Giltiga värden är Left, Center, Right och Justified. Standardvärde är Left.

alignment

Justeringen av mediainnehåll inuti ett element. Giltiga värden är Left, Center och Right. Standardvärde är Center.

font

Teckensnittet som används för textinnehåll i ett element. Accepterar vilket standard webfont som helst.

content

Textinnehållet i elementet. För textblock tolkas detta som Markdown när det renderas.

responsive

Om videon eller bilden ska skalas responsivt. Standardvärde är true.

height

Höjden på videon eller bilden (i pixlar). Ignoreras om mediaobjektet ska skalas responsivt. Frivillig. Standardvärde är null.

width

Bredden på videon eller bilden (i pixlar). Ignoreras om mediaobjektet ska skalas responsivt. Frivillig. Standardvärde är null.

alt

Den alternativa texten som ska visas om videon eller bilden inte kan laddas eller visas. Standardvärde är null.


Konfigurera 2FA


Hämta nuvarande konfiguration

Endpoint: GET /api/authentications/settings

Denna endpoint låter dig hämnta den nuvarande konfigurationen för 2FA.


Uppdatera konfiguration

Endpoint: PUT /api/authentications/settings

Denna endpoint låter dig uppdatera konfigurationen för 2FA.

Anropsdata-typ

                      
{
  "ConcurrentLimit": 1,
  "From": "sample string 1",
  "MessageFormat": "sample string 2",
  "Length": 1,
  "ExpirationTime": 1,
  "NumericOnly": true
}
                      
                  

Responsdata-typ

                      
{
  "ConcurrentLimit": 1,
  "From": "sample string 1",
  "MessageFormat": "sample string 2",
  "Length": 1,
  "ExpirationTime": 1,
  "NumericOnly": true
}
                    
                
ConcurrentLimit

Antalet samtida autentiseringar som är möjliga för ett och samma mobilnummer.

Typ: String

From

Avsändaren som används i SMS:et som bär autentiseringskoden.

MessageFormat

Meddelandet som bär koden, där {0} representerar en unik kod för varje mottagare.

Length

Längden på autentiseringskoden.

ExpirationTime

Tiden då autentiseringskoden går ut.

NumericOnly

Huruvida autentiseringskoden ska besta av enbart siffror eller ej.


Hantera och skicka 2FA


Skapa och skicka autentisering

Endpoint: POST /api/authentications

Denna endpoint låter dig skapa och skicka ut en ny autentisering.

Anropsdata-typ

                      
{
  "Phone": "sample string 1",
  "From": "sample string 2",
  "MessageFormat": "sample string 3",
  "Length": 1,
  "ExpirationTime": 1,
  "NumericOnly": true
}
                      
                  
Phone

Mobilnumret som autentiseringen ska skickas till.

Typ: String

From

Avsändaren som används i SMS:et som bär autentiseringskoden.

MessageFormat

Meddelandet som bär koden, där {0} representerar en unik kod för varje mottagare.

Length

Längden på autentiseringskoden.

ExpirationTime

Tiden då autentiseringskoden går ut.

NumericOnly

Huruvida autentiseringskoden ska besta av enbart siffror eller ej.


Lista dina autentiseringar

Endpoint: GET /api/authentications

Denna endpoint låter dig lista alla dina autentiseringar.

Läs en enskild autentisering

Endpoint: POST /api/authentications/{authentication}

Denna endpoint låter dig läsa en enskild autentisering.

Radera en autentisering

Endpoint: DELETE /api/authentications/{authentication}

Denna endpoint låter dig radera en specifik autentisering.

Responsdata-typ

                        
{
  "ID": 1,
  "Phone": "sample string 2",
  "Created": "2022-06-15T14:38:32.8668254+00:00",
  "HasExpired": true,
  "Expires": "2022-06-15T14:38:32.8668254+00:00",
  "IsUsed": true,
  "Used": "2022-06-15T14:38:32.8668254+00:00"
}
                      
                  
ID

En specifik autentiserings identifierare.

Phone

Mobilnumret som autentiseringen skickades till.

Created

En datumstämpel som visar när autentiseringen skapades.

HasExpired

Visar huruvida autentiseringen har gått ut eller ej.

Expires

En datumstämpel som visar när autentiseringen går förfaller.

IsUsed

Visar huruvida en autentiseringen är använd eller ej.

Used

En datumstämpel som visar när autentiseringen användes.


Validera 2FA


Validera autentisering

Endpoint: POST /api/authentications/validate

Denna endpoint låter dig validera en autentiseringskod.

Anropsdata-typ

                      
{
  "Phone": "sample string 1",
  "Code": "sample string 2"
}
                      
                  

Responsdata-typ

                      
{
  "Valid": true,
  "Authentication": {
    "ID": 1,
    "Phone": "sample string 2",
    "Created": "2022-06-15T14:21:25.3577027+00:00",
    "HasExpired": true,
    "Expires": "2022-06-15T14:21:25.3577027+00:00",
    "IsUsed": true,
    "Used": "2022-06-15T14:21:25.3577027+00:00"
  },
  "Phone": "sample string 2",
  "Code": "sample string 3"
}
                    
                
Valid

Ett värde av sant eller falskt om koden är giltig respektive ogiltig.

Valid

En lista av information gällande en specifik autentisering.

ID

En specifik autentiserings identifierare.

Phone

Mobilnumret som autentiseringen skickades till.

Created

En datumstämpel som visar när autentiseringen skapades.

HasExpired

Visar huruvida autentiseringen har gått ut eller ej.

Expires

En datumstämpel som visar när autentiseringen går förfaller.

IsUsed

Visar huruvida en autentiseringen är använd eller ej.

Used

En datumstämpel som visar när autentiseringen användes.

Phone

Mobilnumret som har autentiserats.

Code

Autentiseringskoden som använts vid autentiseringen.


Sammanfattning kontakt

Hämta kontaktdata

Endpoint: GET /v2/contacts/meta

Denna endpoint tillhandahåller en summering av den kontaktdata som är lagrad i kontaktsystemet

Responsdata-typ

                        
        {
            "totalCount": 10,
            "labels": [
                {
                    "labelName": "all",
                    "usageCount": 10
                },
                {
                    "labelName": "Customer",
                    "usageCount": 7
                },
                {
                    "labelName": "Coworker",
                    "usageCount": 3
                }
            ],
            "properties": [
                {
                    "propertyName": "email",
                    "usageCount": 9,
                    "averageLength": 20,
                    "maxLength": 26,
                    "minLength": 16
                },
                {
                    "propertyName": "firstName",
                    "usageCount": 10,
                    "averageLength": 5,
                    "maxLength": 6,
                    "minLength": 3
                },
                {
                    "propertyName": "lastName",
                    "usageCount": 10,
                    "averageLength": 7,
                    "maxLength": 12,
                    "minLength": 5
                },
                {
                    "propertyName": "department",
                    "usageCount": 10,
                    "averageLength": 4,
                    "maxLength": 8,
                    "minLength": 3
                },
                {
                    "propertyName": "phoneNumber",
                    "usageCount": 10,
                    "averageLength": 12,
                    "maxLength": 12,
                    "minLength": 12
                }
            ]
        }
                        
                    
totalCount

Det totala antalet kontakter lagrade.

labels

En post för varje använd etikett.

labels.labelName

Etikettens namn

labels.usageCount

Antalet lagrade kontakter som tilldelats etiketten


properties

En post för varje använd egenskap.

properties.propertyName

Namnet/nyckeln för egenskapen.

properties.usageCount

Antalet kontakter som har ett värde för egenskapen.

properties.averageLength

Den genomsnittliga längden på egenskapen bland lagrade kontakter.

properties.maxLength

Det längsta värdet för egenskapen bland lagrade kontaktern.

properties.minLength

Det kortaste värdet för egenskapen bland lagrade kontakten.


Hantera kontakter

Läs en samling av kontakter

Endpoint: GET /v2/contacts

Denna endpoint ger dig en samling kontakter för vilka du kan se definitionen av kontaktdokumentet nedan. Denna samling kan filtreras efter egenskaper, metadata och/eller etiketter med hjälp av frågeparametrar. Metadata finns bara om meta läggs till som en frågeparameter.

Exempel på filter: https://ip1-api-gateway-dev.azure-api.net/v2/contacts?labels=Coworker&properties%5BphoneNumber%5D=%2B46123456789&metadata%5BphoneNumber.isBlocked%5D=false

Paginering

Genom att lägga till query för paginering på anropet så sätter du en gräns på hur många kontakter du hämtar

                        
https://api.ip1sms.com/v2/contacts?start=0&limit=200&order=DESC
                        
                    
Exemplet visar en lista 0 - 200 hämtade kontakter

Läs en enskild kontakt

Endpoint: Get /v2/contacts/{contactId}

Denna endpoint ger dig en enda specifik kontakt. Metadata finns bara om "meta" läggs till som en frågeparameter

Uppdatera en kontakt

Endpoint: PATCH /v2/contacts/{contactId}

Endpoint: PUT /v2/contacts/{contactId}

Med dessa endpoints kan du uppdatera en kontakt och ändra lagrad data. Den första endpointen gör en delvis uppdatering, anger eventuella värden som finns och tar bort alla tydliga nullvärden om det finns. Den andra ersätter allt med nya data oavsett tidigare värden.

Lägg till/importera kontakter

Endpoint: POST /v2/contacts

Denna endpoint låter dig lägga till/importera nya kontakter. Den tar en samling kontaktdokument. Som standard accepteras kontakterna och importeras sedan i bakgrunden, men det kan göras direkt genom att lägga till sync som en frågeparameter. Direktimport rekommenderas endast för små samlingar av kontakter (färre än 1000).

Radera kontakter

Endpoint: POST /v2/contacts/{contactId}

Denna endpoint låter dig ta bort en kontakt. Det finns också en endpoint för att ta bort mer än en kontakt, se avsnittet för Massoperationer.

Responsdata-typ

    
        {
            "id": "606312a5d233ab8484e18404",
            "ownerId": "ip1-XXXXX",
            "properties": {
                "phoneNumber": "+46123456789",
                "email": "icarus@example.com",
                "firstName": "Icarus",
                "lastName": "Sol",
                "department": "Sales"
            },
            "metadata": {
                "phoneNumber": {
                    "isPossiblePhoneNumber": "true",
                    "isValidPhoneNumber": "true",
                    "phoneNumberType": "MOBILE",
                    "parsedMSISDN": "46123456789",
                    "isBlocked": "false"
                }
            },
            "labels": [
              "Coworker",
              "all"
            ]
          }
    
id

Kontaktens ID, används för att referera till en specifik kontakt.

ownerId

Kontot som äger kontakten.

properties

En dictionary av kontaktegenskaper, som telefonnunner, namn, företagsuppgifter m.m.

metadata

Metadata om vissa egenskaper. En dictionary med metadata-egenskaper för varje egenskap med metadata. Saker som valideringsresultat och blockerad status.

labels

En samling etiketter för kontakten. Används oftast för att kategorisera eller gruppera kontakter.


Kodexempel

Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att lägga till en kontakt.

Lägg till en kontakt 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 contact = new Contact()
    {
        properties = new Dictionary() {
            { "phoneNumber", "46712345678"},
            {"email" , icarus@example.com},
            {"firstName" , "Icarus"},
            {"lastName" , "Sol"},
            {"department" , "Sales"}
        },
        labels = new List() 
        { 
            "Coworker",
            "Sales"
        }
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("contacts", contact);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
    
public class Contact
{
    public Dictionary properties { get; set; }
    public List labels { get; set; }
}    
                        
                    

Hantera etiketter

Dessa endpoints uppdaterar en samtliga kontakter i perspektivet från en etikett och returnerar en sammanfattning av etiketten i fråga.

Lägg till en etikett för flera kontakter

Endpoint: POST /v2/labels/{labelName}/contacts

Denna endpoint låter dig lägga till en etikett till många kontakter samtidigt. Den tar en samling kontakt-ID:n

Exempel:
    
        [
            "5d8b19f972c0b7514c5b0f"
            "5d8b19f972c0b7515c5b0f"
            "5d8b19f972c0b7516c5b0f"
        ]
    

Radera en label

Endpoint: DELETE /v2/labels/{labelName}

Denna endpoint låter dig ta bort en etikett och kan ta bort den från alla kontakter som har den. Kontakterna är annars intakta.

Responsdata-typ

    
        {
            "labelName": "Coworker",
            "usageCount": 3
        }
    
labelName

Etikettens namn.

usageCount

Antalet kontakter som använder etiketten.


Mass-operationer

Dessa endpoints utför så kallade mass-operationer och kan ibland vara destruktivt eller "farligt" då data kan försvinna om den inte används på rätt sätt.

Radera kontakter genom filtrering

Endpoint: DELETE /v2/contacts

Denna endpoint låter dig ta bort alla kontakter som matchar de använda filtren. Dessa är samma filter som för att lista kontakter (se Hantera kontakter). Detta är destruktivt och bör användas med försiktighet. Den returnerar en samling av de borttagna kontakterna ungefär som att lista dem.


Hantera blacklist


Läs blacklist

Endpoint: GET /v2/blacklist

Denna endpoint låter dig läsa hela din blacklist.

Lägg till en post

Endpoint: POST /v2/blacklist

Denna endpoint lägger till en post i din blacklist.

Läs en enskild post

Endpoint: GET /v2/blacklist/{msisdn}

Denna endpoint låter dig läsa en specifik post i din blacklist.

Lägg till eller uppdatera post

Endpoint: PUT /v2/blacklist/{msisdn}

Denna endpoint låter dig uppdatera eller lägga till en post i din blacklist.

Ta bort en post

Endpoint: DELETE /v2/blacklist/{msisdn}

Denna endpoint låter dig radera en post från din blacklist.

Datatyp

    
        {
            "msisdn": "46703541190",
            "created": "2019-11-01T16:32:18.253"
        }
    
msidsn

Det tillagda mobilnumret.

created

Datumet då posten lades till i blacklisten.



Överblick konto


Överblick huvudkonto

Endpoint

Endpoint: GET /api/me

Denna endpoint ger dig överblick över ditt huvudkonto konto

Responsdata-typ

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

Ett enskilt 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. All 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


Hämta detaljer för underkonto

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


Skapa ett nytt 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


Lista samtliga underkonton

Endpoint

Endpoint: GET /api/me/children

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

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 underkonto


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 = "ucs",
        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" => "ucs",
    "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 = "ucs",
    Key .priority = 1
}

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

Användbara verktyg

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