Get a contact form widget by ID

GET

/api/widgets/contact/{widgetId}

• Production

Retrieves the full configuration of a contact form widget.

Authorizations

• bearerAuth

Parameters

Path Parameters

widgetId

required

string format: uuid

The unique identifier of the widget to retrieve.

Responses

200

The widget was found and returned.

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

No widget exists with the given ID in the authenticated tenant.

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"
]