Messages
Send a message#
POST /v1/messages queues an SMS and answers at once; a phone sends it within seconds.
| Name | Type | Required | Description |
|---|---|---|---|
to | string | yes | Recipient. E.164 recommended; see Phone numbers. |
text | string | yes | The message. At most 6 SMS parts and 2,000 characters; see Limits. |
requestId | string | no | Your own id for this message, 1–100 characters. Sending the same requestId again never creates a second message. |
ttlSec | integer | no | Seconds the message may wait to be sent, 60–86400. Default 86400 (24 hours). After that it becomes expired. |
deviceId | string | no | Send only from this phone (an id from GET /v1/devices). Without it, any of your online phones may send. |
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Your order #1042 has shipped.",
requestId: "order-1042-shipped",
ttlSec: 3600
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Your order #1042 has shipped.",
"requestId" => "order-1042-shipped",
"ttlSec" => 3600,
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"requestId": "order-1042-shipped",
"ttlSec": 3600,
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"status": "pending",
"deviceId": null,
"sim": null,
"error": null,
"requestId": "order-1042-shipped",
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-20T10:15:02.481Z"
}A new message returns 201.
Idempotency with requestId#
Networks fail; retries happen. Send a requestId (for example your order or event id) and retry freely: if a message with that requestId already exists in your workspace, you get 200 with that message instead of a new one. Nothing else in the body is compared.
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Your order #1042 has shipped.","requestId":"order-1042-shipped","ttlSec":3600}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Your order #1042 has shipped.",
requestId: "order-1042-shipped",
ttlSec: 3600
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Your order #1042 has shipped.",
"requestId" => "order-1042-shipped",
"ttlSec" => 3600,
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"requestId": "order-1042-shipped",
"ttlSec": 3600,
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Your order #1042 has shipped.",
"status": "sent",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"error": null,
"requestId": "order-1042-shipped",
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-20T10:15:02.481Z"
}Choosing the phone#
With deviceId only that phone may take the message. It is not handed to another phone if that one fails, so the message fails or expires instead. A deviceId that isn't an active phone of your workspace gets 422 device_not_found.
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Sent from a chosen phone.","deviceId":"6650e0a1e4b0a1b2c3d4e500"}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Sent from a chosen phone.",
deviceId: "6650e0a1e4b0a1b2c3d4e500"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Sent from a chosen phone.",
"deviceId" => "6650e0a1e4b0a1b2c3d4e500",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Sent from a chosen phone.",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Sent from a chosen phone.",
"status": "pending",
"deviceId": null,
"sim": null,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
}Get a message#
GET /v1/messages/{id} returns the message with its timeline in events. An id from another workspace is 404 not_found, exactly like an id that doesn't exist.
curl "https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const res = await fetch("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6", {
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.get(
"https://sms.liscosolutions.com/v1/messages/6650f1c2e4b0a1b2c3d4e5f6",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json()){
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Order #1042 is ready for pickup.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:14.020Z",
"expiresAt": "2026-11-21T09:15:02.481Z",
"events": [
{
"at": "2026-11-20T09:15:02.481Z",
"type": "queued",
"deviceId": null,
"sim": null,
"detail": null
},
{
"at": "2026-11-20T09:15:03.902Z",
"type": "claimed",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": null,
"detail": null
},
{
"at": "2026-11-20T09:15:08.377Z",
"type": "attempt_failed",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"detail": "no_service"
},
{
"at": "2026-11-20T09:15:10.651Z",
"type": "sent",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"detail": null
},
{
"at": "2026-11-20T09:15:14.020Z",
"type": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"detail": null
}
]
}Each event has at (time), type, the deviceId and sim involved (if any) and a detail such as an error code:
type | Meaning |
|---|---|
queued | Accepted by the API. |
claimed | A phone took it. |
attempt_failed | Sending failed on one phone; it goes back to the queue for another phone. |
requeued | Returned to the queue because the phone holding it went offline, or was unlinked. |
sent | The phone sent it. |
delivered | The network confirmed delivery. |
failed | Every allowed attempt failed; detail holds the error. |
expired | ttlSec passed before it was sent. |
List messages#
GET /v1/messages returns your workspace's messages, newest first.
| Query parameter | Type | Description |
|---|---|---|
status | string | Only this status: pending, claimed, sent, delivered, failed or expired. |
limit | integer | 1–100, default 20. |
cursor | string | The nextCursor of the previous page. |
curl "https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const res = await fetch("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2", {
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.get(
"https://sms.liscosolutions.com/v1/messages?status=delivered&limit=2",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json()){
"data": [
{
"id": "6650f1c2e4b0a1b2c3d4e5f6",
"to": "+905321234567",
"text": "Order #1042 is ready for pickup.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 1,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
},
{
"id": "6650f0a8e4b0a1b2c3d4e5e1",
"to": "+905321234567",
"text": "Your appointment is confirmed.",
"status": "delivered",
"deviceId": "6650e0a1e4b0a1b2c3d4e500",
"sim": 2,
"error": null,
"requestId": null,
"createdAt": "2026-11-20T09:15:02.481Z",
"updatedAt": "2026-11-20T09:15:02.481Z",
"expiresAt": "2026-11-21T09:15:02.481Z"
}
],
"nextCursor": "6650f0a8e4b0a1b2c3d4e5e1"
}nextCursor is null on the last page. The list includes every message of the workspace: those you sent through the API, codes from /v1/otp/send, and test messages sent from the dashboard.
The message object#
| Field | Type | Description |
|---|---|---|
id | string | The message id. |
to | string | Recipient in E.164. |
text | string | The text. For OTP messages the code is always shown as •. |
status | string | pending, claimed, sent, delivered, failed or expired; see Message statuses. |
deviceId | string or null | The phone that holds or sent it. |
sim | integer or null | The SIM slot it was sent from (1 or 2). |
error | string or null | Why it failed or expired (e.g. no_service, generic_failure, expired). |
requestId | string or null | Your requestId, if you sent one. |
createdAt | string | When it was queued (ISO 8601, UTC). |
updatedAt | string | Last change. |
expiresAt | string | When it expires if not sent by then. |