Skip to main content
POST
/
v1
/
widget
/
custom_components
Create Custom Component
curl --request POST \
  --url https://api.bland.ai/v1/widget/custom_components \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "widget_id": "<string>",
  "pathway_id": "<string>",
  "pathway_node": "<string>",
  "width": "<string>",
  "height": "<string>",
  "variables": [
    "<string>"
  ],
  "iframe_url": "<string>"
}'
{
  "data": [
    {
      "created_at": "2025-10-02T21:45:27.633Z",
      "updated_at": "2025-10-02T21:45:27.633Z",
      "id": "70b56282-8db5-4e26-aad9-098c099fb1db",
      "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb",
      "widget_id": "7d1a8c0d-5346-4f96-9f5c-d888e273eaf0",
      "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad",
      "pathway_node": "1",
      "width": "100%",
      "height": "300px",
      "variables": [
        "firstName"
      ],
      "iframe_url": "https://widget-custom-components.vercel.app"
    }
  ],
  "errors": null
}

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body

​
widget_id
string
required
Widget identifier UUID to associate with the custom component.
​
pathway_id
string
required
Pathway UUID to associate with the custom component.
​
pathway_node
string
required
Pathway node ID to display the custom component on.
​
width
string
required
Widget width dimension (e.g., “100%”, “500px”).
​
height
string
required
Widget height dimension (e.g., “300px”, “100%”).
​
variables
string[]
required
Array of available agent variable names to pass into the custom component iframe URL as query params.
​
iframe_url
string
required
URL for the iframe source.

​
Response

​
status
number
HTTP status code (200 for success).
​
data
object
  • id (string): Custom component UUID
  • org_id (string): Organization UUID
  • widget_id (string): Widget identifier UUID
  • pathway_id (string): Associated pathway UUID
  • pathway_node (string): Pathway node ID to display the custom component on
  • width (string): Widget width dimension
  • height (string): Widget height dimension
  • variables (string[]): Array of variable names to pass into the custom component iframe URL as query params
  • iframe_url (string): URL for the iframe source
  • created_at (string): ISO timestamp
  • updated_at (string): ISO timestamp
​
errors
null
Always null on successful response.
{
  "data": [
    {
      "created_at": "2025-10-02T21:45:27.633Z",
      "updated_at": "2025-10-02T21:45:27.633Z",
      "id": "70b56282-8db5-4e26-aad9-098c099fb1db",
      "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb",
      "widget_id": "7d1a8c0d-5346-4f96-9f5c-d888e273eaf0",
      "pathway_id": "05f4b269-e79a-4825-b4cd-7778f782bfad",
      "pathway_node": "1",
      "width": "100%",
      "height": "300px",
      "variables": [
        "firstName"
      ],
      "iframe_url": "https://widget-custom-components.vercel.app"
    }
  ],
  "errors": null
}