RESTful SMS 2.0

Introduktion

Här hittar du allt du behöver för att koppla vårt RESTful SMS 2.0 API till ditt system eller applikation.

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.


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.


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.

Kodexempel
                                      
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/api/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": "string",
        "recipients": {"46712345678"},
        "body": "string",
        "type": sms,
        "datacoding": gsm,
        "priority": 1,
        "reference": "Test",
        "tags": [
            "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());
        }
}
                                    
                                
                                      
$conf = array(
    'password' => 'API key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'POST',
    'endpoint' => 'batches',
);

$message = array(
    "sender" => "ip1sms",
    "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;
                                    
                                
                                      
Dim account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"

Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/api/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 With
{
    Key .sender = "iP1sms",
    Key .recipients = New List(Of String)() From {"46712345678"},
    Key .body = "Test",
    key .type = "sms",
    key .datacoding = "gsm",
    key .priority = 1,
    key .reference = "Test",
    key .tags = "Test SMS"
}

Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("batches", sms)


End Sub`;
                                    
                                

Statuskoder

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.


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

RESTful SMS 1.0

Introduktion

Här hittar du allt du behöver för att koppla vårt RESTful SMS API 1.0 till ditt system eller applikation. Med hjälp av ett SMS API kan du enkelt skräddarsy dina egna SMS-funktioner.


Autentisering

Alla requester till vårt RESTful SMS API 1.0 kräver autentisering med dina kontouppgifter. Vi använder oss av autentisering via Konto-ID och API-nyckel genom HTTP Basic. Dessa uppgifter kan du hitta genom att logga in i vår webbapplikation.

För att skapa din Basic Authentication sträng, ta ditt kontonummer (ex. ip1-12345) och din API-nyckel (ex. cCnbXFfyTM5BTKh7uNV#tz) och kör dem genom en Base64 encoder i följande format: ip1-12345:CnbXFfyTM5BTKh7uNV

Du bör få ut en sträng som ser ut ungefär så här: aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==

Du har nu genererat din HTTP Basic Authentication-sträng, som du sedan anger som en HTTP header på följande sätt:

Authorization: Basic aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==


Anropsstruktur

api.ip1sms.com är den URL som ligger som bas för samtliga API-anrop är och kan nås antingen via HTTP eller HTTPS och kan användas på följande sätt:

http://api.ip1sms.com

eller

https://api.ip1sms.com

Resten av ovannämnda URL är olika för olika anrop och kallas för anropets URI. En URI pekar i de flesta fall till en entitet eller samling av det som anropats (ex. api/contacts pekar på en samling av kontakter). HTTP verbet förtydligar operationen som behöver göras på målet (ex. GET läser och POST skapar).

Kodexempel
                                          
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var sms = new OutgoingSMS()
    {
        From = "iP1",
        Numbers = new List() { "46123456789" },
        Contacts = new List(),
        Groups = new List(),
        Message = "test",
        Prio = 1,
        Email = false
    };

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

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                        
                                    
                                          
$conf = array(
    'account' => 'ip1-xxxxx',
    'password' => 'apiKey',
    'apiUrl' => 'api.ip1sms.com',
    'method' => 'POST',
    'endpoint' => '/api/sms/send',
);

$message = array(
    'Numbers' => ['4673055555'],
    'From' => 'iP.1',
    'Message' => "Test message via iP.1's REST API",
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$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 account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"

Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))

Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)

Dim sms As New With
    {
        Key .From = "iP1sms",
        Key .Numbers = New List(Of String)() From {"46123456789"},
        Key .Contacts = New List(Of Integer)(),
        Key .Groups = New List(Of Integer)(),
        Key .Message = "Test", Key .Email = False
    }

Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("sms/send", sms)


End Sub`;
                                        
                                    

RESTful SMS Survey 1.0

Beskrivning

Vårt SMS Survey API låter dig skicka undersökningar via SMS. Perfekt för att automatisera kundundersökningar, vid exempelvis ordrar eller andra typer av registreringar. Du kan enkelt skapa, skicka och hantera enkäter direkt via API:et.


Kodexempel

                                          
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var survey = new OutgoingSurvey()
    {
        From = "iP1",
        Numbers = new List() { "46123456789" },
        Contacts = new List(),
        Groups = new List(),
        Message = "test survey",
        Prio = 1,
        Email = false
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("surveys/{survey}/send", survey);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Survey Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                        
                                    
                                          
$conf = array(
    'account' => 'ip1-xxxxx',
    'password' => 'apiKey',
    'apiUrl' => 'api.ip1sms.com',
    'method' => 'POST',
    'endpoint' => '/surveys/{survey}/send',
);

$message = array(
    'Numbers' => ['4673055555'],
    'From' => 'iP.1',
    'Message' => "Test message via iP.1's REST API",
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$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 account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"

Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))

Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)

Dim survey As New With
    {
        Key .From = "iP1sms",
        Key .Numbers = New List(Of String)() From {"46123456789"},
        Key .Contacts = New List(Of Integer)(),
        Key .Groups = New List(Of Integer)(),
        Key .Message = "Test", Key .Email = False
    }

Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("surveys/{survey}/send", survey)


End Sub`;
                                        
                                    

RESTful 2FA

Beskrivning

Genom att koppla på 2FA vid exempelvis registrering av nya konton kan du enkelt säkerställa att personen har angivit rätt uppgifter genom att bekräfta användarens telefonummer. Koden skickas som ett SMS till angivet nummer på nolltid.

När du integrerar tvåfaktorsautentisering via SMS från iP.1 få4r du automatisk tillgång till vår globala spamfilterlista som innehåller tusentals virtuella nummersom använts vid illasinnade bot-registreringar.

Kodexempel


Statuskoder

Nedan hittar olika statuskoder för både HTTP-anrop samt status på SMS.

Statuskoder HTTP
Code Name Description
200 OK Standard success kod, används vid lyckade anrop, förutom vid skapade entiteter.
201 Created Används enbart vid skapande av entiteter. Headern LocationAnvänds för att peka ut nyligen skapade entiteter.
400 Bad Request Används när användarangiven information innehåller fel, respons-bodyn kan innehålla information kring vilken data som är invalid och varför.
401 Unauthorized Används när autentiseringsinformation saknas eller är felaktig, eller om den autentiserade användaren inte har behörighet att anropa API:et.
403 Forbidden Används vid lyckad autentisering, men att anropet försöker nå en entited eller samling av entiteter som användaren inte har behörighet att nå. Statusbeskrivningen kan innehålla ytterligare information.
404 Not Found Används när vid försök att nå en entitet eller samling av entiter som inte finns eller om anropet försöker nå en URI som är felaktig.
405 Method Not Allowed Används vid försök att använda ett HTTP verb som inte går att använda för angiven entitet eller samling av entiteter.
415 Unsupported Media Type Används vid försök att skicka annan data än JSON eller om anropet saknar en Content-Type header.
500 Internal Server Error Används generellt vid fel, om ingen annan felkod är mer relevant. Response bodyn kan innehålla ytterligare information.
Statuskoder SMS
statuskod Beskrivning
0 Levererad till Gateway
1 Misslyckades att logga in på Gateway
2 Ogiltigt innehåll i meddelandet
3 Ogiltigt format på telefonnumret
4 Otillräckligt saldo
10 Mottagen av Gateway
11 Tidsinställd leverans
12 Tidsinställd leverans avbruten
21 Levererad till GSM-nätet
22 Levererad till mobiltelefon
30 Otillräckligt saldo
41 Ogiltigt innehåll i meddelandet
42 Internt fel
43 Leverans misslyckades
44 Leverans misslyckades
45 Ogiltigt telefonnummer
50 Generellt leveransfel
51 Leverans till GSM-nätet misslyckades
52 Leverans till telefon misslyckades
100 Otillräckligt saldo
101 Ogiltiga kontouppgifter
110 Parameterfel

SMS Gateway (Soap) Deprecated


Kodexempel
                            
$conf['apiurl'] = 'https://web.smscom.se/sendsms/sendsms.asmx?wsdl';
$conf['mmsapiurl'] = 'https://web.smscom.se/mms/mms.asmx?wsdl';
$conf['account'] = 'ip1-xxxxx';  
$conf['password'] = 'API-Key'; 

$conf['to'] = '46712345678'; 
$conf['from'] = 'iP1';
$conf['prio'] = '1';
$conf['msg'] = 'Test message via iP.1 API (Web Service)';
$conf['msg_at'] = "Test send at message via iP.1 API (Web Service)";
$conf['msg_bundle'] = "Test bundle message via iP.1 API (Web Service)";

$client = new SoapClient($conf['apiurl']);
$mmsClient = new SoapClient($conf['mmsapiurl']);

$result = $client->balans(array('konto'=>$conf['account'], 'passwd' => $conf['password']));
echo 'Balnace: ' . $result->balansResult;

$smsresult = $client->sms(array('konto'=>$conf['account'], 'passwd' => $conf['password'], 'till' => $conf['to'], 'from' => $conf['from'], 'meddelande' =>$conf['msg'], 'prio' => $conf['prio']));

echo 'Result of SMS: ' . $smsresult->smsResult;
                            
                        
Dokumenation SMS Gateway (Soap)

Deprecated Detta API är deprekerat och kommer inte längre att vidareutvecklas. Vi rekommenderar er att använda något av våra REST API:er


Fullständig dokumentation

SMS Gateway (http) Deprecated


Kodexempel

                            
$conf['account'] = 'ip1-xxxx';  
$conf['password'] = 'api-key'; 
$conf['apiurl'] = 'https://web.smscom.se/sendsms.aspx';

$conf['to'] = '4673055555';     
$conf['from'] = 'iP.1';        
$conf['msg'] = 'Test message via iP.1 HTTP Request';       
$conf['prio'] = '1';

$data = http_build_query(array('acc'=>$conf['account'],'pass'=>$conf['password'],'msg'=>  $conf['msg'],'from'=>$conf['from'],'to'=> $conf['to'],'prio'=>$conf['prio'], 'type' => ''));
        

$opts = array('http' =>
    array(
        'method'  => 'GET',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $data
    )
);

$context  = stream_context_create($opts);            
$result = file_get_contents($conf['apiurl'] . '?' . $data, false, $context);

echo 'Result/SMS ID: ' . $result;
                            
                        
Dokumenation SMS Gateway (HTTP)

Deprecated Detta API är deprekerat och kommer inte längre att vidareutvecklas. Vi rekommenderar er att använda något av våra REST API:er


Fullständig dokumentation