Skip to main content
POST
/
v1
/
widget
/
sessions
/
{sessionId}
/
messages
Send widget message
curl --request POST \
  --url https://api.example.com/v1/widget/sessions/{sessionId}/messages \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "attachmentIds": [
    {}
  ]
}
'

​
Overview

Roadmap — not yet available. The embeddable widget is a future feature.
Sends a message from the user to the widget AI assistant. The assistant’s response is delivered via the widget SSE stream — this endpoint accepts the message and returns immediately. Authentication: Widget session token (pass as Authorization: Bearer <sessionToken> or X-Widget-Token header).

​
Request headers

​
Authorization
string
required
Widget session token. Format: Bearer <sessionToken>. Obtain from Create widget session.

​
Path parameters

​
sessionId
string
required
The widget session identifier from Create widget session.

​
Request body

​
message
string
required
The user’s message. Maximum 2,000 characters.
​
attachmentIds
array
Optional list of previously uploaded attachment IDs to include with this message.

​
Response

Returns 202 Accepted. The assistant’s reply streams on GET /v1/widget/sessions/{sessionId}/stream. 
{
  "messageId": "wmsg_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "sessionId": "wsess_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "status": "processing",
  "submittedAt": "2024-04-01T14:30:00Z"
}

​
Error responses

StatusError codeDescription
400validation_errormessage is empty or exceeds length limit
401unauthorizedMissing or invalid session token
404session_not_foundSession does not exist or has expired
429rate_limit_exceededToo many messages in this session

​
Examples

curl https://api.causeflow.ai/v1/widget/sessions/wsess_01HX9VTPQR3KF8MZWBYD5N6JCE/messages \
  -X POST \
  -H "Authorization: Bearer wst_live_EXAMPLE_TOKEN_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What is the root cause of inc_EXAMPLE_01JX?" }'

Widget stream

Receive the AI response via SSE

Close session

End the widget session when done