Widget

The settings of the website widget, the same ones as under Deploy › Design in the portal, and the code to put the widget on a website.

2 min read Updated

Widget settings

GET/v1/agents/{agent_id}/widget

Permission widget:read

Colours, greeting, position, question chips and the other widget fields, with their version.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
dataobjectThe widget fields (welcome_message, theme_color, header_text, ...).
resource_idstringThe agent's id.
versionintegerVersion of the settings. Send it as expected_version with your next change.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "data": {
    "header_text": "Chat with us",
    "input_placeholder": "Type your message...",
    "pop_up_messages": true,
    "theme_color": "#5616eaff",
    "welcome_message": [
      "Hello! How can I help you?"
    ],
    "widget_horizontal_alignment": "right"
  },
  "resource_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "version": 4
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Change the widget

PATCH/v1/agents/{agent_id}/widget

Permission widget:writeNeeds an integration with read and change access

Send only the fields to change (same names as GET returns in data).

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
Idempotency-KeystringheaderAny unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries.

Request body

FieldTypeDescription
expected_versioninteger or nullThe version from your last read. If the resource changed since, the call answers 409 version_conflict. Leave it out to change the current version. At least 1.
welcome_messagearray of stringsGreeting messages, at most 20.
predefined_questionsarray of stringsQuestion chips shown under the greeting, at most 30.
theme_colorstringMain colour as hex, e.g. #5616ea.
button_hover_colorstringColour of buttons on hover, hex.
header_font_colorstringText colour of the header, hex.
header_textstringTitle in the header.
input_placeholderstringPlaceholder of the message field.
font_familystringCSS font family, e.g. Inter, sans-serif.
chat_window_widthintegerWidth of the chat window in pixels, 250 to 1200.
chat_window_heightintegerHeight of the chat window in pixels, 300 to 1600.
widget_horizontal_alignmentstringleft or right.
widget_vertical_alignmentstringbottom, or elevated to lift the launcher off the page edge.
widget_border_radiusintegerCorner radius of the launcher, 0 to 100.
widget_sizeintegerSize of the launcher in pixels, 20 to 200.
widget_icon_pathstringAddress of the launcher icon.
header_icon_pathstringAddress of the header icon.
avatar_icon_pathstringAddress of the agent's avatar.
pulsingbooleantrue: the launcher pulses.
pop_up_messagesbooleantrue: the greeting pops up next to the closed launcher.
pop_up_delay_secondsintegerSeconds before the greeting pops up, 0 to 3600.
promoting_textstringShort promotional line in the widget.
hide_promotingbooleantrue hides the promotional line.
remove_powered_bybooleantrue removes the Ultimo branding. Needs a plan that includes it, otherwise 403 plan_restricted.
custom_branding_textstringYour own text in place of the branding.
open_links_in_new_tabbooleantrue opens links in answers in a new tab.
loading_indicatorstringtimeline or dots while the agent writes.
voice_inputbooleantrue shows the microphone button. Needs the Boost plan or higher, otherwise 403 plan_restricted.

Response 200 OK

FieldTypeDescription
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned.
resourceobjectThe widget settings after the change.
resource.agent_idstringThe agent's id.
resource.dataobjectThe widget fields (welcome_message, theme_color, header_text, ...).
resource.resource_idstringThe agent's id.
resource.versionintegerVersion of the settings. Send it as expected_version with your next change.

Example request

curl -X PATCH "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget" \
  -H "Authorization: Bearer $ULTIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_version": 4,
  "header_text": "Ask our team"
}'

Response 200 OK

{
  "replayed": false,
  "resource": {
    "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
    "data": {
      "header_text": "Chat with us",
      "input_placeholder": "Type your message...",
      "pop_up_messages": true,
      "theme_color": "#5616eaff",
      "welcome_message": [
        "Hello! How can I help you?"
      ],
      "widget_horizontal_alignment": "right"
    },
    "resource_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
    "version": 5
  }
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Embed code

GET/v1/agents/{agent_id}/embed

Permission widget:read

The website code and chat link, as in the portal under Deploy.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
chat_urlstringThe agent's hosted chat page, to link to.
iframe_htmlstringThe hosted chat as an iframe.
website_htmlstringThe widget code for a website, as in the portal under Deploy › Embed code.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/embed" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "chat_url": "https://chat.ultimo-bots.com/c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "iframe_html": "<iframe src=\"https://chat.ultimo-bots.com/c3e02486-f107-40c4-ac4d-e6155111bc8e\" style=\"width:400px;height:600px;border:0\"></iframe>",
  "website_html": "<div id=\"chat-widget-container\" data-user-id=\"c3e02486-f107-40c4-ac4d-e6155111bc8e\"></div>\n<script src=\"...\"></script>"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Next steps