Skicka SMS
Quick start
Använd exemplet nedan och byt ut “API_NYCKEL” mot en bearer token som du skapar i användarportalen.
curl -X POST "https://api.ip1sms.com/v2/batches" \
-H "Authorization: Bearer API_NYCKEL" \
-H "Content-Type: application/json" \
-d '{
"sender": "iP1",
"recipients": [
"MOTTAGARNUMMER"
],
"body": "Ett fint meddelande skickat från iP.1 SMS API"
}'
Anrop
Endpoint: /v2/batches
Metod: POST
Content-Type: application/json
Exempel på anropsdata
{
"sender": "iP1",
"recipients":[
"456189040623",
"175368927054",
"392094880589",
"568798567631"
],
"body": "A very nice message",
}
Exemplet ovan innehåller anropsdatan med de obligatoriska fälten sender, recipients och body, som krävs för att skicka ett SMS-meddelande. Se under rubriken Fält för anropsdata för en lista av samtliga fält och dess beskrivningar.
Fält för anropsdata
| Fältnamn | Obligatoriskt | Typ | Beskrivning och Villkor | Exempel |
|---|---|---|---|---|
| sender | Ja | String |
Ett Anrop kommer att avslås om sender:
|
|
| recipients | Ja | Array |
Ett Anrop kommer att avslås om recipients:
|
|
| recipients – templating | Nej | Nestat Objekt |
För att använda mallsystemet 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. |
|
| body | Ja | String |
Ett anrop kommer att misslyckas om body:
|
|
| type | Nej | String |
Det finns två typer: sms och flash.
sms.
|
|
| datacoding | Nej | String |
Det finns två typer tillgängliga:
gsm är satt, kommer meddelanden som kräver
ucs (utökade tecken) att nekas. Standard är
ucs.
|
|
| priority | Nej | Integer |
Används för meddelanden som behöver levereras snabbt. Tillåtna värden
är 1 (standard, lägsta) och 2 (högsta).
Att sätta prioritet 2 ökar priset per SMS (10 öre för
svenskt konto, € 0.01 för internationellt konto).
|
|
| deliveryWindows | Nej | Array |
Möjlighet att schemalägga utskick under specifika tidsfönster (t.ex.
vardagar 10:00-10:15). Du kan ha flera fönster.
Parsing-regler:
|
|
| deliveryReportUrl | Nej | String |
Om en URL anges skickas statusuppdateringar (leveransrapporter) dit
via POST. Rapporterna är separerade för varje mottagare
och status.
|
|
| reference | Nej | String |
Tillåter användaren att sätta ett eget ID eller referens.
Restriktioner:
null är standardvärde.
|
|
| tags | Nej | string |
En array av taggar som används för att kategorisera eller sortera batcher. Gör det möjligt att filtrera vid listning av batcher. |
|
Respons
Responsen på ett anrop består av en JSON med fält som beskriver batchens innehåll.
Exempel på responsdata
Nedan hittar du ett exempel på svar vid lyckad request mot batches endpoint. Se under rubriken Fält för responsdata för en detaljerad beskrivning av samtliga fält i responsen.
{
"id": "5bc86b6e85c7209830f96936",
"sender": "46101606060",
"body": "Hi my name is {name}",
"owner": "ip1-XXXXX",
"direction": "MT",
"type": "flash",
"datacoding": "GSM",
"priority": 1,
"templated": true,
"priceSummary": {
"total": 0.125,
"currency": "EUR",
"average": 0.0416
},
"messageSummary": {
"101": {
"messages": 43,
"sms": 86
},
"102": {
"messages": 3,
"sms": 6
},
"201": {
"messages": 142,
"sms": 284
}
},
"deliveryWindows": [
{
"opens": "ISO-8601 string",
"closes": "ISO-8601 string"
},
{
"opens": "ISO-8601 string",
"closes": "ISO-8601 string"
}
],
"status": 112,
"deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
"reference": "A client reference",
"tags": ["marketing", "auth", "etc"],
}
Fält för responsdata
| Fältnamn | Typ | Beskrivning | Exempel | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | String |
Batchens ID. | |
||||||||||||||||||
| sender | String |
Avsändaren som används för ett eller flera meddelanden. | |
||||||||||||||||||
| body | String |
Den ursprungliga bodyn, alltså meddelandetexten, som skickas, före mallar har tillämpats, enligt den ursprungliga requesten. |
|
||||||||||||||||||
| owner | String |
Kontonumret för SMS-kontot som står som ägare batchen | |
||||||||||||||||||
| direction | String |
Talar om ifall meddelandet skickades eller togs emot av vårt system.
|
|
||||||||||||||||||
| type | String |
Beskriver meddelandets typ.
|
|
||||||||||||||||||
| datacoding | String |
Talar om vilken teckenuppsättning som används för batchen.
|
|
||||||||||||||||||
| priority | Integer |
Beskriver vilken prioritet som används för batchen. |
|
||||||||||||||||||
| templated | boolean |
Talar om ifall batchens body (Meddelandetxt) innehåller templating. |
|
||||||||||||||||||
| priceSummary | array |
Ger en summering av batchens kostnad samt vilken valuta som debiterat kontot. |
|
||||||||||||||||||
| messageSummary | array |
Ger en summering av antalet meddelande i batchen uppdelat i statusgrupper. |
|
||||||||||||||||||
| deliveryWindows | Array |
Visar batchens tidsfönster | |
||||||||||||||||||
| status | Integer | Aktuell status för batchen. Härleds från riktningen och den senaste statusen för batchens meddelanden. Tillgängliga statusar är följande:
|
|
||||||||||||||||||
| deliveryReportUrl | String |
Visar eventuella callback-url för mottagande av leveransrapporter till extern mjukvara. |
|
||||||||||||||||||
| reference | String |
Visar batchens referens om sådan finns. |
|
||||||||||||||||||
| tags | string |
visar eventuella taggar i batchen. |
|
Kodexempel
Nedan hittar du ett enkelt kodexempel med autentisering och funktionalitet för att skicka ett SMS.
Skicka ett SMS i 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<string>() { "46712345678" },
Body = "Test message rest v2",
};
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; }
}
Skicka ett SMS i 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",
);
$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;
Skicka ett SMS i Visual Basic
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"
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
End Class
Felsökning
I detta avsnitt hittar du HTTP-felstatuskoder och vanligt förekommande fel för enskilda anropsfält.
Vanliga felstatuskoder
| Kod | Namn | Betydelse | Klass |
|---|---|---|---|
| 400 | Bad Request | Servern kan inte förstå förfrågan, ofta på grund av ogiltig syntax (t.ex. felaktigt formaterad JSON-data). | Klientfel |
| 401 | Unauthorized | Klienten måste autentisera sig för att få åtkomst till resursen (t.ex. saknas en API-nyckel eller inloggningstoken). | Klientfel |
| 403 | Forbidden | Klienten har autentiserat sig, men saknar behörighet att utföra åtgärden (t.ex. en vanlig användare försöker radera andras data). | Klientfel |
| 404 | Not Found | Servern har inte hittat resursen som efterfrågades (t.ex. en specifik resurs med ett ID som inte finns). | Klientfel |
| 405 | Method Not Allowed | HTTP-metoden som används är inte tillåten för resursen (t.ex. försöker POST:a till en resurs som endast accepterar GET). | Klientfel |
| 409 | Conflict | Begäran kunde inte slutföras på grund av en konflikt med resursens nuvarande tillstånd (t.ex. försöker skapa en resurs som redan existerar). | Klientfel |
| 500 | Internal Server Error | Ett generiskt felmeddelande som indikerar att ett oväntat tillstånd på servern hindrade den från att uppfylla begäran. | Serverfel |
| 503 | Service Unavailable | Servern är för närvarande inte tillgänglig (t.ex. överbelastad eller nere för underhåll). | Serverfel |
Felsökning specifika fält
Varje felaktigt anrop som triggar en felstatuskod innehåller en detaljerad beskrivning i respons-bodyn. Du kan extrahera denna text programmatiskt för att få en mer tydlig bild av vad som gick fel. Om du inte kan avläsa felet i response-bodyn så kan du utgå från listan nedan för att felsöka ditt misslyckade anrop.
sender
- Säkerställ att tilläggstjänsten "Valfri avsändare" finns aktiverad på kontot. Du kan aktivera "Valfri avsändare" i webshopen eller via någon av våra webbtjänster.
- Säkerställ att avsändaren finns registrerad på kontot i användarportalen.
- Om avsändaren består av ett nummer, säkerställ att numret inte är längre än 15 siffror.
- Om en alfanumerisk avsändare används, säkerställ att den består av 3 - 11 tecken, Aa - Zz, 0 - 9.
body
- Säkerställ att meddelandetexten inte överstiger 2000 tecken.
- Kontrollera texten innehåll för att utesluta att den innehåller olämpligt eller reglerat innehåll vilket kan trigga spärrtjänster hos vissa operatörer.
recipients
- Se till att numret du försöker skicka till är i formatet MSISDN (4612345678), alltså ett nummer med landskod, utan + eller dubbla nollor framför.