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

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

#0166A3

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, file, or captcha.

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

#0166A3

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

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