VEverdun
Conversations

Open Conversation

Find-or-create the thread for a named contact.

200, NOT 201: it is idempotent find-or-create, so a 201 would be a lie on the common path. Tenancy comes from the RESOLVED CONTACT'S SITE, never from the request body, and an out-of-scope contact answers 404 rather than 403.

post/conversations

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/conversations
  • Auth
    HTTP bearer

Request body

site_contact_idstring required

The site contact to open a thread with. Its site must be in your scope.

number'primary' | 'afterhours'

Which of the contact's two numbers on file identifies the thread. Mirrors NotifyOwnerRequest.number; the server only ever texts numbers from the contact row.

Example request

{
  "site_contact_id": "2dd7154e-21dc-408f-ac25-b2918d591e29",
  "number": "primary"
}

Response

Successful Response

idstring required

The thread id.

verdun_numberstring required

Our line, E.164.

customer_numberstring required

The customer's number, E.164.

contact_namestring nullable

Snapshot of the contact at resolution time. Null when the number could not be pinned to one person.

site_contact_idstring nullable

The resolved contact, if exactly one matched. Null makes the thread read-only (consent cannot be checked without it).

parent_idstring nullable

Client. Null only for a thread orphaned by a hard client delete.

parent_namestring nullable

Client name, for the list row.

site_idstring nullable

Site. Null means a PARENT-LEVEL thread — the number belongs to contacts at several sites of one client — not a missing field. It is visible only to a scope holding the whole client.

site_namestring nullable

Site name, for the list row.

account_idstring nullable

The SITE'S account, resolved at read time. Null for a client-wide thread and for a site directly under the client.

account_namestring nullable

Account name, for the list row.

status'open' | 'archived' required

An inbound or an outbound reopens an archived thread.

unread_countinteger required

Conversation-level and SHARED across operators in v1, not per viewer.

last_message_atstring date-time required

Last activity. The list's sort key, never null.

last_inbound_atstring date-time nullable

Last message from the customer.

last_outbound_atstring date-time nullable

Last message from us.

last_message_previewstring nullable

First 160 characters of the newest body. Staff-only; it never reaches an activity-log entry.

last_message_statusstring nullable

Delivery state of the LAST message, provider vocabulary (queued / sent / delivered / failed / undelivered; received on an inbound). Null with no messages. For the list row's badge.

last_message_operator_idstring nullable

Who sent the last message. Null on an inbound.

last_message_operator_namestring nullable

Their name, snapshotted when the message was sent. Null on an inbound.

last_message_direction'outbound' | 'inbound' nullable

Direction of the previewed message.

claimed_by_operator_idstring nullable

Who is answering this thread.

claimed_by_namestring nullable

Their name, for the list row.

claimed_atstring date-time nullable

When they claimed it.

created_atstring date-time nullable

When the thread was opened.

updated_atstring date-time nullable

Last write to the thread row.

Example response

{
  "verdun_number": "+18555550119",
  "customer_number": "+16195550142",
  "contact_name": "Jamie Rivera (Owner)",
  "last_message_status": "delivered"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.