​

Extension SMS

• GET /threads — the inbox: per-peer conversation summaries with unread counts, newest first.
• GET /thread — one conversation: every SMS exchanged with a single peer, newest first.
• POST /send — send an SMS from the extension’s DID.
• POST /read — mark a peer’s inbound messages read.

​

Access and roles

• Reading (GET /threads, GET /thread) requires the voice:read or voice:write scope.
• Writing (POST /send, POST /read) requires an owner, admin, developer, or agent role and the voice:write scope, server-side. The dashboard’s role gate is a UI affordance — an API key with only voice:read gets a 403 on /send even though reads succeed.

​

Read the thread list

curl "https://api.orbit.devotel.io/api/v1/voice/extension-sms/threads?from=%2B13035550142&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "from": "+13035550142",
    "threads": [
      {
        "peer": "+12025550113",
        "messageCount": 12,
        "unreadCount": 2,
        "lastMessageAt": "2026-08-31T14:07:21.000Z",
        "lastBody": "Can you confirm the booking for Thursday?",
        "lastDirection": "inbound"
      }
    ]
  },
  "meta": { "request_id": "req_911d1c2a", "timestamp": "2026-08-31T14:08:02.113Z" }
}

​

Send an SMS

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/extension-sms/send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"from": "+13035550142", "to": "+12025550113", "body": "Confirmed for Thursday at 3 pm."}'

{
  "data": { "id": "msg_4ac1e7d9", "status": "queued" },
  "meta": { "request_id": "req_52ab00f1", "timestamp": "2026-08-31T14:10:44.003Z" }
}

​

Common send rejections

• 403 FORBIDDEN — the from number is not an active DID the organization owns. Check the number picker; this check runs on all four endpoints.
• 422 RECIPIENT_OPTED_OUT — the recipient opted out of SMS; no further sends to them succeed until they opt back in per your organization’s opt-out policy.
• skipped status with a reason — a tenant-owned suppression policy accepted but held the send (for example, duplicate_content when the exact same body already reached that recipient inside your duplicate-suppression window, or opted_out). A skipped result releases any consumed monthly quota slot, matching the opt-out path.

​

Mark a thread read

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/extension-sms/read" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"from": "+13035550142", "peer": "+12025550113"}'

{
  "data": { "from": "+13035550142", "peer": "+12025550113", "markedRead": 2 },
  "meta": { "request_id": "req_77c3d054", "timestamp": "2026-08-31T14:12:09.812Z" }
}

​

Operating limits

• Owned, active numbers only. Every endpoint validates from against your organization’s active phone numbers before reading or sending. Anything else is refused (403), and text-spoofing a released or foreign number is not possible.
• Body size. 1–1,600 characters per SMS; longer texts must be split client-side or sent as an MMS attachment via media_url.
• Rate limits. Reads and writes use the standard authenticated read/write rate limits, same as the rest of the voice surface.
• Delivery attribution. Every send writes an audit-log entry with the from number, destination, and acting user.

​

Compliance and quiet hours

• Opt-out lists — a recipient who opted out gets a 422 (RECIPIENT_OPTED_OUT) instead of a delivery.
• Quiet hours — if your organization has opted into per-channel quiet hours (organization settings), an Extension SMS send is evaluated against them like any other send; transactional traffic resolves as transactional and flows 24/7, while sends tagged as marketing are blocked during the restricted window. If you have not enabled quiet hours, sends are unrestricted. Schedule-sensitive texting (for example, appointment reminders an agent sends at night) should be understood against your organization’s quiet-hours settings, not assumed outside them.
• Duplicate-content suppression — if your organization enables the duplicate-message window, a repeated identical body returns skipped with reason: "duplicate_content".

​

Extension SMS vs the Messages API