Skip to main content

Karix WhatsApp

The Karix WhatsApp integration lets you connect a published Agent to a WhatsApp Business number provisioned through Karix (a major RCM provider for WhatsApp in India and APAC). Inbound user messages — including voice notes — flow into the Agent, and the Agent's text response is delivered back to the user via Karix.

Where it lives​

  • Open the Agent in Studio.
  • Go to the Deployment tab. (The tab is visible after the Agent has at least one published version.)
  • Open the Third-party integrations sub-tab.
  • Pick Karix WhatsApp.

A side drawer opens with the configuration form on the left and setup instructions on the right.

Configuration​

Auth & Karix config​

Required:

  • Karix API Key / Token — your WhatsApp API access token from the Karix console. Stored encrypted, shown as ••••• once saved.

Optional (where applicable for your Karix tenant):

  • Karix Account / App / Tenant ID
  • WABA number / sender identifier
  • Base URL / Region — pick if your Karix tenant uses a non-default region.

A Test connection button validates the token. Errors are surfaced clearly: 401 (invalid key), 403 (permission denied), 429 (rate-limited), 5xx (upstream error).

Webhook​

  • Webhook URL — read-only, copy with the icon.
  • Required headers — read-only, copy as JSON for paste into Karix. Typically:
X-SimplAI-Webhook-Token: <generated secret>
  • Rotate webhook token — generates a new secret. Important: rotating requires you to update the headers in the Karix console as well, or inbound messages will stop.

Voice message processing (optional)​

A toggle: Process audio/voice messages.

When off (default), inbound voice notes are not processed — your agent receives no input for that message (you can configure a fallback response in the agent's base instruction).

When on, configure:

  • ASR Provider — same provider list as Voice Agents (see Voice Agent BYOK).
  • Languages — multi-select.
  • Auto-detect language — if the provider supports it.

Setup steps (Karix console side)​

  1. Get your Karix credentials. Log in to the Karix console; locate your WhatsApp API access token. Paste it into Karix API Key / Token in SimplAI and click Save.
  2. Copy your SimplAI Webhook URL and headers. Stay in the SimplAI drawer; you'll paste these into Karix next.
  3. Configure the webhook in Karix. Open the Karix Bot Builder console at https://managebot.karix.solutions/bot_builder_gui/#/login, go to WhatsApp Campaign → Webhook Config, pick your WABA number, click Create.

Fill in the webhook config for both of these:

  • User-initiated Rules (inbound user messages) — paste the SimplAI Webhook URL, add the headers from SimplAI, set Max retry attempts to 3 and Max interval time to 5 minutes.
  • Delivery Events (sent / delivered / read callbacks) — same URL, same headers, pick the delivery rules you need (recommended: sent / delivered / read), configure retries and interval, click Save.

After saving, Karix issues a Webhook ID — keep it on the Karix side for your reference.

  1. Need help from Karix? For webhook provisioning or account-side enablement, contact [email protected].

  2. Voice messages (optional). If you enabled voice processing, SimplAI downloads the incoming voice media from Karix, transcribes it via your selected ASR provider, and feeds the transcript to the Agent as text input. The Agent responds in text (which is sent back to WhatsApp).

How messages flow at runtime​

  • Karix delivers an event to SimplAI's webhook endpoint.
  • SimplAI identifies the agent version, integration instance, and end-user identity (WhatsApp number) from the payload.
  • Each distinct end user maps to a separate conversation thread. The conversation key is the combination of (agent_version_id, channel=whatsapp, karix_waba_id, end_user_id). The platform stores the last N turns (typically 10) for context.
  • Text messages: input = message text + conversation context; output = agent's text reply (max 65,536 characters), sent back via Karix.
  • Voice messages: media downloaded via Karix-provided link, transcribed via ASR, transcript becomes the agent's input; agent's text response is sent back as a text WhatsApp message.

Reliability​

  • The webhook handler is idempotent — duplicate events are deduplicated by (karix_message_id, event_type), so Karix retries don't double-process.
  • If ASR or Agent execution exceeds the configured timeout, the user gets a graceful fallback (or no response, configurable) — the platform doesn't hang indefinitely.

Pricing​

  • 1 WhatsApp message = 1 user message + 1 agent response. Credits are charged per message unit.
  • Voice transcription is billed separately based on voice duration in seconds.
  • BYOK ASR — if you provide your own ASR key, the ASR usage bills against your provider account directly; SimplAI may charge a small platform overhead credit (check with your GTM contact for the current policy).

The Karix line item in your usage screen splits messaging credits from ASR credits so you can see each independently.

Audit and observability​

  • Audit log entries are created on integration create, update, and webhook-token rotate. Secret values are never logged.
  • Tracing links the inbound webhook event → ASR step (if any) → agent run → outbound Karix send, so a single conversation turn is visible end-to-end. See Live tracing.

Troubleshooting​

  • Inbound messages don't arrive. Verify the Webhook URL and headers in the Karix console match exactly. Test the connection from the SimplAI drawer.
  • 401 / 403 on test connection. Karix token is invalid or lacks permission — regenerate in the Karix console and re-save.
  • Duplicate messages. Karix is retrying — verify your idempotency by checking the karix_message_id in the trace; if duplicates persist, file a ticket.
  • Voice notes not processed. Check that voice processing is toggled on and an ASR provider is selected. Verify the ASR key (or BYOK key) is valid.
  • Outbound message rejected by Karix. Check WhatsApp's 24-hour customer-service window and template-message rules — outbound to a user outside the 24-hour window may require an approved template.

What's not in scope (today)​

  • Outbound campaign messaging (sending unprompted WhatsApp messages to a list) — Karix integration today is for inbound + reply flow.
  • WhatsApp template message authoring inside SimplAI — templates must be created and approved on the Karix side.
  • Direct media (image, document) generation by the Agent for WhatsApp — Agent responses are text-only on this channel.