Worked request and response samples

Copy a request as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope, shown under Error envelope.

Inbound message flow

An inbound message arrives on one of your channels (an SMS carrier webhook, a WhatsApp callback, an email ingest, the web-chat widget, and so on) and is folded onto one normalized shape. Every message you list or reply to below is the same object — the carrier differences are already folded out. For the webhook side of that flow — the data.normalized block stamped on inbound message and opt-out envelopes, one kind discriminator, and the single normalized.inbound subscription that covers the whole inbound family — see Normalized inbound event envelope.

1. List conversations

GET /api/v1/conversations/

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/conversations/" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/conversations/', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/conversations/", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/conversations/", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/conversations/')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/conversations/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
      "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
      "contact_phone": "+14155552134",
      "channel": "sms",
      "status": "open",
      "assigned_to": "usr_3f8a1c2b9d4e5f60718293a4b5c6d7e8",
      "last_message_at": "2026-08-01T11:58:00.000Z",
      "unread_count": 1
    }
  ],
  "meta": {
    "request_id": "req_list",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

2. Open one conversation

GET /api/v1/conversations/{id}

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/conversations/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/conversations/{id}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/conversations/{id}", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/conversations/{id}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/conversations/{id}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/conversations/{id}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
    "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
    "contact_phone": "+14155552134",
    "channel": "sms",
    "status": "open",
    "assigned_to": "usr_3f8a1c2b9d4e5f60718293a4b5c6d7e8",
    "agent_active": true,
    "created_at": "2026-08-01T09:30:00.000Z",
    "last_message_at": "2026-08-01T11:58:00.000Z",
    "unread_count": 1
  },
  "meta": {
    "request_id": "req_conv",
    "timestamp": "2026-08-01T12:01:00.000Z"
  }
}

The message transcript is a separate read: GET /api/v1/conversations/{id}/messages. Each element of its data array looks like:

{
  "id": "msg_7a1b2c3d4e5f6071829304b5c6",
  "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
  "direction": "inbound",
  "channel": "sms",
  "from": "+14155552134",
  "body": "Do you open on Sundays?",
  "status": "delivered",
  "created_at": "2026-08-01T11:58:00.000Z"
}

For exports, GET /api/v1/conversations/export?format=json&include_messages=true inlines each conversation’s full transcript in one response.

3. Post a reply

POST /api/v1/conversations/{id}/reply

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/conversations/{id}/reply" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/conversations/{id}/reply', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/conversations/{id}/reply", headers=headers, json={
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/conversations/{id}/reply", bytes.NewBuffer([]byte(`{
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/conversations/{id}/reply')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/conversations/{id}/reply');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "body": "Yes — we're open 10:00 to 16:00 on Sundays.",
  "from": "+14155550100"
}
JSON);
echo curl_exec($ch);

body and from are the usual pair; media_url works on its own when you are sending an attachment. channel optionally overrides the reply channel, and email replies can carry subject, cc, and bcc top-level. A successful reply answers 202 Accepted with the message status set to queued — the message is accepted onto the conversation and delivery continues asynchronously, so poll GET /:id/messages or your message.delivered webhook for the final status:

{
  "data": {
    "id": "msg_5d6e7f8a9b1c2d3e4f50617c8d",
    "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
    "direction": "outbound",
    "channel": "sms",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_reply",
    "timestamp": "2026-08-01T12:02:00.000Z"
  }
}

4. Reply to a closed conversation

closed, archived, and snoozed conversations reject replies so a scripted caller cannot bill a send or disturb a deferred thread — reopen first with POST /api/v1/conversations/{id}/reopen. The message names the status so your client can point the operator at the next action:

422

{
  "error": {
    "code": "CONVERSATION_TERMINAL",
    "status": 422,
    "message": "Cannot reply to a closed conversation. Reopen it first."
  },
  "meta": {
    "request_id": "req_reply_terminal",
    "timestamp": "2026-08-01T12:03:00.000Z"
  }
}

Error envelope

Malformed input returns the standard validation envelope:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Either a message body or a media attachment is required"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Worked request and response samples