Skip to main content

​
Conversations

The Conversations API is the first active Woes REST API resource. It writes to the same workspace-scoped conversation and message model used by live chat, email, Discord, the operator inbox, and automations.

​
Conversation Object

{
  "object": "conversation",
  "id": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
  "channel": "api",
  "status": "open",
  "priority": "medium",
  "subject": "Need help with auth",
  "preview": "Need help with auth",
  "customer": {
    "id": "cus_123",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Example API Co",
    "identitySource": "headers"
  },
  "createdAt": "2026-06-28T18:00:00.000Z",
  "updatedAt": "2026-06-28T18:00:00.000Z",
  "lastMessageAt": "2026-06-28T18:00:00.000Z",
  "closedAt": null
}

​
List Conversations

GET /api/v1/conversations
Query parameters:
ParameterTypeDescription
limitnumber1-100 conversations. Default: 20.
statusstringopen, waiting, or solved.
channelstringapi, live-chat, email, or discord.
customerIdstringCustomer id stored on the conversation.
curl "https://woes.dev/api/v1/conversations?status=open&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

{
  "object": "list",
  "hasMore": false,
  "conversations": [
    {
      "object": "conversation",
      "id": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
      "channel": "api",
      "status": "open",
      "priority": "medium",
      "subject": "Need help with auth",
      "preview": "Need help with auth",
      "customer": {
        "id": "cus_123",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "company": "Example API Co",
        "identitySource": "headers"
      },
      "createdAt": "2026-06-28T18:00:00.000Z",
      "updatedAt": "2026-06-28T18:00:00.000Z",
      "lastMessageAt": "2026-06-28T18:00:00.000Z",
      "closedAt": null
    }
  ]
}

​
Create Conversation

POST /api/v1/conversations
Request body:
FieldTypeRequiredDescription
customer.idstringYesStable customer id from your system.
customer.namestringNoCustomer display name.
customer.emailstringNoCustomer email address.
customer.companystringNoCustomer company or account name.
subjectstringYesConversation subject.
externalIdstringNoIdempotency-style external identifier.
channelstringNoDefaults to api.
prioritystringNoDefaults to medium; 1-32 characters.
curl https://woes.dev/api/v1/conversations \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ticket_123",
    "subject": "Need help with auth",
    "customer": {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    }
  }'
Response: 201 Created 
{
  "conversation": {
    "object": "conversation",
    "id": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
    "channel": "api",
    "status": "open",
    "priority": "medium",
    "subject": "Need help with auth",
    "preview": "Need help with auth",
    "customer": {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co",
      "identitySource": "headers"
    },
    "createdAt": "2026-06-28T18:00:00.000Z",
    "updatedAt": "2026-06-28T18:00:00.000Z",
    "lastMessageAt": "2026-06-28T18:00:00.000Z",
    "closedAt": null
  }
}
If externalId already exists in the workspace, the API returns 409.

​
Retrieve Conversation

GET /api/v1/conversations/{conversationId}

curl https://woes.dev/api/v1/conversations/6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33 \
  -H "Authorization: Bearer $WOES_API_KEY"

​
Update Conversation

PATCH /api/v1/conversations/{conversationId}
Supported fields:
FieldTypeDescription
statusstringopen, waiting, or solved.
prioritystring1-32 character priority label.
subjectstringUpdated conversation subject.
curl https://woes.dev/api/v1/conversations/6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33 \
  -X PATCH \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "solved" }'

​
List Messages

GET /api/v1/conversations/{conversationId}/messages

curl https://woes.dev/api/v1/conversations/6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33/messages \
  -H "Authorization: Bearer $WOES_API_KEY"

{
  "object": "list",
  "messages": [
    {
      "object": "message",
      "id": "54c57ed8-e8d7-47f6-8907-27d2174c245a",
      "conversationId": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
      "role": "user",
      "body": "I am getting a 401 from POST /orders.",
      "deliveryStatus": "delivered",
      "createdAt": "2026-06-28T18:01:00.000Z"
    }
  ]
}

​
Create Message

POST /api/v1/conversations/{conversationId}/messages
Request body:
FieldTypeRequiredDescription
bodystringYesMessage body, up to 8,000 characters.
rolestringNouser or assistant. Defaults to user.
curl https://woes.dev/api/v1/conversations/6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33/messages \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "body": "I am getting a 401 from POST /orders."
  }'
Response: 201 Created 
{
  "message": {
    "object": "message",
    "id": "54c57ed8-e8d7-47f6-8907-27d2174c245a",
    "conversationId": "6f6b6f9a-1b6a-4e42-9f71-1b9a3f3d2a33",
    "role": "user",
    "body": "I am getting a 401 from POST /orders.",
    "deliveryStatus": "delivered",
    "createdAt": "2026-06-28T18:01:00.000Z"
  }
}

​
Tenant Boundary

Every Conversations API call is scoped to the workspace attached to the API key. If a conversation id belongs to another workspace, Woes returns 404 instead of revealing that the record exists.