Free setup on annual plans

Sign up today!
Book a Demo

Channels

Home

> API Reference >

Endpoints >

Channels

API Reference: Channels endpoints

The Channels API manages the communication streams that connect AnswerPal to email, chat, phone and WhatsApp flows. The current implementation covers channel definitions, routing, topic policy, email imports, connection testing, mailbox folders and channel-specific UI translations.

Overview

Channels are customer-owned communication entry points. Most endpoints require a JWT Bearer token and return data scoped to the authenticated customer. Channel setup also affects background email subscriptions, routing rules, topic applicability and localized chat UI text.

Current endpoints

Core channel endpoints

  • GET /api/Channels – Bearer JWT, customer representative roles
    List all channels for the authenticated customer.
  • POST /api/Channels – ManageSettings
    Create a channel. If autoRetrieveEmails is enabled, the API also updates folder auto-retrieve state and ensures email subscriptions.
  • GET /api/Channels/{id} – Bearer JWT, customer representative roles
    Read one channel owned by the authenticated customer.
  • PUT /api/Channels/{id} – ManageSettings
    Update one channel. Changing autoRetrieveEmails also updates folders and subscriptions.
  • DELETE /api/Channels/{id} – ManageSettings
    Delete one channel owned by the authenticated customer.
  • GET /api/Channels/{channelToken}/translations-by-token/{lang} – Public callback/token endpoint
    Return channel translations by public channel token and language, with fallback handling.

Routing and topic policy

  • GET /api/Channels/{id}/routing – Bearer JWT, customer representative roles
    Return channel routing definition, topics and routing rules.
  • GET /api/Channels/{id}/topic-policy – ManageSettings
    Return the current topic policy for a channel.
  • PUT /api/Channels/{id}/topic-policy – ManageSettings
    Update topic policy with mode, includeTopicIds and excludeTopicIds. Supported modes are AllApplicableExcept and NoneExcept.

Email import and connection tests

  • POST /api/Channels/import-emails – ImportEmails
    Queue email import for all channels of the authenticated customer. Optional query: maxCount.
  • POST /api/Channels/{channelId}/import-emails – ImportEmails
    Queue email import for one channel. Optional query: maxCount.
  • POST /api/Channels/test-connection – ManageSettings
    Test IMAP and SMTP settings. Body uses ChannelTestConnectionDTO; channelID is optional.

Conflict note: when a Microsoft Graph client secret has expired, import requests return 409 Conflict with code GraphClientSecretExpired.

Channel folder endpoints

  • GET /api/ChannelFolders/byChannel/{channelId}
    List folders for a channel owned by the authenticated customer.
  • GET /api/ChannelFolders/fromMailbox/{channelId}
    Read folders from the actual mailbox provider for a channel.
  • POST /api/ChannelFolders
    Create a linked folder.
  • GET /api/ChannelFolders/{id}
    Read one linked folder.
  • PUT /api/ChannelFolders/{id}
    Update one linked folder.
  • DELETE /api/ChannelFolders/{id}
    Delete one linked folder.

Conflict note: duplicate folder links return 409 Conflict with code DuplicateChannelFolder.

Channel translation endpoints

  • GET /api/ChannelTranslations/byChannel/{channelId}
    List translations for a channel.
  • POST /api/ChannelTranslations
    Create a translation for a channel and language.
  • GET /api/ChannelTranslations/{id}
    Read one translation.
  • PUT /api/ChannelTranslations/{id}
    Update text fields. channelID and lang stay fixed after creation.
  • DELETE /api/ChannelTranslations/{id}
    Delete one translation.

Access and authentication

Protected endpoints use Authorization: Bearer <token>. The API scopes reads and writes to the authenticated customer. Some operations require policies or roles:

  • ManageSettings: create, update, delete, topic policy and connection testing.
  • ImportEmails: queue email import jobs.
  • Customer representative roles: channel list, read and routing views.
  • Public token endpoint: /api/Channels/{channelToken}/translations-by-token/{lang}.

Channel fields

Core channel fields

  • channelType
    Required string, max 20. Channel type such as Email, Chat, Phone or WhatsApp.
  • name
    Required string, max 100. Display name for the channel.
  • connectionDetails
    Optional connection/configuration details.
  • isActive
    Whether the channel is active.
  • autoRetrieveEmails
    Controls automatic email retrieval and subscription setup for email channels.
  • hostnames
    Allowed hostnames for chat/widget usage.
  • isDefaultTranslationChannel
    Marks the default channel for translation fallback.
  • phoneNumber
    Phone number associated with phone flows.

Email provider and override fields

  • emailAddress, emailProviderType
    Identifies the mailbox and provider type.
  • overrideEmailSettings, overrideGraphTenantID, overrideGraphClientID, overrideGraphClientSecret, overrideGraphAuthorityURL, overrideGraphScope
    Override Microsoft Graph settings for this channel.
  • overrideImapServer, overrideImapPort, overrideImapUsername, overrideImapPassword, overrideImapUseSsl
    Override inbound mailbox settings.
  • overrideSmtpServer, overrideSmtpPort, overrideSmtpUsername, overrideSmtpPassword, overrideSmtpUseSsl
    Override outbound email settings.

Response-only channel fields

  • channelID
    Channel identifier.
  • customerID
    Owning customer, set by the API.
  • token
    Public token used by tokenized endpoints such as translations by token.

ChannelFolder fields

ChannelFolder fields

  • folderName
    Required string, max 255. Display name of the linked folder.
  • externalFolderID
    Required string, max 255. Provider folder identifier.
  • isActive
    Whether the folder link is active.
  • autoRetrieveEmails
    Whether emails are retrieved automatically from this folder.
  • folderDirection
    Direction setting, default Both.
  • channelID
    Required on create and returned on read.
  • folderID
    Returned identifier for the linked folder.

MailboxFolder response fields

  • id, displayName, fullName, depth, isInbox
    Returned by GET /api/ChannelFolders/fromMailbox/{channelId}.

ChannelTranslation fields

ChannelTranslation fields

  • channelID
    Required on create and returned on read.
  • lang
    Required string, max 3. Language code such as en, nl or fr.
  • chatTitle, defaultGreeting, sendButtonText
    Core chat widget labels and greeting.
  • escalatePrompt, availabilityCheck, agentJoin
    Escalation and agent availability messages.
  • yesText, noText, youText
    Short UI labels.
  • validEmail, submitButtonText, succesfulSubmission
    Email capture and form submission labels.
  • channelTranslationID
    Returned identifier for the translation record.

Routing and topic policy response fields

GET /api/Channels/{id}/routing returns ChannelRoutingReadDTO with channel id, name, type, scope mode, a routing definition, topics and URL/rule matches. GET /api/Channels/{id}/topic-policy returns ChannelTopicPolicyReadDTO with mode, included topic ids, excluded topic ids and topic lists.

Connection test response fields

POST /api/Channels/test-connection returns ChannelTestResult with providerType, imap and smtp. Each protocol result includes applicable, success, server, port, useSsl, error and durationMs.

FAQ

Use GET /api/Channels. It returns channels scoped to the authenticated customer and requires one of the customer representative roles.

Use POST /api/Channels/test-connection with ChannelTestConnectionDTO. The response includes provider type and separate IMAP/SMTP protocol test results.

Use POST /api/Channels/import-emails for all channels or POST /api/Channels/{channelId}/import-emails for one channel. Both queue background jobs and accept an optional maxCount query parameter.

Use /api/ChannelTranslations for authenticated management, or GET /api/Channels/{channelToken}/translations-by-token/{lang} for public token-based retrieval.

Need more help?

Contact Support

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons