Home Channels & Inboxes Creating an API channel inbox

Creating an API channel inbox

Last updated on Jun 05, 2026

Creating an API channel inbox

The 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 for

The 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 widget
  • Kiosk or point-of-sale support interface
  • Aggregating messages from a platform Konversio doesn't natively support
  • Internal helpdesk where the "user" is another system rather than a human

Create an API channel inbox

  1. Go to Settings → Inboxes → Add Inbox
  2. Select API as the channel type
  3. Give the inbox a name and click Create Inbox
  4. Assign agents as usual

After creation, the inbox settings page shows:

  • Your Inbox Identifier (a token used to scope API calls to this inbox)

Pushing messages in

To create a conversation and send a message into the inbox, use the Konversio public API. You will need:

  • Your Konversio instance URL
  • The Inbox Identifier from the inbox settings
  • A contact identifier (you create or look up contacts via the API as well)

A minimal flow:

  1. Create or find a contact — POST /api/v1/profile or POST /api/v1/accounts/{account_id}/contacts
  2. Create a conversation — POST /api/v1/accounts/{account_id}/conversations with the inbox ID and contact ID
  3. Create a message in that conversation — POST /api/v1/accounts/{account_id}/conversations/{id}/messages

The 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 webhook

When 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 sessions

For 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 chat

A typical mobile app integration:

  1. User taps "Contact support" in the app
  2. App backend calls Konversio to create or retrieve a contact using the user's account ID as the identifier
  3. App creates a conversation in the API channel inbox and posts the user's first message
  4. Konversio routes the conversation to an available agent
  5. Agent replies in Konversio
  6. Webhook fires to your backend, which pushes the reply to the mobile app via push notification or WebSocket
  7. User sees the reply inside the app

The API channel gives you full control over the user-facing UI while Konversio handles the agent-side tooling.