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.
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.
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.
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.
Logga in i användarportalen med din iP.1-användare som skapades i samband med din kontoregistrering. Följ sedan video-instruktionen nedan för att skapa din nyckel.
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=DESCDu 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. |
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.
För att du ska kunna använda din egen avsändare krävs ett av våra abonnemang, alternativt extratjänsten "Valfri Avsändare", som köpes separat om du använder vårt system för SMS-saldo.
Obs! Om du utvecklar med av ett testkonto så behöver du använda avsändaren iP1 eller iP1sms.
Endpoint: GET /v2/me/senders
Denna endpoint listar alla dina registrerade avsändare som är knutna till ditt konto, sorterade i alfabetisk ordning.
Endpoint: PUT /v2/me/senders/{sender}
Denna endpoint tillåter dig att registrera en ny 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.
{
"sender": "TestNOS",
"created": "2018-10-23T17:43:19Z"
}
Nedan hittar du kodexempel med autentisering och funktionalitet för att registrera en avsändare.
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());
}
}
$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;
Imports System.Net.Http
Imports System.Net.Http.Headers
Module Module1
Sub Main()
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", "API Key")
Dim sender As String = "iP1"
Dim response As HttpResponseMessage = client.PutAsync($"me/senders/{sender}", Nothing).Result
If response.IsSuccessStatusCode Then
Console.WriteLine("Sender registered")
Else
Console.WriteLine("Failed, " & response.StatusCode.ToString() & ": " & response.Content.ReadAsStringAsync().Result)
End If
End Sub
End Module
Endpoint: POST /v2/batches
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"
Ett Anrop kommer att avslås om Sender:
Ett meddelande kanske inte når mottagaren om:
Ett Anrop kommer att avslås om Recipients:
Telefonnumer måste skrivas i formatet MSISDN.MSISDN betstår av tre element: CC = Country Code, NDC = National Desination Code och SN = Subscriber Number. Exempel på ett svenskt MSISDN: CC = 46, NDC = 712 och SN = 34567846712345678 Varje telefonnummer analyseras och valideras där resultatet visas som en status för meddelandet. Om detta steg misslyckas skickas inte meddelandet.
Ett anrop kommer att misslyckas om Body:
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"]
}
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.
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.
Det finns två typer tillgängliga:
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.
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.
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.
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.
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.
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.
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.
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.
Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att skicka ett SMS.
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<string>() { "46712345678" },
Body = "Test message rest v2",
Type = "sms",
Datacoding = "gsm",
Priority = 1,
Reference = "Test",
Tags = new List<string>() { "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<string> 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<string> Tags { get; set; }
}
$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;
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Net.Http.Json
Module Module1
Sub Main()
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", "API Key")
Dim sms As New OutgoingSMS()
sms.Sender = "iP1"
sms.Recipients = New List(Of String)() From {"46712345678"}
sms.Body = "Test message rest v2"
sms.Type = "sms"
sms.Datacoding = "gsm"
sms.Priority = 1
sms.Reference = "Test"
sms.Tags = New List(Of String)() From {"Test SMS"}
Dim response As HttpResponseMessage = client.PostAsJsonAsync("batches", sms).Result
If response.IsSuccessStatusCode Then
Console.WriteLine("Sent")
Else
Console.WriteLine("Failed, " & response.StatusCode.ToString() & ": " & response.Content.ReadAsStringAsync().Result)
End If
End Sub
End Module
Public Class OutgoingSMS
Public Property Sender As String
Public Property Recipients As List(Of String)
Public Property Body As String
Public Property Type As String
Public Property Datacoding As String
Public Property Priority As Integer
Public Property Reference As String
Public Property Tags As List(Of String)
End Class
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.
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
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.
{
"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"],
}
Avsändaren som används för ett eller flera meddelanden.
Den ursprungliga bodyn som skickas, före mallar har tillämpats, enligt den ursprungliga requesten.
Kontonumret för SMS-kontot som står som ägare till batchen.
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.
Specifierar det största setet datacoding som är tillåtet i batchen
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.
Om templating användes i batchen eller inte.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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"
}
Ett unikt id för ett detta specifika meddelande.
Ett id för samtliga meddelanden som skickades i samma request som detta specifika meddelande.
SMS-kontots ID, ägare för det specifika meddelandet.
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.
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
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.
Meddelandets prioritet. Prioritet 1 är standardvärdet och samtidigt den lägsta prioritet som tillhandahålls. Prioritet 2 är den högsta prioriteten.
Hela meddelandets pris. Vill du veta priset för ett enskilt SMS i ett meddelande, kan du dela meddelandets pris med antalet segment.
Vilken valuta som meddelandets pris använder.
En array bestående av statusuppdateringar.
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.
När SMS:et senast uppdaterades
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.
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
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
Läs meddelanden eller en summering av meddelanden gällande specifika deltagare. Detta kan exempelvis innebära konversationer mellan dig och en specifik kund.
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.
Avsändare för den deltagare vars meddelanden är listade.
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
}
}
}
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.
Den totala mängden meddelanden kopplade till deltagaren.
Den totala mängden SMS-segment kopplade till deltagaren.
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.
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.
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.ip1.net/accounts/ → Inställningar för inkommande SMS (Se bild nedan)
{
"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"
}
Ett unikt ID för det specifika meddelandet.
Ett ID för alla meddelanden som tagits emot i samma begäran som detta meddelande. Detta är vanligtvis bara ett meddelande.
Konto-ID för SMS-kontot som äger meddelandet.
Avsändar-ID för det inkommande meddelandets upphovsman.
Mottagaren av meddelandet (t.ex. ditt virtuella nummer).
Det inkommande meddelandets innehåll.
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.
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.
Anger datakodningsschemat som används för att skicka meddelandet i fråga.
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.
En lista bestående av 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.
När det inkommande SMS:et senast uppdaterades.
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
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
Nedan hittar du ett kodexempel för en callback för inkommande SMS-trafik.
[Route("callback")]
[ApiController]
public class CallbackController : ControllerBase
{
private readonly SqlConnection Connection;
public CallbackController()
{
Connection = new SqlConnection("Connection String");
Connection.Open();
}
[HttpPost("")]
public ActionResult HandleCallback(IncommingSms request)
{
using (SqlCommand cmd = new SqlCommand("INSERT INTO [Messaging].[SmsMessage] ([Sender],[Body]) VALUES (@sender, @body)", Connection))
{
cmd.Parameters.AddWithValue("@sender", request.Sender);
cmd.Parameters.AddWithValue("@body", request.Body);
int result = cmd.ExecuteNonQuery();
}
return Ok();
}
}
public class IncommingSms
{
public string Id { get; set; }
public string BatchId { get; set; }
public string Owner { get; set; }
public string Sender { get; set; }
public string Recipient { get; set; }
public string Body { get; set; }
public string Direction { get; set; }
public int Segments { get; set; }
public string Type { get; set; }
public string Datacoding { get; set; }
public int Priority { get; set; }
public List Statuses { get; set; }
public DateTime Modified { get; set; }
public string Mcc { get; set; }
public string Mnc { get; set; }
}
public class Status
{
public DateTime Created { get; set; }
public int Code { get; set; }
public int Duration { get; set; }
}
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.
{
"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"
}
Ett unikt ID för det specifika meddelandet.
Ett id för batchens meddelande som skickats i samma request som det specifika meddelandet.
Meddelandets mottagare
Den ny statuskoden för meddelandet. För mer information om våra statuskoder, se avsnittet om statuskoder.
Visar om meddelandets status är permanent/slutlig. Om så är fallet kommer detta vara den sista rapporten som skickas gällande detta meddelande.
När statusuppdateringen inträffade (med andra ord, när rapporten genererades).
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.
Hela meddelandets pris. Om du vill få ett pris på ett enskilt SMS kan du dela sumeringen av priset på antal segment i meddelandet.
Vilken valuta som priset anges i.
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.
Nedan hittar du samtliga statuskoder för RESTful 2.0. Statuskoderna är uppdelade i 4 olika grupper:
Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.
Talar om SMS:ets slutgiltiga status.
Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.
Talar om ifall meddelandet är olevererbart eller andra tekniska fel.
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 |
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 |
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. |
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 |
Endpoint: GET /v2/landings
Denna endpoint ger dig en samling landningssidor för vilka du kan se definitionen av datatypen nedan.
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
Endpoint: Get /v2/landings/{landingId}
Denna endpoint ger dig en enda specifik 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.
Endpoint: POST /v2/landings
Denna endpoint låter dig skapa en ny landdningssida.
Endpoint: POST /v2/landings/{landingId}
Denna endpoint låter dig ta bort en specifik landnignssida.
{
"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
}
]
}
Landningssidans ID, används för att referera till en specifik landdningssida.
Landningssidans namn.
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
}
Länken som leder till landningssidan.
En kortare version som vidarebefordrar till link. kortlänkar används i SMS-kampanjer.
En tidsstämpel för senaste gången landningssidan ändrades.
En samling av landningssidans element. Du kan läsa mer om dessa i avsnittet "Elementtyper".
Endpoint: GET /v2/landings/{landingId}/elements
Denna endpoint ger dig en samling av elementen på en specifik landningssida. Se definitionen av datatyp nedan.
Endpoint: Get /v2/landings/{landingId}/elements/{elementId}
Denna endpoint ger dig ett specifikt element på en landningssida
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.
Endpoint: POST /v2/landings/{landingId}/elements
Denna endpoint låter dig skapa ett nytt element på en landnignssida.
Endpoint: POST /v2/landings/{landingId}/elements/{elementId}
Denna endpoint låter dig ta bort ett element på en landnignssida.
{
"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
}
Elementets typ. Exemplet visar ett titel-element.
Elementets ID, används för att referera till en specifikt element.
Elementets ordning på sidan, sidan renderas i stigande ordning (ID:n bryter banden). Valfritt, standardvärdet är null.
Färgen som används som elementets bakgrund (Anges i hexadecimal), om tillämpligt. Standarvärde är #f7f7f7.
Färgen som används som elementets förgrund (Anges i hexadecimal), om tillämpligt. Standarvärde är #111.
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.
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.
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.
{
"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
}
En titels nivåer. Giltiga värden är 1 - 5, varav 1 är den största rubrikstorleken, 5 den minsta.
Om titeltexten ska visas i fetstil eller inte. standardvärde är false
Om titeltexten ska visas i kursivt eller inte. standardvärde är false
Om titeltexten ska vara understruken eller inte. standardvärde är false
{
"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
}
Textstorleken i pixlar. Standardvärde är 16 (px)
{
"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"
}
Bestämmer den renderade knapptypen. Giltiga värden är Standalone och block. Standardvärde är Standalone.
Ändrar knapp-elementets storlek, större eller mindre. Giltiga värden är sm, lg och null. Standardvärde är null.
Knapp-elementets färg (Anges i hexadecimal). Standardvärde är #89b642
{
"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"
}
{
"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"
}
En URL till en förhandsgranskningsbild som ska visas när videon inte spelas upp. Valfritt, standardvärdet är null.
Bestämmer om kontroller för video-element ska visas eller inte. Standardvärde är false
Bestämmer om videon ska starta automatiskt så fort sidan laddas eller inte. Standardvärde är false
Bestämmer om videon ska spelas i loop eller inte. Standardvärde är false
Bestämmer om ljudet ska vara avstängt när sidan laddats eller inte. Standardvärde är false
Justeringen av elementets textinnehåll. Giltiga värden är Left, Center, Right och Justified. Standardvärde är Left.
Justeringen av mediainnehåll inuti ett element. Giltiga värden är Left, Center och Right. Standardvärde är Center.
Teckensnittet som används för textinnehåll i ett element. Accepterar vilket standard webfont som helst.
Textinnehållet i elementet. För textblock tolkas detta som Markdown när det renderas.
En URL till det länkade innehållet i elementet. För videor och bilder är detta videon eller bilden, och för knappar är det destinationen man kommer till vid klick.
Om videon eller bilden ska skalas responsivt. Standardvärde är true.
Höjden på videon eller bilden (i pixlar). Ignoreras om mediaobjektet ska skalas responsivt. Frivillig. Standardvärde är null.
Bredden på videon eller bilden (i pixlar). Ignoreras om mediaobjektet ska skalas responsivt. Frivillig. Standardvärde är null.
Den alternativa texten som ska visas om videon eller bilden inte kan laddas eller visas. Standardvärde är null.
Endpoint: GET /api/authentications/settings
Denna endpoint låter dig hämnta den nuvarande konfigurationen för 2FA.
Endpoint: PUT /api/authentications/settings
Denna endpoint låter dig uppdatera konfigurationen för 2FA.
{
"ConcurrentLimit": 1,
"From": "sample string 1",
"MessageFormat": "sample string 2",
"Length": 1,
"ExpirationTime": 1,
"NumericOnly": true
}
{
"ConcurrentLimit": 1,
"From": "sample string 1",
"MessageFormat": "sample string 2",
"Length": 1,
"ExpirationTime": 1,
"NumericOnly": true
}
Antalet samtida autentiseringar som är möjliga för ett och samma mobilnummer.
Typ: String
Avsändaren som används i SMS:et som bär autentiseringskoden.
Meddelandet som bär koden, där {0} representerar en unik kod för varje mottagare.
Längden på autentiseringskoden.
Tiden då autentiseringskoden går ut.
Huruvida autentiseringskoden ska besta av enbart siffror eller ej.
Endpoint: POST /api/authentications
Denna endpoint låter dig skapa och skicka ut en ny autentisering.
{
"Phone": "sample string 1",
"From": "sample string 2",
"MessageFormat": "sample string 3",
"Length": 1,
"ExpirationTime": 1,
"NumericOnly": true
}
Mobilnumret som autentiseringen ska skickas till.
Telefonnumer måste skrivas i formatet MSISDN.MSISDN betstår av tre element: CC = Country Code, NDC = National Desination Code och SN = Subscriber Number. Exempel på ett svenskt MSISDN: CC = 46, NDC = 712 och SN = 34567846712345678 Varje telefonnummer analyseras och valideras där resultatet visas som en status för meddelandet. Om detta steg misslyckas skickas inte meddelandet.
Typ: String
Avsändaren som används i SMS:et som bär autentiseringskoden.
Meddelandet som bär koden, där {0} representerar en unik kod för varje mottagare.
Längden på autentiseringskoden.
Tiden då autentiseringskoden går ut.
Huruvida autentiseringskoden ska besta av enbart siffror eller ej.
Endpoint: GET /api/authentications
Denna endpoint låter dig lista alla dina autentiseringar.
Endpoint: POST /api/authentications/{authentication}
Denna endpoint låter dig läsa en enskild autentisering.
Endpoint: DELETE /api/authentications/{authentication}
Denna endpoint låter dig radera en specifik autentisering.
{
"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"
}
En specifik autentiserings identifierare.
Mobilnumret som autentiseringen skickades till.
En datumstämpel som visar när autentiseringen skapades.
Visar huruvida autentiseringen har gått ut eller ej.
En datumstämpel som visar när autentiseringen går förfaller.
Visar huruvida en autentiseringen är använd eller ej.
En datumstämpel som visar när autentiseringen användes.
Endpoint: POST /api/authentications/validate
Denna endpoint låter dig validera en autentiseringskod.
{
"Phone": "sample string 1",
"Code": "sample string 2"
}
{
"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"
}
Ett värde av sant eller falskt om koden är giltig respektive ogiltig.
En lista av information gällande en specifik autentisering.
En specifik autentiserings identifierare.
Mobilnumret som autentiseringen skickades till.
En datumstämpel som visar när autentiseringen skapades.
Visar huruvida autentiseringen har gått ut eller ej.
En datumstämpel som visar när autentiseringen går förfaller.
Visar huruvida en autentiseringen är använd eller ej.
En datumstämpel som visar när autentiseringen användes.
Mobilnumret som har autentiserats.
Autentiseringskoden som använts vid autentiseringen.
Endpoint: GET /v2/contacts/meta
Denna endpoint tillhandahåller en summering av den kontaktdata som är lagrad i kontaktsystemet
{
"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
}
]
}
Det totala antalet kontakter lagrade.
En post för varje använd etikett.
Etikettens namn
Antalet lagrade kontakter som tilldelats etiketten
En post för varje använd egenskap.
Namnet/nyckeln för egenskapen.
Antalet kontakter som har ett värde för egenskapen.
Den genomsnittliga längden på egenskapen bland lagrade kontakter.
Det längsta värdet för egenskapen bland lagrade kontaktern.
Det kortaste värdet för egenskapen bland lagrade kontakten.
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
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
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
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.
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).
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.
{
"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"
]
}
Kontaktens ID, används för att referera till en specifik kontakt.
Kontot som äger kontakten.
En dictionary av kontaktegenskaper, som telefonnunner, namn, företagsuppgifter m.m.
Metadata om vissa egenskaper. En dictionary med metadata-egenskaper för varje egenskap med metadata. Saker som valideringsresultat och blockerad status.
En samling etiketter för kontakten. Används oftast för att kategorisera eller gruppera kontakter.
Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att lägga till en kontakt.
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; }
}
Dessa endpoints uppdaterar en samtliga kontakter i perspektivet från en etikett och returnerar en sammanfattning av etiketten i fråga.
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
[
"5d8b19f972c0b7514c5b0f"
"5d8b19f972c0b7515c5b0f"
"5d8b19f972c0b7516c5b0f"
]
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.
{
"labelName": "Coworker",
"usageCount": 3
}
Etikettens namn.
Antalet kontakter som använder etiketten.
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.
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.
Endpoint: GET /v2/blacklist
Denna endpoint låter dig läsa hela din blacklist.
Endpoint: POST /v2/blacklist
Denna endpoint lägger till en post i din blacklist.
Endpoint: GET /v2/blacklist/{msisdn}
Denna endpoint låter dig läsa en specifik post i din blacklist.
Endpoint: PUT /v2/blacklist/{msisdn}
Denna endpoint låter dig uppdatera eller lägga till en post i din blacklist.
Endpoint: DELETE /v2/blacklist/{msisdn}
Denna endpoint låter dig radera en post från din blacklist.
{
"msisdn": "46703541190",
"created": "2019-11-01T16:32:18.253"
}
Det tillagda mobilnumret.
Datumet då posten lades till i blacklisten.
Endpoint: GET /api/me
Denna endpoint ger dig överblick över ditt huvudkonto konto
{
"Account": "string",
"Organization": "string",
"Type": "string",
"Balance": 0.0,
"Currency": "string"
}
Ett enskilt kontos unika ID bestående av prefixet ip1- följt av ett antal siffror.
Företagets/organisations namn som står som ägare till kontot.
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.
Ett enskilt kontos saldonivå. kan bestå av en negativ eller positiv siffra, beroende på vald kostnadsmodell.
Anger vilken valuta ett enskilt konto debiteras i. SEK eller Euro.
Endpoint: GET /api/me/account
Denna endpoint ger dig en detaljlista för ett enskilt konto enligt responsdata-typen nedan.
{
"Key": "string",
"Parent": "string",
"Type": "string",
"Balance": 0.0,
"Currency": "string",
"ID": "string",
"Name": "string"
}
Ett enskilt kontos API-nyckel.
Ett enskilt kontos föräldra-konto.
Ett enskilt kontos kontotyp.
Ett enskilt kontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.
Ett enskilt kontos valuta.
Ett enskilt kontos ID, består av prefixet ip1- följt av ett antal siffror.
Ett enskilts kontos märkning. Exempelvis avdelning eller referens till kontots syfte.
Endpoint: POST /api/me/children
Denna endpoint låter dig skapa ett nytt underkonto, underordnat ditt huvudkonto.
{
"Name": "string"
}
Kontots märkning. Exempelvis avdelningsnamn eller annat namn som anspelar på kontots syfte.
{
"Key": "string",
"Parent": "string",
"Type": "string",
"Balance": 0.0,
"Currency": "string",
"ID": "string",
"Name": "string"
}
Ett underkontots API-nyckel.
Ett underkontos föräldra-konto.
Ett underkontos konto-typ.
Ett underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.
Ett underkontos valuta.
Ett underkontos ID, består av prefixet ip1- följt av ett antal siffror.
Ett underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.
Endpoint: GET /api/me/children
Denna endpoint låter dig lista samtliga underkonton kopplade till ett konto.
Endpoint: GET /api/me/children{child}
Denna endpoint låter dig lista ett enskilt underkonto kopplade till ett konto.
{
"Key": "string",
"Parent": "string",
"Type": "string",
"Balance": 0.0,
"Currency": "string",
"ID": "string",
"Name": "string"
}
Ett enskilt underkontos API-nyckel.
Ett enskilt underkontos föräldra-konto.
Ett enskilt underkontos kontotyp.
Ett enskilt underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.
Ett enskilt underkontos valuta.
Ett enskilt underkontos ID, består av prefixet ip1- följt av ett antal siffror.
Ett enskilts underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.
Endpoint: put /api/me/children/{child}
Denna endpoint låter dig uppdatera ett enskilt underkonto kopplat till ett konto.
{
"ID": "string",
"Name": "string"
}
{
"Key": "string",
"Parent": "string",
"Type": "string",
"Balance": 0.0,
"Currency": "string",
"ID": "string",
"Name": "string"
}
Ett enskilt underkontots API-nyckel.
Ett enskilt underkontos föräldra-konto.
Ett enskilt underkontos konto-typ.
Ett enskilt underkontos saldonivå. Kan bestå av en negativ siffra eller positiv siffra beroende på vilken betalningsmodell som är kopplat till kontot.
Ett enskilt underkontos valuta.
Ett enskilt underkontos ID, består av prefixet ip1- följt av ett antal siffror.
Ett enskilts underkontos märkning. Exempelvis avdelning eller referens till kontots syfte.
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.ip1.net/accounts/ → Inställningar för inkommande SMS (Se bild nedan)
{
"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"
}
Ett unikt ID för det specifika meddelandet.
Ett ID för alla meddelanden som tagits emot i samma begäran som detta meddelande. Detta är vanligtvis bara ett meddelande.
Konto-ID för SMS-kontot som äger meddelandet.
Avsändar-ID för det inkommande meddelandets upphovsman.
Mottagaren av meddelandet (t.ex. ditt virtuella nummer).
Det inkommande meddelandets innehåll.
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.
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.
Anger datakodningsschemat som används för att skicka meddelandet i fråga.
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.
En lista bestående av 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.
När det inkommande SMS:et senast uppdaterades.
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
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
Nedan hittar du ett kodexempel för en callback för inkommande SMS-trafik.
[Route("callback")]
[ApiController]
public class CallbackController : ControllerBase
{
private readonly SqlConnection Connection;
public CallbackController()
{
Connection = new SqlConnection("Connection String");
Connection.Open();
}
[HttpPost("")]
public ActionResult HandleCallback(IncommingSms request)
{
using (SqlCommand cmd = new SqlCommand("INSERT INTO [Messaging].[SmsMessage] ([Sender],[Body]) VALUES (@sender, @body)", Connection))
{
cmd.Parameters.AddWithValue("@sender", request.Sender);
cmd.Parameters.AddWithValue("@body", request.Body);
int result = cmd.ExecuteNonQuery();
}
return Ok();
}
}
public class IncommingSms
{
public string Id { get; set; }
public string BatchId { get; set; }
public string Owner { get; set; }
public string Sender { get; set; }
public string Recipient { get; set; }
public string Body { get; set; }
public string Direction { get; set; }
public int Segments { get; set; }
public string Type { get; set; }
public string Datacoding { get; set; }
public int Priority { get; set; }
public List Statuses { get; set; }
public DateTime Modified { get; set; }
public string Mcc { get; set; }
public string Mnc { get; set; }
}
public class Status
{
public DateTime Created { get; set; }
public int Code { get; set; }
public int Duration { get; set; }
}
Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att skicka ett enskilt SMS.
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());
}
}
$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;
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)
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 UtilsEtt 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-PhonenumberVå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.
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.
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.
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.
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. |
Nedan hittar du samtliga statuskoder för SMPP. Statuskoderna är uppdelade i 4 olika grupper:
Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.
Talar om SMS:ets slutgiltiga status.
Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.
Talar om ifall meddelandet är olevererbart eller andra tekniska fel.
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 |
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 |
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. |
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 |