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.
- GET
/v1/agents/{agent_id}/widgetWidget settings - PATCH
/v1/agents/{agent_id}/widgetChange the widget - GET
/v1/agents/{agent_id}/embedEmbed code
Widget settings
GET/v1/agents/{agent_id}/widget
Colours, greeting, position, question chips and the other widget fields, with their version.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
data | object | The widget fields (welcome_message, theme_color, header_text, ...). |
resource_id | string | The agent's id. |
version | integer | Version 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"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
Send only the fields to change (same names as GET returns in data).
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Idempotency-Key | stringheader | Any 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
| Field | Type | Description |
|---|---|---|
expected_version | integer or null | The 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_message | array of strings | Greeting messages, at most 20. |
predefined_questions | array of strings | Question chips shown under the greeting, at most 30. |
theme_color | string | Main colour as hex, e.g. #5616ea. |
button_hover_color | string | Colour of buttons on hover, hex. |
header_font_color | string | Text colour of the header, hex. |
header_text | string | Title in the header. |
input_placeholder | string | Placeholder of the message field. |
font_family | string | CSS font family, e.g. Inter, sans-serif. |
chat_window_width | integer | Width of the chat window in pixels, 250 to 1200. |
chat_window_height | integer | Height of the chat window in pixels, 300 to 1600. |
widget_horizontal_alignment | string | left or right. |
widget_vertical_alignment | string | bottom, or elevated to lift the launcher off the page edge. |
widget_border_radius | integer | Corner radius of the launcher, 0 to 100. |
widget_size | integer | Size of the launcher in pixels, 20 to 200. |
widget_icon_path | string | Address of the launcher icon. |
header_icon_path | string | Address of the header icon. |
avatar_icon_path | string | Address of the agent's avatar. |
pulsing | boolean | true: the launcher pulses. |
pop_up_messages | boolean | true: the greeting pops up next to the closed launcher. |
pop_up_delay_seconds | integer | Seconds before the greeting pops up, 0 to 3600. |
promoting_text | string | Short promotional line in the widget. |
hide_promoting | boolean | true hides the promotional line. |
remove_powered_by | boolean | true removes the Ultimo branding. Needs a plan that includes it, otherwise 403 plan_restricted. |
custom_branding_text | string | Your own text in place of the branding. |
open_links_in_new_tab | boolean | true opens links in answers in a new tab. |
loading_indicator | string | timeline or dots while the agent writes. |
voice_input | boolean | true shows the microphone button. Needs the Boost plan or higher, otherwise 403 plan_restricted. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. |
resource | object | The widget settings after the change. |
resource.agent_id | string | The agent's id. |
resource.data | object | The widget fields (welcome_message, theme_color, header_text, ...). |
resource.resource_id | string | The agent's id. |
resource.version | integer | Version 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"
}'import os, uuid, requests
r = requests.patch(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"expected_version": 4,
"header_text": "Ask our team",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/widget", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"expected_version": 4,
"header_text": "Ask our team"
})
});
console.log(res.status, await res.json());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
The website code and chat link, as in the portal under Deploy.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
chat_url | string | The agent's hosted chat page, to link to. |
iframe_html | string | The hosted chat as an iframe. |
website_html | string | The 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"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/embed",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/embed", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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.