RelayDocs

API reference

Widget API

These are the endpoints the support widget calls. They’re documented so you understand what the widget does. Every request carries the visitor id in x-visitor-id and your workspace key as ?key=, and a visitor can only ever see their own conversations.

Same origin only

The widget API has no CORS headers: it’s called from the widget’s iframe on your Relay host. It may change between versions. To customize the chat experience, use the widget’s settings and JavaScript API.

Configuration and content#

Widget configuration#

GET/api/widget/config

Returns brandName, accentColor, greeting, botEnabled, aiEnabled, agentName, logoUrl, attachmentsEnabled, maxFileMb and helpBase (the path of your help center). No visitor id needed. A workspace whose subscription has lapsed answers 402, which makes the widget hide itself.

Search articles#

GET/api/widget/articles?q=

Up to 5 published articles matching q (or the first 5 when empty), each with slug, title, excerpt and category.

Identity#

Who am I#

GET/api/widget/identify

Returns { customer: { name, email } | null } for this visitor.

Identify the visitor#

POST/api/widget/identify
namestringoptional
Display name.
emailstringoptional
Email address.
externalIdstringoptional
Your user id (the widget sends RelaySettings.userId here).
metaobjectoptional
String key/values, merged into what’s stored.

Conversations#

List my conversations#

GET/api/widget/conversations

This visitor’s conversations, newest activity first, with a preview and an unread flag.

Start a conversation#

POST/api/widget/conversations
bodystringrequired
The first message; up to 5000 characters.

Returns { conversation, messages }. With the bot on, the bot’s answer is already included, or the conversation has been handed off.

Read a conversation#

GET/api/widget/conversations/:id

Returns the conversation and its messages (never internal notes) and marks your replies as read.

Send a message#

POST/api/widget/conversations/:id/messages
bodystringrequired
Up to 5000 characters.

If the bot is handling the conversation, it answers again. A message reopens a pending or resolved conversation.

Talk to a human#

POST/api/widget/conversations/:id/escalate
namestringoptional
Saved on the customer if given.
emailstringoptional
Validated; saved on the customer if given.

Moves the conversation to Open.

That helped#

POST/api/widget/conversations/:id/resolve

Marks the conversation resolved by the bot.

Live events#

Event stream#

GET/api/widget/stream?vid=<visitorId>&key=<key>

Server-Sent Events. Sends ready, then a conversation event with { conversationId } whenever one of this visitor’s conversations changes. The widget refetches when it gets one.