POST
/
api
/
v1
/
widget-settings
curl -X POST https://api.ravan.ai/api/v1/widget-settings/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "Ava Support",
    "bot_auto_start": false,
    "bot_position": "BOT_POSITION_BOTTOM_RIGHT",
    "language": "en"
  }'

{
  "success": true,
  "message": "Widget settings created successfully",
  "data": {
    "id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "botName": "Ava Support",
    "botAutoStart": false,
    "botPosition": "bottom-right",
    "customFormFields": null,
    "theme": null,
    "language": "en",
    "isActive": true,
    "createdAt": "2026-03-20T10:30:00Z",
    "updatedAt": "2026-03-20T10:30:00Z"
  }
}

​
Authorizations

​
X-Api-Key
string
required
Your Agni API key. Find it in your support@ravan.ai under Settings → API Keys.

​
Body

​
bot_name
string
Display name of the bot shown in the widget header (e.g. "Ava Support").
​
bot_auto_start
boolean
If true, the widget automatically starts a voice conversation when the page loads. Defaults to false.
​
bot_position
string
Where the widget appears on the page. Allowed values:
  • BOT_POSITION_BOTTOM_RIGHT (default)
  • BOT_POSITION_BOTTOM_LEFT
  • BOT_POSITION_TOP_RIGHT
  • BOT_POSITION_TOP_LEFT
  • BOT_POSITION_UNSPECIFIED
URL of the bot avatar image displayed inside the widget.
Inline SVG markup for the floating widget button icon.
​
custom_form_fields
object
Custom form fields displayed to the user before starting a conversation (e.g. name, email, phone number).
​
theme
object
Widget color theme and styling. Pass a theme configuration object to customize colors, fonts, and appearance.
​
language
string
Language code for widget UI text (e.g. en, es, fr, de).
​
consent_content
string
Body text of the consent/privacy modal shown to users before call recording begins.
​
consent_title
string
Title of the consent/privacy modal.

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Human-readable status message.
​
data
object
The newly created widget settings object.
curl -X POST https://api.ravan.ai/api/v1/widget-settings/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "Ava Support",
    "bot_auto_start": false,
    "bot_position": "BOT_POSITION_BOTTOM_RIGHT",
    "language": "en"
  }'

{
  "success": true,
  "message": "Widget settings created successfully",
  "data": {
    "id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "botName": "Ava Support",
    "botAutoStart": false,
    "botPosition": "bottom-right",
    "customFormFields": null,
    "theme": null,
    "language": "en",
    "isActive": true,
    "createdAt": "2026-03-20T10:30:00Z",
    "updatedAt": "2026-03-20T10:30:00Z"
  }
}

Authorizations

​
X-Api-Key
string
header
required

Body

application/json
​
bot_name
string
​
bot_auto_start
boolean
​
bot_position
enum<string>

Position of the bot widget on screen

Available options:
BOT_POSITION_UNSPECIFIED,
BOT_POSITION_BOTTOM_RIGHT,
BOT_POSITION_BOTTOM_LEFT,
BOT_POSITION_TOP_RIGHT,
BOT_POSITION_TOP_LEFT
​
custom_form_fields
object
​
theme
object
​
language
string
​
consent_content
string
​
consent_title
string

Response

Successful response

​
success
boolean
​
message
string
​
data
object