Channels & Inboxes

Creating an API channel inbox

Creating an API channel inboxThe API channel is Konversio's generic integration layer. If you have a source of customer messages that doesn't fit email, WhatsApp, or another built-in channel — a mobile app, a custom web form, an internal tool, a voice transcription pipeline — the API channel is how you connect it.What the API channel is forThe API channel decouples Konversio from specific platforms. You push messages in via HTTP, and Konversio handles the conversation routing, agent assignment, and response flow. Your system receives agent replies via webhook.Typical use cases:Mobile app in-app chat (iOS/Android)Custom web chat built with your own UI instead of the embeddable widgetKiosk or point-of-sale support interfaceAggregating messages from a platform Konversio doesn't natively supportInternal helpdesk where the "user" is another system rather than a humanCreate an API channel inboxGo to Settings → Inboxes → Add InboxSelect API as the channel typeGive the inbox a name and click Create InboxAssign agents as usualAfter creation, the inbox settings page shows:Your Inbox Identifier (a token used to scope API calls to this inbox)Pushing messages inTo create a conversation and send a message into the inbox, use the Konversio public API. You will need:Your Konversio instance URLThe Inbox Identifier from the inbox settingsA contact identifier (you create or look up contacts via the API as well)A minimal flow:Create or find a contact — POST /api/v1/profile or POST /api/v1/accounts/{account_id}/contactsCreate a conversation — POST /api/v1/accounts/{account_id}/conversations with the inbox ID and contact IDCreate a message in that conversation — POST /api/v1/accounts/{account_id}/conversations/{id}/messagesThe full API reference is available at https://your-konversio-instance.com/swagger or in the Konversio developer documentation.All API calls require an agent authentication token (api_access_token), passed as a header or query parameter.Receiving agent replies via webhookWhen an agent replies to a conversation that came in through an API channel inbox, Konversio fires a webhook. Set up a webhook endpoint under Settings → Integrations → Webhooks and subscribe to the message_created event.Your endpoint will receive a POST with the message payload, including the conversation ID, the message content, and metadata. Your application can then deliver the reply to the end user through whatever channel your app uses.Identifying users across sessionsFor conversations to be continuable (returning user picks up where they left off), pass a consistent identifier for each contact when creating or looking up contacts. This is typically a user ID from your own system. Without a stable identifier, each API call creates a new anonymous contact and a new conversation.Example: mobile app support chatA typical mobile app integration:User taps "Contact support" in the appApp backend calls Konversio to create or retrieve a contact using the user's account ID as the identifierApp creates a conversation in the API channel inbox and posts the user's first messageKonversio routes the conversation to an available agentAgent replies in KonversioWebhook fires to your backend, which pushes the reply to the mobile app via push notification or WebSocketUser sees the reply inside the appThe API channel gives you full control over the user-facing UI while Konversio handles the agent-side tooling.

Setting up email

Setting up emailKonversio handles email as a full two-way channel. Inbound messages arrive as conversations; replies from agents go back as emails. This covers how to connect an email address to a Konversio inbox.Create an Email inboxGo to Settings → Inboxes → Add InboxSelect Email as the channel typeEnter:Channel name — internal label for your teamEmail address — the address you want to receive mail at (e.g. support@yourdomain.com)Display name — the sender name shown on outbound emailsClick Create Inbox and assign agentsAt this stage the inbox exists but cannot yet send or receive mail. You need to configure either inbound forwarding or IMAP, and SMTP for outbound.Inbound email: forwardingThe simplest inbound setup is forwarding. Konversio provides a unique forwarding address for each inbox — something like abc123@inbound.your-konversio-instance.com.Set up a forwarding rule in your existing mail service (Gmail, Fastmail, your domain's MX provider) to forward all mail sent to support@yourdomain.com to that Konversio address. Konversio receives the forwarded message, parses it, and opens a conversation.This approach requires no IMAP credentials and works with almost any mail provider.Inbound email: IMAPIf you prefer Konversio to poll your mailbox directly:Open the inbox settings and go to the Configuration tabEnable IMAP and fill in:IMAP host and port (e.g. imap.yourdomain.com, port 993)Username and password (use an app-specific password if your provider supports it)SSL enabled (recommended)Konversio polls the mailbox at regular intervals. New messages are pulled in and opened as conversations. Messages are marked as read after import.Outbound email: SMTPTo send replies from Konversio back to customers via your own mail server:In the inbox settings, go to the Configuration tabEnable SMTP and fill in:SMTP host and port (e.g. smtp.yourdomain.com, port 587)Username and passwordFrom address (should match the inbox email address to avoid SPF/DKIM failures)TLS/STARTTLS settingIf you do not configure SMTP, Konversio falls back to its own mail relay. For professional use and deliverability, configuring your own SMTP is strongly recommended.Reply-via-email flowWhen a customer replies to an agent's email, the reply lands back in the inbox (via forwarding or IMAP) and is threaded into the original conversation. Konversio matches replies to conversations using a Message-ID / In-Reply-To header chain, so the conversation stays intact even across multiple back-and-forth exchanges.Agents reply directly from the conversation view in Konversio — they do not need to open a mail client.Practical notesUse a dedicated mailbox for each Konversio inbox. Shared mailboxes used by humans and Konversio simultaneously will cause duplicate handling.Set up DKIM and SPF records for your sending domain. Without them, outbound mail is likely to land in spam.If you use Gmail, enable IMAP access in Google Account settings and use an App Password rather than your main password.

Setting up Telegram

Setting up TelegramTelegram is one of the simpler channels to connect. There are no platform approvals, no business verification steps, and no messaging window restrictions. You create a bot, get a token, and paste it into Konversio.Step 1: Create a Telegram botOpen Telegram and search for @BotFather — the official bot for creating and managing botsStart a chat and send the command /newbotBotFather will ask you for:A display name for your bot (e.g. "Acme Support")A username for the bot — must end in bot (e.g. acme_support_bot)BotFather confirms creation and gives you an API token — a string like 7123456789:AAF...Keep this token private. Anyone with the token can control your bot.Optionally, while you are in BotFather, you can:Set a description (/setdescription) — shown to users before they start the botSet a profile photo (/setuserpic)Disable the "what can this bot do?" prompt (/setcommands) if you don't use bot commandsStep 2: Create a Telegram inbox in KonversioGo to Settings → Inboxes → Add InboxSelect Telegram as the channel typeFill in:Channel name — an internal label for your teamBot token — paste the token you received from BotFatherClick Create Inbox and assign agentsKonversio sets up a webhook with Telegram automatically using the token you provided. There is no manual webhook registration step.Step 3: Test the connectionOpen Telegram and search for your bot by its usernameTap Start and send a messageWithin a few seconds, the message should appear as a new conversation in your Konversio inboxReply from the conversation view in Konversio. Your reply will arrive in the user's Telegram chat.Notes and limitationsNo proactive outreach: Telegram bots cannot message users who have not started a conversation with the bot first. Your team can only reply; they cannot initiate.One bot per inbox: Each Telegram inbox uses exactly one bot token. If you want to run separate bots (e.g. for different brands), create separate inboxes with separate bot tokens.Group chats: Konversio's Telegram integration is designed for direct (private) messages between users and the bot. Adding the bot to a group chat is possible but behaviour in that context is not a primary supported use case.No phone number required: Unlike WhatsApp, Telegram requires no phone number on your side. The bot exists independently of any phone number.

Setting up website live chat

Setting up website live chatThe website live chat widget lets visitors start a conversation with your team directly from any web page. Setting it up takes about five minutes.Create a Website inboxGo to Settings → Inboxes → Add InboxSelect Website as the channel typeFill in the basic details:Website name — an internal label, visible only to your teamWebsite URL — the domain where the widget will appear (used for reference, not enforced)Widget colour — pick a colour that matches your site's brandWelcome heading and Welcome tagline — shown to visitors before they start a chatClick Create Inbox, then assign agents or teams on the next screenClick More Settings to configure additional options, or proceed to get your embed codeInstall the widget on your siteAfter creating the inbox, Konversio generates a small JavaScript snippet. It looks like this:<script> (function(d,t) { var BASE_URL="https://your-konversio-instance.com"; var g=d.createElement(t),s=d.getElementsByTagName(t)[0]; g.src=BASE_URL+"/packs/js/sdk.js"; g.defer = true; g.async = true; s.parentNode.insertBefore(g,s); g.onload=function(){ window.chatwootSDK.run({ websiteToken: 'YOUR_INBOX_TOKEN', baseUrl: BASE_URL }) } })(document,"script"); </script> Paste this snippet just before the closing </body> tag on every page where you want the widget to appear.Installing via a tag managerIf you use Google Tag Manager, Adobe Launch, or a similar tool, paste the snippet as a Custom HTML tag and fire it on All Pages (or a specific trigger). No special configuration is needed — the script is self-contained.Pre-chat formYou can require visitors to provide details before starting a conversation. Go to the inbox's Configuration tab and enable the Pre Chat Form. You can request:NameEmail addressPhone numberEach field can be set as optional or required. Collecting an email address before chat starts means you can follow up even if the visitor leaves before your team responds.Customising the widgetUnder Settings → Inboxes → (your inbox) → Configuration:Widget colour — change at any time; updates immediately without changing the embed codeWelcome heading / tagline — the text shown in the widget launcher panelConversation continuity — returning visitors with the same browser see their previous conversationsBusiness hours — optionally show availability and expected response timesTesting the widgetAfter installing the snippet, open the page in a browser and click the chat icon. Send a test message. It should appear immediately in your Konversio inbox under Conversations.If the widget does not appear, check that the script tag is loading (browser console, Network tab) and that your Konversio instance URL in the snippet is correct and reachable from the visitor's browser.

What is an inbox?

What is an inbox?In Konversio, an inbox is the connection point between a communication channel and your workspace. Every conversation your team handles comes in through an inbox.The core conceptThink of an inbox as a named pipeline. You create one inbox per channel connection — for example:One inbox for your website live chat widgetOne inbox for support@yourdomain.comOne inbox for your WhatsApp Business numberOne inbox for your Telegram botEach inbox has its own configuration, its own set of assigned agents, and its own conversation queue. Conversations from different channels stay separate unless you deliberately route them together via teams or automation.What an inbox is notAn inbox is not the same as an email folder or a generic "inbox" in the everyday sense. It is specifically a configured integration. You cannot receive messages through an inbox that hasn't been set up with valid credentials or embed code — the inbox is the configuration that makes the channel work.Supported channel typesKonversio supports several channel types for inboxes:Website — embeddable live chat widget for web pagesEmail — inbound and outbound via SMTP/IMAPWhatsApp — via the WhatsApp Business API (Meta)Telegram — via a Telegram bot tokenAPI — a generic channel for custom integrationsFacebook, Instagram, Line, SMS (Twilio/Bandwidth) — also available depending on your setupAgents and teamsEach inbox can have agents assigned to it directly. Only agents assigned to an inbox (or administrators) can see and respond to conversations in that inbox.You can also assign a team to an inbox. Teams are groups of agents — useful when you want a shared pool handling a particular channel without listing individuals each time.An agent can be assigned to multiple inboxes. An inbox can have multiple agents. There is no fixed limit.Multiple inboxesYou can create as many inboxes as you need. Common reasons to run multiple inboxes of the same channel type:Separate inboxes for different brands or products sharing one Konversio instanceDifferent email addresses routed to different teams (sales@, support@, billing@)Multiple websites with separate chat widgets, each with its own brandingManaging inboxesInboxes are created and configured under Settings → Inboxes. Each inbox has its own settings page where you can update its name, credentials, assigned agents, and automation rules after creation.Deleting an inbox does not delete the conversations that came through it — those remain in the system and are accessible to administrators.

Setting up WhatsApp

Setting up WhatsAppKonversio connects to WhatsApp via the official WhatsApp Business API. This gives you access to WhatsApp in a shared team inbox, with full conversation history and agent assignment.What you need before you startWhatsApp Business API access is controlled by Meta. You cannot connect a personal WhatsApp number or a WhatsApp Business App account directly. You need:A Meta Business Account (verified)A WhatsApp Business API phone number — provisioned through Meta directly or through a Meta Business Solution Provider (BSP)Your Phone Number ID — found in the Meta for Developers dashboard under your WhatsApp appA permanent API access token for that appIf you do not yet have WhatsApp Business API access, start at Meta's WhatsApp Business platform and follow their onboarding process. This step is outside Konversio's control and can take time if Meta requires business verification.Create a WhatsApp inboxGo to Settings → Inboxes → Add InboxSelect WhatsApp as the channel typeFill in:Channel name — an internal labelPhone Number ID — from the Meta for Developers dashboardAPI Access Token — a system user token or permanent page token with whatsapp_business_messaging permissionBusiness Account ID — also from the Meta dashboardClick Create Inbox and assign agentsConfigure the webhook in MetaAfter creating the inbox, Konversio displays a webhook URL. You must register this URL in your Meta app:In Meta for Developers, open your app and go to WhatsApp → ConfigurationSet the Webhook URL to the URL Konversio providedSet the Verify Token to the value shown in Konversio's inbox settingsSubscribe to the messages webhook fieldOnce the webhook is verified, incoming WhatsApp messages will open as conversations in Konversio.TestingSend a WhatsApp message from a personal number to your business number. Within a few seconds it should appear as a new conversation in the inbox. Reply from Konversio — the customer will receive it on WhatsApp.Limitations to be aware of24-hour messaging window: WhatsApp only allows free-form replies within 24 hours of the customer's last message. Outside that window, you can only send pre-approved template messages.Template messages: Templates must be created and approved in Meta's dashboard before use. They are typically used for proactive outreach (order updates, appointment reminders). You cannot send arbitrary outbound messages to customers who haven't messaged you recently.No broadcast lists: The Business API is for conversation-based support, not bulk messaging. Use a dedicated campaign tool for broadcast use cases.These are WhatsApp/Meta platform constraints, not Konversio limitations.