Get channel by ID
GET /api/channels/{channelId}
Retrieve full details for a single channel including its type, configuration, and provisioning status.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the channel to retrieve.
Responses
Section titled “ Responses ”The channel was found and returned.
A channel represents a communication pathway through which oHallo sends and receives messages. Each channel has a type, configuration, and provisioning status.
object
Unique identifier for the channel.
Example
d4e5f6a7-b8c9-0123-4567-890abcdef012Workspace the channel belongs to.
Example
a1b2c3d4-e5f6-7890-abcd-ef1234567890The account the channel belongs to.
Example
a0b1c2d3-4567-89ab-cdef-0123456789abOn a read by id: the brand the channel answers for, which is the brand of its workspace.
Channel type: email, chat, whatsapp or voice_phone. The type decides the shape of config.
Example
emailHuman-readable name.
Example
Support EmailWhere the channel stands. draft: set up but not live; an inbox_api email channel stays in draft until its mailbox is connected in the dashboard. pending_dns: a subdomain, subdomain_with_redirect or mail_routing_rule email channel waits for its DNS records to be published and to resolve; a mail_routing_rule channel waits here until its DKIM records are verified, for up to 72 hours, after which it moves to error. pending_verification: the channel’s DNS records resolve, and oHallo is completing the verification of its domain. pending_setup: a mail_routing_rule or subdomain_with_redirect email channel waits for the first message its mail-flow rule redirects, and turns active when it arrives. pending_inbound: a forwarding email channel waits for the first forwarded message, and turns active when it arrives. pending_activation: a voice channel waits while its phone number is in review with the carrier, and turns active when the number is approved. active: the channel receives and sends messages; a successful connectivity test also sets it, on every channel but a mail_routing_rule one. error: provisioning failed, a connectivity test failed on an active channel, or a connected mailbox needs to be connected again; after a provisioning failure config.error_message says why when the reason is known. The retry endpoint provisions an email channel again, and a connected mailbox is connected again in the dashboard. inactive: a connected mailbox was disconnected, and the channel receives and sends nothing until the mailbox is connected again. deprovisioned: the channel was deleted; channel lists leave it out, and a read by id returns it.
Example
activeWhether the channel is enabled.
Example
trueThe id of the run that provisions an email channel; null on a channel no provisioning run was started for, such as a chat, voice or inbox_api channel.
When a connectivity test, or the disconnection of a mailbox, last set the channel’s status; null before either.
The channel’s configuration, in the shape for its channelType: the email channel config for email, the chat channel config for chat and the voice channel config for voice_phone. It holds settings only; channel credentials are stored apart and never returned.
object
The configuration of an email channel. inbound_mode decides how mail reaches oHallo and which fields the channel needs. A config without inbound_mode is read as subdomain, with inbound_address taken from from_address. While it provisions the channel, oHallo adds keys of its own, marked read-only: the inbound_address it generates, the DNS records to publish, and error_message when provisioning fails. A channel is created in subdomain, forwarding, inbox_api or mail_routing_rule; another inbound_mode on create, or a new mode on update other than subdomain, forwarding or inbox_api, answers 422.
object
A subdomain given to oHallo, for example help.example.com, receives the mail itself. Publish the records in dns_records on it. The channel turns active once the domain is verified. The addresses are on a subdomain of a registrable domain, as the Public Suffix List draws it: an address on a registrable domain itself, such as support@example.com or support@example.co.uk, answers 422 with the message on that address, since an MX record there would receive all of the domain’s mail.
object
subdomain, which is also how a config without inbound_mode is read.
The address customers write to and replies come from: an address on the subdomain.
Example
support@help.example.comThe address mail is received at, the same as from_address. Required when inbound_mode is sent; without inbound_mode it is taken from from_address.
Example
support@help.example.comThe domain the DNS records belong to, written by oHallo.
Example
help.example.comThe DNS records an email channel needs, written by oHallo. Publish each at the DNS host of its domain. The verification record, the DKIM records and the MX record route and verify mail; SPF and DMARC serve the delivery of replies.
object
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
On a mail_routing_rule channel, the domain the DKIM records belong to.
Why provisioning failed, when the channel’s status is error and the reason is known.
A routing subdomain receives mail at oHallo, and a mail-flow rule at the current mail provider redirects the mail for from_address to inbound_address on it. Publish the records in dns_records on the routing subdomain. Customers keep writing to from_address, and the channel turns active when the first redirected message arrives. A channel in this mode is read back with it and keeps it on update; a create in it answers 422.
object
The address customers write to and replies come from.
The subdomain that receives mail at oHallo, for example mail.example.com.
The address on routing_subdomain that the mail-flow rule redirects to: the local part of from_address at routing_subdomain.
Where the mailbox of from_address is hosted.
The domain the DNS records belong to, the routing subdomain, written by oHallo.
The DNS records an email channel needs, written by oHallo. Publish each at the DNS host of its domain. The verification record, the DKIM records and the MX record route and verify mail; SPF and DMARC serve the delivery of replies.
object
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
On a mail_routing_rule channel, the domain the DKIM records belong to.
Why provisioning failed, when the channel’s status is error and the reason is known.
The mailbox stays where it is and forwards its mail to inbound_address, an address oHallo generates when the channel is created. No DNS records are needed. Replies are sent from an oHallo address, with from_address as their reply-to address. The channel turns active when the first forwarded message arrives.
object
The address customers write to.
Where the mailbox of from_address is hosted.
The address to forward the mail to, generated by oHallo.
Why provisioning failed, when the channel’s status is error and the reason is known.
A mail-flow rule in Microsoft 365 or Google Workspace redirects the mail for from_address to inbound_address, an address oHallo generates when the channel is created. DKIM records on the domain of from_address sign the replies; dns_records lists them once provisioning has requested them. The channel turns active when the first redirected message arrives. A channel is created in this mode with from_address and mail_provider (office365 or google); an update into it answers 422.
object
The address customers write to and replies come from.
Where the mailbox of from_address is hosted.
The address the mail-flow rule redirects to, generated by oHallo.
The DNS records an email channel needs, written by oHallo. Publish each at the DNS host of its domain. The verification record, the DKIM records and the MX record route and verify mail; SPF and DMARC serve the delivery of replies.
object
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
One DNS record to publish.
object
The record type.
The record’s name.
The record’s value.
The priority of an MX record.
On a mail_routing_rule channel, the domain the DKIM records belong to.
Why provisioning failed, when the channel’s status is error and the reason is known.
OHallo reads and sends through a Microsoft 365 mailbox. The mailbox is connected in the dashboard: open the channel under Settings, Channels and choose Connect, which signs in to the mailbox’s provider. The channel stays in draft until then, and turns active when the mailbox is connected. A connected mailbox keeps its from_address, inbound_address, mail_provider and inbound_mode.
object
The mailbox to connect. It may be empty when the channel is created and entered in the dashboard before the mailbox is connected.
The mailbox’s address, as from_address. It may be empty when the channel is created.
The provider of the mailbox.
The configuration of a chat channel. Every field is optional: a chat channel with an empty config runs on any website as a floating launcher.
object
The website origins the chat runs on, each a scheme and host such as https://www.example.com. A page’s origin must match one of them exactly, so a domain and its www subdomain are two origins. An empty or absent list lets the chat run on any website.
Example
[ "https://www.example.com"]How the chat appears on the page.
object
floating is a launcher in a corner of the page that opens the chat, sidebar is a full-height panel at the side of the page, and inline is a section inside the page.
The chat’s accent colour as a hex value.
Example
#0A2540The corner the floating launcher sits in. Floating mode only.
Questions shown in the empty chat; choosing one sends it as the visitor’s first message. Inline mode only.
How the team follows up when a chat visitor needs it. A channel that holds handover reads it alone.
object
When a visitor’s question needs the team and an email address for the visitor is known, the assistant passes the chat to the team by email: an email conversation with the visitor opens, or an open one continues, linked to the chat, in the email channel chosen for follow-ups or, when none is chosen, the workspace’s only email channel. The visitor receives an email in it, unless a team member holds that conversation or has paused the assistant on it. When phone is true and the visitor leaves a number for a call, a callback request is recorded instead.
With true, a phone number the visitor leaves for a call from the team becomes a callback request in Callbacks. With false, none is recorded.
In the account’s own words, which questions go to the team. The assistant reads it when it decides which questions to pass to the team.
Stored with a chat channel. While the channel holds no handover, its guidance is the channel’s guidance.
object
Stored with the channel.
In the account’s own words, which questions go to the team. Read as the channel’s guidance while the channel holds no handover.
On a voice channel, what the assistant does when a person cannot take over: when the team is closed or no colleague is on duty. A caller placed in the queue waits for a colleague. On a chat channel that holds no handover, strategy: 'callback' reads as handover.phone: true.
object
resume_ai: the assistant carries on with the customer itself. callback: it records a request for someone to call the customer back. A voice channel applies take_message as callback, and one without a strategy offers a callback.
The configuration of a voice channel (voice_phone). Every field is optional.
object
The line’s language, as a language code: one of the brand’s supportedLanguages, or the workspace’s operatingLanguage. It is stored as the canonical code (no is stored as nb). Without it, or with null, the line takes the workspace’s operating language. A language outside those answers 422 and nothing is saved.
Example
svThe opening line callers hear on this number, in place of the workspace’s greeting. A new or changed line is saved only with welcomeGreetingAttested: true in the same request (EU AI Act Article 50), and its wording must mention the assistant in the line’s language; otherwise the request answers 422 with code greeting_attestation_required or greeting_must_mention_ai. A confirmation covers the line’s language: after the line moves to another language, the line is confirmed again in that language.
How soon the voice starts to speak a reply. sentence, the default, waits for a whole sentence, which sounds most natural; token starts on the first words and answers sooner.
Policies left out of calls on this number. A call draws on every approved policy of the workspace except these.
Knowledge base entries left out of calls on this number. A call draws on every approved entry of the workspace except these.
On a voice channel, what the assistant does when a person cannot take over: when the team is closed or no colleague is on duty. A caller placed in the queue waits for a colleague. On a chat channel that holds no handover, strategy: 'callback' reads as handover.phone: true.
object
resume_ai: the assistant carries on with the customer itself. callback: it records a request for someone to call the customer back. A voice channel applies take_message as callback, and one without a strategy offers a callback.
What a caller waiting for a person hears, such as the hold music, as set on the channel’s page in the dashboard.
Example
{ "inbound_mode": "subdomain", "from_address": "support@help.example.com", "inbound_address": "support@help.example.com", "domain": "help.example.com"}A chat channel’s public key: the data-key of the code that puts the chat on a website. null on the other channel types.
The phone number a voice channel answers; null on the other channel types.
The reference oHallo uses to read the channel’s stored credentials at runtime, never the credentials themselves; null when none are stored.
Has no effect.
The channel’s current configuration version.
Timestamp when the channel was created.
Example
2026-01-10T08:00:00.000ZTimestamp when the channel was last updated.
Example
2026-01-10T08:00:00.000ZEU AI Act Article 50 confirmation covering the exact greeting override in config.welcome_greeting on a voice channel, composed by the server when the override is saved with welcomeGreetingAttested.
object
The language the override was confirmed in. The confirmation covers the override only while the line’s language (config.language, else the workspace’s operating language) is this language.
Example
daWhether the stored confirmation still covers the override in config.welcome_greeting, in the line’s language. False means callers hear the standard opening line on this number until the override is confirmed again.
No channel exists with the given ID in the authenticated tenant.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]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.
Example
11223344-5566-4788-99aa-bbccddeeff00On 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.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]