​

SMS integration loop: send, deliver, reply, and recover

​

1. Map the endpoints

https://api.orbit.devotel.io/api/v1

POST /messages/sms
  → 202 { data.id, data.status, data.segments }
  → message.sent / message.delivered / message.failed
  → message.received (the recipient replies)
  → POST /messages/sms (your reply)
  → compensate your business action if delivery fails

​

2. Start in the sandbox

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/webhooks/orbit",
    "events": [
      "message.sent",
      "message.delivered",
      "message.failed",
      "message.received"
    ]
  }'

​

3. Send the message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-sms-v1" \
  -d '{
    "to": "+15005550002",
    "from": "+18005551234",
    "body": "Your order 1234 has shipped. Reply STATUS for tracking."
  }'

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "direction": "outbound",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "test_mode": true
  }
}

​

Body fields

• to is the recipient in E.164 format, such as +14155552671. Normalize user-entered numbers with the E.164 formatter tool before sending.
• from is your owned, SMS-capable number. It is optional when Orbit can choose an eligible sender, but pass it explicitly when you need stable two-way threading.
• body is the message text. It must be within the API payload-character limit. Its encoding determines how many carrier segments the message uses.
• Idempotency-Key is a caller-generated key for safe retries. Reusing the key with the same body returns the original result; changing the body with the same key is rejected. Never use a new key to blindly retry a send after an uncertain timeout until you have reconciled the original request.

​

4. Wire delivery and reply webhooks

​

Delivery receipts

• message.sent means the send was accepted downstream. It is not delivery.
• message.delivered means the carrier confirmed delivery to the handset.
• message.failed means a terminal failure such as a handset rejection, block, expiry, or no-receipt outcome. Read data.status, error_code, and error_message when present.

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "data": {
    "message_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "channel": "sms",
    "status": "delivered",
    "is_terminal": true
  }
}

​

Inbound replies

1. Verify the signature over the raw body.
2. Deduplicate the event id.
3. Persist the inbound message and associate it with the conversation pair.
4. Return 200.
5. Queue any business action or reply.

​

5. The test

​

Roll back a failed business action

• Store your order or notification state as pending_sms with the message_id.
• On message.delivered, mark the notification complete.
• On message.failed or an expired no-receipt outcome, mark the action for retry or compensation according to your own tenant policy.
• Retry only with a new idempotency key after correcting the cause or choosing a new recipient. Do not send a duplicate merely because a webhook was retried.
• If a late delivered receipt corrects a prior terminal event, accept the correction and reconcile your local state by message_id.

​

Next steps

• Your first SMS, end to end — provision a number and build the longer first-send path.
• Send & Receive Messages — canonical inbound webhook and reply flow.
• Wire delivery-report webhooks per channel — event semantics, signatures, sandbox rehearsal, and debugging.
• API error handling by example — validation, rate limits, and retryable failures.
• SMS segment and cost calculator — preflight encoding, segments, and cost.
• E.164 formatter tool — normalize numbers before the send.