Channels and provider setup

Customers reach you through channels. Every channel is configured in Admin → Settings → Channels & Integrations. The page has a Channel catalog for connecting new accounts and a Connected channels list for managing saved ones.

This chapter covers the common lifecycle, then each channel type. For the website, WordPress and buyer-app surfaces of Web Chat, continue with Customer integrations.

Before you connect a providerLink to this section

  • Public HTTPS. Messaging and voice providers deliver webhooks only to public https:// URLs. PUBLIC_API_ORIGIN must be that origin, because KasaDESK builds the incoming URLs from it. Copy the full URL shown in the channel’s setup. A manually configured provider may use https://support.example.com/api/v1/webhooks/channels/<provider>/<channel-id>. Meta sign-in shares an app callback, and live voice uses separate incoming and TwiML App URLs. Restart the app after changing it.
  • Provider accounts. Use accounts and test numbers you are allowed to use for testing. Provider approval, app review and messaging-tier rules are set by each provider.
  • Credentials stay on the server. Tokens, app secrets and passwords are encrypted with ENCRYPTION_KEY, are never returned to the browser, and are redacted from errors, health details and logs.

The channel lifecycleLink to this section

Use this sequence for messaging and voice providers. Web Chat and email have their own setup below.

  1. Save credentials. In the Channel catalog, choose the provider and enter its credentials. Messaging and voice accounts can be saved and verified before they are routed.
  2. Configure the provider’s webhook where the provider requires it. KasaDESK shows the exact URL, and a verify token where applicable. Some tokens are shown once.
  3. Verify connection. KasaDESK calls the provider’s real API with the saved credentials, and registers webhooks where the provider allows it. Activation requires a passed verification.
  4. Assign a destination. Open the channel from Connected channels → Manage. Under Brands on this channel, choose the workspace and default workgroup, then Assign workspace. The first assignment is the home workspace. Until then the channel shows Needs workspace assignment, and KasaDESK acknowledges provider events without importing them.
  5. Activate channel from the channel’s Test and status panel.
  6. Run live check. A read-only re-check against the provider. It does not change the channel’s health.
  7. Run a round trip. From a real test account, send a message, find it in the right brand and workgroup, reply, and confirm the customer received it.

Keep three results separate when you sign off a channel:

Result What it proves
Verify connection / Run live check The selected provider checks passed. Inbound delivery still needs its own test.
A test message arriving in the inbox Inbound webhook delivery and routing work.
A reply received on the customer’s device Outbound sending works. “Accepted by provider” alone is not proof of delivery.

The integrated review used local verification and provider fixtures. A provider needs a round trip on approved test accounts before you open the channel to customers.

Web ChatLink to this section

A Web Chat channel powers the website widget, the WordPress plugin, hosted Help Center pages in app WebViews, and the optional React Native customer SDK. Each Web Chat channel belongs to one workspace, chosen when you create it.

  1. In Channels & Integrations, create a Web Chat channel. Choose the workspace and default workgroup before saving.
  2. Add every website origin that may embed the chat to its allowed origins, for example https://www.example.com. An origin is scheme, host and any non-default port, with no path. The chat frame refuses to load on any other origin.
  3. Copy the site key (pk_…). It is publishable and safe to put in page HTML or an app bundle.
  4. If you will sign customer identities, copy the identity secret. It is shown once, on creation or rotation. Store it only on your own backend.
  5. If a native app will connect without a browser origin, set Native app access to enabled or verified_only. It is disabled by default.
  6. Optionally set a site-specific primary colour and title. These override the brand’s published chat theme for this channel only.

Embed the loader on an allowlisted test page. Open the chat, send a synthetic message, confirm the correct workspace and workgroup in the inbox, then reply. Verify the customer sees the reply. Repeat from a disallowed test origin and confirm the frame is blocked. See Embed chat on a website.

EmailLink to this section

Each mailbox belongs to one workspace. Choose Email in the Channel catalog, then pick the provider for this mailbox. Choose the workspace and default workgroup before saving.

IMAP and SMTPLink to this section

IMAP/SMTP is the default. Enter the support address, sender display name, IMAP and SMTP server settings and credentials. KasaDESK watches the mailbox with IMAP IDLE where supported and also polls every MAIL_POLL_SECONDS (default 60). Replies are sent as real emails from the same mailbox with standard threading headers, and customer replies thread into the same conversation. Run the connection tests, assign the destination, activate, then send an email from another mailbox and reply to it.

Run background workers in exactly one process while email is connected. Several worker processes would each open their own connections to every mailbox.

ResendLink to this section

  1. Select Resend as the email provider. Enter the support address, sender display name and a Resend API key with full access, then save.
  2. In Resend, configure receiving for the support address and verify its sending domain. Copy the HTTPS webhook URL from the saved mailbox in KasaDESK and register it in Resend for the Email received event.
  3. Run Test inbound and Test outbound. The inbound test checks the matching Resend webhook and obtains its signing secret. The outbound test sends a message, so choose a test address you control.
  4. Review the destination, activate, and verify a live round trip from another mailbox.

Changing the API key pauses the mailbox until both tests pass and an admin reactivates it. After removing a mailbox from KasaDESK, remove its webhook in Resend.

A mailbox with outbound enabled and a passed outbound test can also be chosen in Security → Account emails to send staff password-reset emails.

TelegramLink to this section

  1. In Telegram, use @BotFather to create a bot and copy the bot token.
  2. Choose Connect Telegram, name the channel, paste the token in Bot token, and Save credentials.
  3. Verify connection checks the token and registers the webhook with a secret token. You do not configure anything else at Telegram.
  4. Assign the destination and activate.
  5. Run live check, then message the bot from a Telegram account and reply.

Telegram bots work in private chats only, can message only people who wrote first, and receive no delivery or read receipts, so replies stay “Accepted by provider”.

WhatsApp Business PlatformLink to this section

You need a Meta Business app with WhatsApp, the Phone number ID, the WhatsApp Business Account ID, a permanent System User access token with whatsapp_business_messaging and whatsapp_business_management, and the App secret.

  1. Choose Connect WhatsApp, enter those values and Save credentials.
  2. KasaDESK shows the Webhook URL and a Verify token (shown once). Enter both in the Meta App Dashboard webhook configuration and subscribe to the messages field.
  3. Verify connection, assign the destination and activate.
  4. On the channel page, register each approved message template under Message templates, exactly as approved: name, language code and number of body parameters.
  5. Run live check, then message the number from a test phone and reply.

Free-form replies are allowed within 24 hours of the customer’s last message. After that the composer offers Send template. KasaDESK does not create or submit templates; create them in WhatsApp Manager.

WhatsApp inbound callingLink to this section

  1. Activate the messaging channel first. In WhatsApp Manager, enable Calling for the number with Graph API and WebRTC signaling. Subscribe the Meta app to the calls webhook field alongside messages.

  2. Provide a TURN relay that agent browsers can reach. With an existing relay, supply WHATSAPP_TURN_URLS and WHATSAPP_TURN_SECRET on the KasaDESK server. Keep the shared secret private.

  3. To run the supplied coturn service on the same Linux VPS, point a separate DNS-only hostname such as voice.example.com at its public IPv4 address. Set KASADESK_TURN_HOST, KASADESK_TURN_BIND_IP and KASADESK_TURN_PUBLIC_IP in deploy/.env and create a separate TURN secret with openssl rand -hex 32. Leave WHATSAPP_TURN_URLS empty for the overlay. Allow TCP and UDP 3478 and UDP 49160–49359 through the host and provider firewalls. Use the same port numbers through NAT. If you configure KASADESK_TURN_TLS_DIR with the relay certificate and key, allow TCP 5349 too.

  4. For the coturn overlay, check the configuration and start both services. Use both files for subsequent Compose operations on the relay:

    docker compose --env-file deploy/.env \
      -f deploy/docker-compose.yml -f deploy/docker-compose.turn.yml config --quiet
    docker compose --env-file deploy/.env \
      -f deploy/docker-compose.yml -f deploy/docker-compose.turn.yml up -d --build --wait
  5. Open WhatsApp calling on the active channel. Choose Conversation workgroup or Entire brand workspace in Ring available agents in, then select Check Meta and enable inbound calls.

  6. In the HTTPS inbox, set an eligible agent to Available. Call the test business number, answer, grant microphone permission and check audio both ways. Verify the call appears on the conversation. Repeat from a second network. A healthy TURN container verifies its local listener. The approved test call verifies public reachability and the media path.

If the call rings but audio fails, verify the relay DNS record and UDP rules. If no eligible agent rings, check the calls webhook, active channel, routing scope, presence and whether the agent is already busy. The documented calling flow receives inbound WhatsApp calls; place browser outbound voice calls through Twilio Voice.

Messenger and InstagramLink to this section

Two setup paths are available under Messenger & Instagram:

  • Facebook sign-in (recommended). Enter your Meta app’s App ID and App Secret in Meta app setup, configure the Page and Instagram webhooks with the URLs and verify token shown there, then Continue with Facebook, choose Pages in Choose Facebook Pages, and Connect selected. Use Synchronize now to discover newly granted Pages.
  • Manual setup. Enter the Page ID, Instagram account ID where needed, a Page access token and the App secret, then configure the webhook with the URL and one-time verify token.

Then assign each saved account under Brands on this channel, activate, and test from Messenger and Instagram.

Required permissions include pages_messaging, pages_manage_metadata, and for Instagram instagram_basic and instagram_manage_messages. The Instagram account must be professional, linked to the Page, and allow access to messages. Replies 24 hours to 7 days after the customer’s last message carry Meta’s HUMAN_AGENT tag, which requires Meta’s approval. AI and automated replies are refused after 24 hours, and all replies are refused after 7 days. Until app review, only people with a role on the Meta app can message the Page.

Twilio VoiceLink to this section

Use a Voice-capable Twilio number and its Account SID and Auth Token. For live voice, create a Standard API key in US1 and a dedicated TwiML App on the same account. Enter the API Key SID, API Key Secret and TwiML App SID in KasaDESK.

  1. Choose Connect Voice, keep Enable live inbox calling selected, enter the credentials, the number in E.164 format and a voicemail greeting, and save.
  2. In Twilio, set the number’s incoming-call webhook and the TwiML App’s Voice Request URL to the two URLs KasaDESK shows, both with HTTP POST.
  3. Verify connection, assign the destination, choose Incoming calls go to if the line serves several brands, and activate.
  4. In the inbox, agents open Voice dialer, choose a line, Connect line, set presence to Available, and keep the tab open to receive calls.

Test an inbound call to the configured number and an outbound call from the dialer. Check answer, decline and timeout behavior, two-way audio, and the call record. Calls go to voicemail outside support hours or when nobody answers. For a voicemail-only line, turn off Enable live inbox calling and test the voicemail greeting and inbox delivery. Twilio’s optional transcription is English-only for recordings up to two minutes and may incur provider charges.

TikTokLink to this section

TikTok must approve your developer app for its Business Messaging API, and the TikTok account must be a Verified Business Account or have Advanced Access. The provider excludes accounts registered in the EEA, Switzerland and the UK from this flow. US accounts require TikTok’s US data security review.

  1. Choose Connect TikTok, enter App ID and App secret, and Save credentials.
  2. Add the TikTok account holder redirect URL that KasaDESK shows to your app’s redirect URLs in the TikTok developer portal.
  3. Choose Connect with TikTok and authorize the business account. KasaDESK exchanges the code and registers the webhook.
  4. Assign the destination, activate, and test from a personal account.

If interactive authorization is unavailable, expand Manual method (only if Connect with TikTok is not possible). Use the exact registered account-holder redirect URL and an unused authorization code or an existing refresh token, then choose Verify connection. Authorization codes expire in 10 minutes.

TikTok allows replies within 48 hours and up to 10 replies per customer message. Agents can send text and JPEG or PNG images. Conversations must start with the customer. TikTok sends no delivery receipt, and a read receipt is available only when TikTok reports the customer read event.

Share one provider account across brandsLink to this section

One Telegram bot, WhatsApp number, Facebook Page, Instagram account, TikTok account or Twilio line can serve several workspaces. Web Chat channels and mailboxes always belong to one workspace.

  1. Connect and verify the account.
  2. In Connected channels → Manage → Brands on this channel, assign the first workspace and default workgroup. Use Add workspace for each additional brand.
  3. Optionally give each brand a routing code (2–32 lowercase letters, digits, - or _) and keywords.
  4. Under When a new customer does not use a link or code, choose Ask which brand or pick the workspace that receives new conversations.
  5. Activate channel when every route is ready.

How an incoming message finds its brand:

  1. A link or code: a Telegram start link https://t.me/<bot>?start=<code>, a WhatsApp link that pre-fills #<code>, or #<code> typed anywhere in a message.
  2. The customer’s earlier conversation on this channel.
  3. Ask which brand: KasaDESK sends a numbered list and moves the same conversation to the answered brand. After two unclear answers an agent chooses.
  4. The chosen default workspace.

The AI never answers while a conversation is still choosing its brand. All brands on one bot or number share its name and profile picture.

Channel buttons in the web chatLink to this section

The web chat shows Continue on WhatsApp and Continue on Telegram for the same workspace when that channel is enabled, healthy, assigned to the workspace with an active default workgroup, and either uses the workspace’s routing code or is the home brand. The buttons open the provider’s own app or site; the conversation then continues on that channel as a separate conversation. The links carry only the destination and routing code.

Remove a channelLink to this section

Removing a channel unregisters its webhook where the provider allows it and wipes its secrets. A channel with conversations is archived and its history stays. Removing a brand from a shared channel stops new conversations for that brand only.