Widget

The widget endpoints are called by the visitor’s browser. Apart from config and session, they use the visitor token: Authorization: Visitor od_vis_.... The workspace comes from the session.

Method	Path	Description
GET	/v1/widget/config?key=<widget_key>	Public config for the widget
POST	/v1/widget/session	Start or resume a visitor session
GET	/v1/widget/conversations	The visitor’s chat conversations
POST	/v1/widget/conversations	Start a conversation
GET	/v1/widget/conversations/{id}/messages	Public messages only, never notes
POST	/v1/widget/conversations/{id}/messages	Send a message
POST	/v1/widget/attachments	Upload a file (multipart)
POST	/v1/widget/conversations/{id}/handoff	Ask for a person after an AI answer
GET, PATCH	/v1/widget/settings	Admin: widget settings

Config

curl "https://api.opendesk.sh/v1/widget/config?key=<widget_key>"

{ "workspace_name": "Example", "brand_color": "#0A0A0A", "greeting": "Hi, how can we help?", "help_center_url": "https://...", "require_email": false }

Session

curl https://api.opendesk.sh/v1/widget/session \
  -H "Content-Type: application/json" \
  -d '{ "key": "<widget_key>", "user_id": "42", "user_hash": "<hex hmac>", "email": "[email protected]", "name": "Ana" }'

{ "visitor_token": "od_vis_...", "contact": { "id": "...", "email": "[email protected]", "name": "Ana", "avatar_url": "" }, "ws_token": "<jwt>", "gateway_url": "wss://gateway.opendesk.sh/socket/widget" }

Field	Notes
key	the workspace’s public widget key, required
visitor_token	resume an existing session
email, name	what the visitor told you
user_id, user_hash	a verified identity: user_hash is hex HMAC-SHA256 of user_id with the widget secret

ws_token is a 5-minute widget_ws token for the realtime gateway’s widget endpoint. It lets the visitor join only their own contact topic.

Conversations

curl https://api.opendesk.sh/v1/widget/conversations \
  -H "Authorization: Visitor od_vis_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hi, my order has not arrived." }'

Settings (admin)

GET and PATCH /v1/widget/settings with { greeting, require_email, enabled, allowed_origins }, from the agent side. Rotate the widget secret with POST /v1/workspace/widget-secret/rotate.