Update Agent Widget
curl --request PATCH \
--url https://api.vocily.ai/v1/agents/{agent_id}/widget \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"allowed_origins": [
"https://acme.example"
]
}
'import requests
url = "https://api.vocily.ai/v1/agents/{agent_id}/widget"
payload = { "allowed_origins": ["https://acme.example"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({allowed_origins: ['https://acme.example']})
};
fetch('https://api.vocily.ai/v1/agents/{agent_id}/widget', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}/widget",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'allowed_origins' => [
'https://acme.example'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vocily.ai/v1/agents/{agent_id}/widget"
payload := strings.NewReader("{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.vocily.ai/v1/agents/{agent_id}/widget")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vocily.ai/v1/agents/{agent_id}/widget")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"name": "Website widget",
"allowed_origins": [
"https://acme.example"
],
"enabled_modes": {
"chat": true,
"talk": true
},
"theme": {
"title": "Acme Support",
"subtitle": "Ask anything or start a web call",
"welcome_message": "Hi! How can I help you today?",
"logo_url": null,
"accent_color": "#7C83FF",
"launcher_text_color": "#FFFFFF",
"user_message_color": "#7C83FF",
"user_message_text_color": "#FFFFFF",
"assistant_message_color": "#17171D",
"assistant_message_text_color": "#E5E7EB",
"position": "bottom-right",
"launcher_label": "Chat",
"button_shape": "rounded",
"panel_radius": 24,
"message_radius": 16,
"launcher_radius": 999,
"icon_radius": 999,
"dock_icon_size": 26,
"launcher_padding_x": 18,
"launcher_padding_y": 13,
"widget_width": 380,
"widget_height": 620,
"show_inbound_number": true
},
"default_variables": {},
"id": "00000011-0000-4000-8000-000000000011",
"agent_id": "00000005-0000-4000-8000-000000000005",
"public_key_prefix": "pk_widget_live_EXA",
"status": "active",
"created_at": "2026-09-16T19:38:04.301686Z",
"updated_at": "2026-09-16T19:38:04.312452Z"
}{
"detail": "Invalid API key",
"code": "UNAUTHORIZED"
}{
"detail": {
"code": "validation_error",
"message": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>",
"type": "<string>"
}
]
},
"code": "VALIDATION_ERROR"
}{
"code": "rate_limited"
}Widget
Configure the widget
Appearance, placement, and which modes it offers.
Update Agent Widget
curl --request PATCH \
--url https://api.vocily.ai/v1/agents/{agent_id}/widget \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"allowed_origins": [
"https://acme.example"
]
}
'import requests
url = "https://api.vocily.ai/v1/agents/{agent_id}/widget"
payload = { "allowed_origins": ["https://acme.example"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({allowed_origins: ['https://acme.example']})
};
fetch('https://api.vocily.ai/v1/agents/{agent_id}/widget', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}/widget",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'allowed_origins' => [
'https://acme.example'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vocily.ai/v1/agents/{agent_id}/widget"
payload := strings.NewReader("{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.vocily.ai/v1/agents/{agent_id}/widget")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vocily.ai/v1/agents/{agent_id}/widget")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allowed_origins\": [\n \"https://acme.example\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"name": "Website widget",
"allowed_origins": [
"https://acme.example"
],
"enabled_modes": {
"chat": true,
"talk": true
},
"theme": {
"title": "Acme Support",
"subtitle": "Ask anything or start a web call",
"welcome_message": "Hi! How can I help you today?",
"logo_url": null,
"accent_color": "#7C83FF",
"launcher_text_color": "#FFFFFF",
"user_message_color": "#7C83FF",
"user_message_text_color": "#FFFFFF",
"assistant_message_color": "#17171D",
"assistant_message_text_color": "#E5E7EB",
"position": "bottom-right",
"launcher_label": "Chat",
"button_shape": "rounded",
"panel_radius": 24,
"message_radius": 16,
"launcher_radius": 999,
"icon_radius": 999,
"dock_icon_size": 26,
"launcher_padding_x": 18,
"launcher_padding_y": 13,
"widget_width": 380,
"widget_height": 620,
"show_inbound_number": true
},
"default_variables": {},
"id": "00000011-0000-4000-8000-000000000011",
"agent_id": "00000005-0000-4000-8000-000000000005",
"public_key_prefix": "pk_widget_live_EXA",
"status": "active",
"created_at": "2026-09-16T19:38:04.301686Z",
"updated_at": "2026-09-16T19:38:04.312452Z"
}{
"detail": "Invalid API key",
"code": "UNAUTHORIZED"
}{
"detail": {
"code": "validation_error",
"message": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>",
"type": "<string>"
}
]
},
"code": "VALIDATION_ERROR"
}{
"code": "rate_limited"
}{ "allowed_origins": ["https://acme.example"],
"enabled_modes": { "chat": true, "talk": true },
"theme": { "title": "Acme Support", "accent_color": "#7C83FF", "position": "bottom-right" } }
enabled_modes decides whether visitors can type, talk, or both. default_variables supplies values
for the agent’s {{variables}} on every conversation the widget starts — a plan name, a page, a
customer id your site already knows.Authorizations
Your API key as a Bearer token, e.g. Authorization: Bearer vk_….
Path Parameters
The agent's id, as GET /v1/agents returns it.
Body
application/json
What to call this widget.
Required string length:
1 - 255The security boundary: which origins may use this widget's public key. Sending the list replaces the whole set.
Whether visitors can type, talk, or both.
Show child attributes
Show child attributes
Appearance and placement.
Show child attributes
Show child attributes
Values supplied for the agent's {{variables}} on every conversation this widget starts.
Show child attributes
Show child attributes
Whether the widget is live or paused.
Was this page helpful?
⌘I