Skip to main content
Each agent has at most one web widget. Asking for a widget again returns the existing one. A widget is made even when your plan doesn’t include web widgets. It then refuses visitors until the plan does, and the reply says so (takes_visitors: false).

​
create_web_widget

Add a voice and chat widget to an agent and return the code to paste into the site.
  • With agent_id, it uses that agent.
  • Without agent_id, it uses the organization’s only agent. If there are several, it lists them so you can pick. If there are none, use create_website_chatbot, which builds the agent and its widget together.
Scope: agents.write

​
Inputs

​
string
The agent_id from list_agents.
​
string
The widget’s title, up to 100 characters. Defaults to the business name, or the agent’s name.
​
string
Your own id for this request, up to 64 characters. Repeat it on retries.

​
Returns

​
boolean
false when no agent was picked yet; see agents.
​
object
​
boolean
true if this request made the widget, false if it already existed.
​
string
The HTML to paste into the page, just before </body>.
​
boolean
false: the widget refuses visitors until your plan includes web widgets.
​
object[]
Only when no agent was named and there are several: the agents to pick from (id, name).

​
Adding the code to a site

Paste embed_code into every page that should show the widget, just before the closing </body> tag. On website builders such as WordPress, Webflow or Wix, use the site-wide “custom code” or “footer code” setting.

​
get_widget_embed_code

Get the code for an agent’s existing widget again. If the agent has no widget yet, it says so and the AI app can offer create_web_widget. Scope: agents.read · Hints: read-only

​
Inputs

​
string
required
The agent_id from list_agents.

​
Returns

The same fields as create_web_widget, with created: false. If the agent has no widget, has_widget is false and there is no embed_code.