Create a channel in a workspace

POST

/api/workspaces/{workspaceId}/channels

• Production

Creates a channel in a workspace. Email channels begin provisioning and progress through pending states; chat and voice channels become active immediately. For voice channels, bind a provisioned phone number via phoneNumberId. The created channel record is returned.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The unique identifier of the workspace to create the channel in.

Request Body

object

channelType

required

The type of channel to create.

string

Allowed values: email chat whatsapp voice_phone

Example

email

displayName

required

A human-readable name for the channel. Leading and trailing whitespace is trimmed.

string

>= 1 characters

Example

Support Email

config

Channel-specific configuration. Email and chat channels validate this against their own configuration shape. Defaults to an empty object.

object

key

additional properties

Example

{
  "inboundAddress": "support@acme.example"
}

enabled

Whether the channel is enabled. Defaults to true.

boolean

Example

true

phoneNumberId

The provisioned phone number to bind. Required when the channel type is voice_phone, and not permitted for other types.

string format: uuid

Example

pn1a2b3c-5678-9abc-def0-1234567890ab

Responses

201

The channel was created.

A channel represents a communication pathway through which oHallo sends and receives messages. Each channel has a type, configuration, and provisioning status.

object

id

required

Unique identifier for the channel.

string format: uuid

Example

d4e5f6a7-b8c9-0123-4567-890abcdef012

workspaceId

required

Workspace the channel belongs to.

string format: uuid

Example

a1b2c3d4-e5f6-7890-abcd-ef1234567890

channelType

required

Channel type: email, chat, whatsapp, or voice.

string

Example

email

displayName

required

Human-readable name.

string

Example

Support Email

status

required

Provisioning status: active, pending_dns, provisioning, or error.

string

Example

active

config

Channel-specific configuration (non-sensitive settings only).

object | null

Example

{
  "inboundAddress": "support@nordic-parts.dk",
  "fromName": "Nordic Parts Support"
}

createdAt

required

Timestamp when the channel was created.

string format: date-time

Example

2026-01-10T08:00:00.000Z

409

The requested phone number is already bound to another voice channel.

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

422

Validation error. One or more required fields are missing or invalid.

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