Conversations · Ody Docs

Threads between one of your Ody numbers and an outside party: list them, read the full timeline, and mark them open or done.

A conversation is one thread between one of your Ody numbers and an outside party (one person, or several people in a group text). Every message, call, voicemail, internal note and system event in the thread is an activity, in time order. It is the same object your team sees as a row in the inbox.

#The conversation object

id uuid — Unique identifier.
inboxId uuid — The inbox the thread lives in.
numberE164 string | null — The Ody number on your side of the thread.
participants array of strings — The outside party's E.164 numbers.
contactName string — Display name: the contact's name, or the formatted number.
status "open" | "done" — Inbox state. A new inbound message re-opens a done thread.
assigneeUid string | null — Teammate the thread is assigned to.
lastActivityAt timestamp — When the latest activity happened.
preview string | null — Snippet of the latest activity.
unread integer — Unread count for the key's creator.

The conversation object

{
  "id": "c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  "inboxId": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
  "numberE164": "+15125550100",
  "participants": ["+15125550123"],
  "contactName": "Ada Lovelace",
  "status": "open",
  "assigneeUid": null,
  "lastActivityAt": "2026-10-14T18:05:42.000Z",
  "preview": "Can I move my appointment to Friday?",
  "unread": 1
}

#The activity object

id uuid — Unique identifier.
type string — message, call, voicemail, internal_note or system.
direction "inbound" | "outbound" | null — null for notes and system events.
authorUid string | null — The teammate who sent it, if any.
body string | null — Message text, or the note's text.
media array — Attachments: url (a short-lived signed link), contentType, size, filename.
deliveryStatus string | null — For messages: queued, sent, delivered, failed, received, or simulated (sent with a test key).
call object | null — For calls and voicemails: status, duration, recording, AI summary and so on.
callTranscript array | null — Speaker-labelled transcript turns, once transcription finishes.
aiTags array of strings — Labels the AI attached (for example appointment).
createdAt timestamp — ISO 8601.

#List conversations

GET/v1/api/conversations

Returns conversations with the most recent activity first. Results are cursor-paginated.

Scope: conversations:read

Query parameters

status "open" | "done" — Filter by inbox state. Omit for both.
limit integer — 1–100, default 50.
cursor string — nextCursor from the previous page.

Returns { conversations: Conversation[], nextCursor: string | null }.

curl "https://api.ody.co/v1/api/conversations?status=open&limit=25" \
  -H "Authorization: Bearer $ODY_API_KEY"

const { conversations } = await ody.conversations.list({ status: "open", limit: 25 });

page = client.conversations.list(status="open", limit=25)

#Retrieve a conversation

GET/v1/api/conversations/:id

Returns the conversation and its full activity timeline, oldest to newest: messages with media, calls with transcripts and AI summaries, voicemails, notes and system events.

Scope: conversations:read

Returns { conversation, activities: Activity[] }, or 404 not_found.

curl https://api.ody.co/v1/api/conversations/c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $ODY_API_KEY"

const { conversation, activities } = await ody.conversations.get("c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b");

thread = client.conversations.get("c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b")

Response

{
  "conversation": { "id": "c4f1a2b3-…", "status": "open", "contactName": "Ada Lovelace" },
  "activities": [
    {
      "id": "a1…",
      "type": "message",
      "direction": "inbound",
      "body": "Can I move my appointment to Friday?",
      "media": [],
      "deliveryStatus": "received",
      "aiTags": ["appointment"],
      "createdAt": "2026-10-14T18:05:42.000Z"
    }
  ]
}

#Update a conversation

PATCH/v1/api/conversations/:id

Marks the thread done (archived from the open inbox) or open again. This is the API equivalent of the inbox's Done button.

Scope: conversations:write

Body

status "open" | "done" required

Returns { conversation: { id, status } }.

curl -X PATCH https://api.ody.co/v1/api/conversations/c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $ODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

await ody.conversations.setStatus("c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b", "done");

client.conversations.set_status("c4f1a2b3-5d6e-4f70-8a9b-0c1d2e3f4a5b", "done")