Create a contact form widget

POST

/api/workspaces/{workspaceId}/widgets/contact

• Production

Creates a new contact form widget linked to a specific channel. Submissions are routed into oHallo as new conversations on the linked channel.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The workspace to create the widget in.

Request Body

object

name

required

Display name for the widget.

string

>= 1 characters

Example

Website Contact Form

channelId

required

Channel that form submissions are routed to.

string format: uuid

Example

d4e5f6a7-b8c9-4123-8567-890abcdef012

formType

Freeform label for the type of form.

string

Example

general_inquiry

fields

Form field definitions.

Array<object>

object

variant

Visual style: outlined, filled, or minimal.

string

Example

outlined

primaryColor

CSS colour value for the primary accent.

string

Example

#000000

customCss

Additional CSS injected into the widget iframe.

string

theme

Colour theme.

string

Allowed values: light dark auto

successMessage

Message displayed after successful submission.

string

redirectUrl

URL to redirect to after submission.

string

enabled

Whether the widget is active.

boolean

Example

true

Responses

201

The widget was created.

A contact form widget that can be embedded on external websites. Submissions are routed into oHallo as new conversations on the linked channel.

object

id

required

Unique identifier for the widget.

string format: uuid

Example

wgt_aabbccdd-eeff-0011-2233-445566778899

workspaceId

required

The workspace this widget belongs to.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

name

required

Display name for the widget.

string

Example

Website Contact Form

channelId

required

Channel that form submissions are routed to.

string format: uuid

Example

d4e5f6a7-b8c9-0123-4567-890abcdef012

formType

Freeform label for the type of form.

string | null

Example

general_inquiry

fields

Form field definitions.

Array<object>

object

id

required

Unique identifier for the field within the form.

string

type

required

Field type: text, email, phone, textarea, number, select, checkbox, date, time, start-time, end-time, file, captcha, or hidden. A hidden field is never rendered; its value is supplied by the embedding page.

string

label

required

Label displayed above the field.

string

placeholder

Placeholder text inside the field.

string | null

required

required

Whether the field must be filled before submission.

boolean

width

required

Layout width: full or half.

string

options

Available choices for select fields.

Array<string>

crmMapping

Maps the field value to a CRM property.

string | null

variant

Visual style: outlined, filled, or minimal.

string | null

Example

outlined

primaryColor

CSS colour value for the primary accent.

string | null

Example

#000000

customCss

Additional CSS injected into the widget iframe.

string | null

theme

Colour theme for the widget.

string | null

Allowed values: light dark auto

Example

light

successMessage

Message displayed after successful submission.

string | null

Example

Thank you for reaching out. We will get back to you within one business day.

redirectUrl

URL to redirect to after submission instead of showing the success message.

string | null

enabled

required

Whether the widget is currently active.

boolean

Example

true

publicKey

Public key used to authenticate the widget.

string | null

Example

pk_wgt_f1e2d3c4b5a6

createdAt

required

Timestamp when the widget was created.

string format: date-time

Example

2026-02-20T12:00:00.000Z

updatedAt

required

Timestamp when the widget was last updated.

string format: date-time

Example

2026-03-05T09:15:00.000Z

404

The workspace is not one of your account’s (Workspace not found), or the channel is not a channel of that workspace (Channel not found). Nothing is created.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]

422

Validation error.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]