Channels

Channels represent the communication pathways through which oHallo sends and receives messages. Each channel has a type (email, chat, WhatsApp, or voice), a set of configuration parameters, and a provisioning status that tracks whether the channel is fully operational.

Required scope: channels:read for GET endpoints, channels:write for write endpoints.

Get channel

Retrieve full details for a single channel.

curl "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "channelType": "email",
  "displayName": "Support Email",
  "status": "active",
  "config": {
    "inboundAddress": "support@nordic-parts.dk",
    "fromName": "Nordic Parts Support"
  },
  "createdAt": "2026-01-10T08:00:00.000Z"
}

Response fields:

Field	Type	Description
id	UUID	Channel identifier
workspaceId	UUID	Workspace the channel belongs to
channelType	string	Channel type: email, chat, whatsapp, or voice
displayName	string	Human-readable name
status	string	Provisioning status: active, pending_dns, provisioning, or error
config	object	Channel-specific configuration (non-sensitive settings only)
createdAt	string	ISO 8601 timestamp

Update channel

Update channel settings. Only the fields you include in the request body are changed.

Required scope: channels:write

curl -X PATCH "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Customer Support Email",
    "config": {
      "fromName": "Nordic Parts Customer Support"
    },
    "enabled": true
  }'

Request body:

Field	Type	Required	Description
displayName	string	No	Human-readable name (minimum 1 character)
config	object	No	Channel-specific configuration values
enabled	boolean	No	Whether the channel is active

Response: Returns the full updated channel object.

Delete channel

Permanently delete a channel. Active conversations on this channel will no longer receive or send messages.

Required scope: channels:write

curl -X DELETE "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "ok": true
}

Store channel credentials

Store or replace the credentials used by a channel to authenticate with external services. Credentials are written to a secure vault and never returned in subsequent API responses. The response includes a credentialsRef that the platform uses internally to retrieve the credentials at runtime.

Required scope: channels:write

curl -X POST "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012/credentials" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "whatsapp_api_key_abc123",
    "webhookSecret": "whsec_def456ghi789"
  }'

Request body: A flat object of string key-value pairs. The exact keys depend on the channel type and the external service it integrates with.

Response:

{
  "ok": true,
  "credentialsRef": "channels/a1b2c3d4-e5f6-7890-abcd-ef1234567890/d4e5f6a7-b8c9-0123-4567-890abcdef012"
}

Test channel connectivity

Verify that the channel can send and receive messages. For email channels this sends a test message; for WhatsApp and voice channels this validates the API credentials against the provider.

Required scope: channels:write

curl -X POST "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012/test" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "ok": true
}

If the test fails, the response indicates the failure.

{
  "ok": false
}

Retry provisioning

Retry the provisioning process for a channel that is in error status. This re-runs the provisioning workflow from the beginning, which may involve creating DNS records, configuring webhooks, or registering with external providers.

Required scope: channels:write

curl -X POST "https://api.ohallo.eu/api/channels/d4e5f6a7-b8c9-0123-4567-890abcdef012/retry-provisioning" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "ok": true
}

Channel statuses

Status	Meaning
active	Fully operational — the channel can send and receive messages
pending_dns	Waiting for DNS records to propagate (email channels)
provisioning	The provisioning workflow is in progress
error	Provisioning failed — use the retry endpoint to attempt again