Conversations

A conversation is the running thread between one of your channels and one recipient phone number. It's created automatically the first time a message flows in either direction. You don't create conversations directly — these endpoints are for reading and managing them.

List conversations

GET /v1/messaging/conversations

Query parameters

Parameter	Type	Description
`channel_id`	uuid	Restrict to one channel.
`status`	string	`open`, `closed`, or `all`. Default: `open`.
`unread_only`	boolean	Only conversations with unread inbound messages. Default: `false`.
`page`	integer	1-indexed. Default: `1`.
`per_page`	integer	Default: `20`, max: `100`.

Example

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  "https://api.tryvox.io/v1/messaging/conversations?unread_only=true&per_page=50"

Response

200 OK:

{
  "data": [
    {
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "channel_id": "8f7a4b2e-91c2-4f3d-9a1e-2c4b6d8f0a1c",
      "contact_phone": "+14155551234",
      "contact_name": "Alex Carter",
      "last_message_at": "2026-04-09T11:14:32Z",
      "last_message_preview": "Yes, please go ahead.",
      "unread_count": 2,
      "status": "open",
      "created_at": "2026-04-09T09:00:00Z"
    }
  ],
  "meta": {"page": 1, "per_page": 50, "total": 1}
}

Get a conversation

GET /v1/messaging/conversations/{id}

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/messaging/conversations/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f

Returns the conversation summary — same shape as a list entry — plus the most recent message if available.

Get messages in a conversation

GET /v1/messaging/conversations/{id}/messages

Query parameters

Parameter	Type	Description
`before`	uuid	Return messages created before this `message_id` (cursor for paging back).
`limit`	integer	Max messages. Default: `50`, max: `200`.

Example

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  "https://api.tryvox.io/v1/messaging/conversations/$CONV_ID/messages?limit=100"

Response

200 OK:

{
  "data": [
    {
      "id": "1b2c3d4e-5f60-7180-9a2b-3c4d5e6f7a8b",
      "conversation_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "direction": "outbound",
      "to": "+14155551234",
      "message_type": "text",
      "content": "Hi, your appointment is confirmed for tomorrow at 10am.",
      "status": "delivered",
      "created_at": "2026-04-09T09:00:12Z",
      "delivered_at": "2026-04-09T09:00:14Z"
    },
    {
      "id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f9a0b1",
      "conversation_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "direction": "inbound",
      "from": "+14155551234",
      "message_type": "text",
      "content": "Thanks! Confirmed.",
      "status": "received",
      "created_at": "2026-04-09T11:14:32Z"
    }
  ],
  "meta": {"has_more": false}
}

Messages are returned newest-first. Page back with ?before={oldest_id}.

Mark as read

Marks every unread inbound message in the conversation as read. Outbound messages are unaffected.

POST /v1/messaging/conversations/{id}/read

curl -X POST \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/messaging/conversations/$CONV_ID/read

204 No Content. The conversation's unread_count resets to zero. If the channel has WhatsApp read receipts enabled, Meta is also notified so the recipient sees the blue ticks.

Errors

Status	Code	Reason
401	`INVALID_CREDENTIALS`	Auth ID / Auth Token bad
404	`CONVERSATION_NOT_FOUND`	No conversation with this `id` on this tenant

Notes

No "create conversation" endpoint. Conversations exist as a side effect of messages. To start a thread, send a template message via Send a Message.
Status is auto-managed. Conversations close after 30 days of inactivity (status: "closed"). A new inbound or outbound message on a closed conversation reopens it.
No archive endpoint. Use status=closed filter to see archived threads.

Conversations

On this page