Skip to main content

Workspace.Chats.Crud

Tags: chat, communication, messaging

Endpoints​

Create​

POST /api/v2/w/{workspace_uuid}/chats

Description:

Chat CRUD operations

Create a new chat conversation in the workspace.

Self-access: Any authenticated member can create a chat (becomes the owner).

Creates either a simple chat or, when workflowId is provided, a workflow assignment chat. The assignment is created automatically; callers do not create or pass an assignment first. For phone-voice assignment chats with the assistant enabled, chat creation also places the outbound call.

Request Body:

  • channel: Communication channel (web-chat, phone-sms, phone-voice, email)
  • workflowId: Workflow to run; creates the assignment automatically when provided
  • workflowVersionNumber: Published workflow version to pin this assignment to
  • memberId: Member this chat is for; defaults to the authenticated member
  • phoneNumberId: Workspace phone number for SMS/voice; workflow default is used when available
  • inboxId: Workspace inbox for email chats; mutually exclusive with phoneNumberId
  • participants: Additional member participants such as an assistant/operator member
  • assistantEnabled: Whether the AI assistant runs the chat (default: true)
  • assistantMemberId: Specific assistant member to use instead of the workflow agent
  • assistantChatModelId / assistantRealtimeModelId: Per-chat assistant model overrides
  • initialMessage: Initial operator message for agent-disabled SMS/email chats
  • title, siteId, isTest, chatType: Optional metadata and chat classification

Response: Returns a ChatResponse object with the newly created chat, including all participants, message counts, and metadata. When an operator-typed initialMessage could not be sent (SMS/email dispatch failed, recipient opted out, missing phone/inbox), the chat is still created and returned with initialMessageError set to a PHI-free reason code — a partial success, not an error. Callers should surface a "reload and retry" warning when that field is present.

Permissions: Requires authenticated member session. Chat ownership is automatically assigned to the creator.

Error Responses:

  • 400 Bad Request: Invalid request parameters or missing required fields
  • 401 Unauthorized: Missing or invalid authentication
  • 404 Not Found: Referenced workflow, member, or assistant member not found
  • 500 Internal Server Error: Database or processing error

Related Endpoints:

  • GET /chats - List all chats
  • GET /chats/{chat_id} - Get chat details
  • PUT /chats/{chat_id} - Update chat properties

Authentication: Requires workspace member

Parameters:

  • chat (CreateChatRequest)

Response: See ChatResponse

Dm​

POST /api/v2/w/{workspace_uuid}/chats/dm

Description:

Chat CRUD operations

Find or create a DM chat with a specific member.

Returns the existing DM chat between the current member and the target member, or creates a new one if none exists.

Self-access: a member may always start their own DM with an agent — it is their own conversation, so no scope is required (matching record self-access, where creating your own record needs no records:write). Initiating a DM with another human member is cross-member contact and requires dm:write.

Authentication: Requires workspace member

Parameters:

Response: See ChatResponse