Channels
Channels connect a selected agent to a business-owned messaging destination while keeping its conversation history, human handoff, and delivery evidence in K...
Channels
Channels connect a selected agent to a business-owned messaging destination while keeping its conversation history, human handoff, and delivery evidence in Kravos.ai.
Implementation is not production approval
WhatsApp, Messenger, and Page-linked Instagram integrations are implemented. Availability depends on the deployed configuration, the business's authorization, and the approval and acceptance evidence for that channel. A saved connection, a successful webhook challenge, or an app-role test does not establish customer production access. Web text and web voice are separate supported surfaces. Slack and email inbox channels are not available here.
Setup Availability
Platform administrators control Meta setup with Meta channels (product.channels.meta.enabled) in /system-settings. It defaults off. Sandbox organizations always receive feature availability, but still require the same authorization, reviewed provider configuration, and production-readiness evidence.
When off, Channels navigation and /channels/** pages are hidden and onboarding, reconnect/replacement, activation, and setup test-send endpoints return not found. This is a setup-visibility switch, not an emergency stop: existing active connections keep receiving and sending through their workers, channel conversations remain in the inbox, and disable/revoke operations remain available through authorized connection APIs. Webhooks and Meta deauthorization/data-deletion compliance callbacks are never disabled by this switch. Turning it off does not revoke authorization or erase data.
Connect The Intended Agent
Open the intended agent's Channels page. Use its channel-specific onboarding flow, select the business asset you are authorized to manage, and verify the destination and agent before saving. WhatsApp uses Embedded Signup; Messenger uses Page consent; Instagram uses a Professional account and its linked Facebook Page.
A connection binds the tenant, selected agent, channel, provider app, and destination. Instagram also retains the linked Page/account pair. Readiness, provider subscription, activation, credential health, and payment readiness are distinct states. Follow the displayed next action instead of treating a saved credential as an active connection.
Credentials are encrypted and are not returned in connection metadata. Operators must not paste tokens into conversations, screenshots, support tickets, or model prompts.
Routing And Durable Processing
- Meta sends a webhook to the channel's public HTTPS endpoint.
- Kravos.ai verifies the signature against the original request body before trusting the payload.
- The signed destination resolves the tenant and selected agent through its connection. Customer IDs never select a different tenant.
- Admitted work is recorded in PostgreSQL before queue publication. BullMQ is a wake-up mechanism, not the only copy of an operation.
- The inbound worker retains the original connection, binding, conversation, and provider operation identity. Duplicate delivery does not create a new logical turn.
- AI-eligible turns pass assignment and conversation-ordering checks. A takeover can fence stale AI output.
- The runtime persists the canonical response; outbound intents retain the provider-visible segments and their independent delivery evidence.
- Recovery resumes safe durable work after a missed wake-up. It does not blindly repeat ambiguous provider sends.
Disconnected, revoked, replaced, and rebound connections cannot redirect old work to a new business or agent. Historical callbacks remain associated with their original operations.
Delivery Truth
| State | Meaning |
|---|---|
| Pending / Sending | An intent is waiting or dispatch is in progress; neither proves provider acceptance. |
| Accepted | Provider acceptance is evidenced; recipient delivery is not implied. |
| Delivered / Read | Channel-supported provider evidence establishes the corresponding event. Instagram does not supply a Delivered transition. |
| Unknown | Dispatch outcome is indeterminate; timeout or missing callback does not prove rejection. |
| Failed / Partial | Failure or mixed segment outcomes require inspection of the original delivery evidence. |
Inspect the original operation before retrying an Unknown send. An authorized operator can resolve without resending while preserving Unknown truth. A retry requires the existing reconciliation contract's non-acceptance evidence or explicit duplicate-risk acceptance; do not resend merely to clear an alert.
Media And Human Handoff
Supported inbound media follows the protected ingestion path. Unsupported or unavailable content must remain visibly truthful rather than appearing as a successful download. Outbound media depends on the channel's supported type, approved permissions, and connection readiness. Instagram media upload has a separate connection/version-bound approval gate.
App-generated echoes are correlated with outbound operations and do not themselves mean a human took over. Verified manual replies, assignment changes, and supported provider control events use the channel's handoff rules. Check both provider routing and local conversation ownership when investigating bot/human overlap.
Deployment Configuration
Public origins, webhook verification and signing secrets, supported Graph version, runtime connectivity, credential encryption, and reviewed onboarding configuration are operator-managed through approved configuration delivery. These are separate from each customer's encrypted connection credentials.
ChannelConfig and deployment-wide token settings remain only for the established unambiguous legacy compatibility path. Do not create a ChannelConfig as a substitute for new multi-tenant Meta onboarding, and do not use a global token to bypass a broken connection. Machine clients must use the current connection-aware selectors and authorization contracts exposed by their deployed tools.
Legacy compatibility still requires an active, verified recipient registration matching the signed phone-number or Page destination. update_channel_config verifies Meta credential ownership before recipient changes, credential replacements, or activation; an ownership conflict never reassigns another tenant's registration. Existing unregistered configs must complete verification rather than inferring ownership from sender history. Credentials are encrypted with their tenant/channel context and remain write-only.
Legacy replies and profile lookups use that tenant's registered credentials. Environment-token fallback is restricted to the operator-selected META_PLATFORM_TENANT_ID and an exact match to the configured phone-number or Page identity. Tenant settings cannot grant platform ownership, and connection-managed channels cannot be changed through a legacy channel-only write.
Acceptance And Troubleshooting
- Verify the selected business destination and agent, not just the channel name.
- A successful webhook challenge proves endpoint verification only. Observe a signed message, durable operation, canonical reply, and provider outcome separately.
- Check worker/recovery health, connection lifecycle, credentials, subscription, conversation assignment, and the applicable messaging window.
- Keep app-role development evidence separate from a non-role customer's own-asset acceptance.
- Do not log message content, raw customer identifiers, access tokens, consent codes, or provider response bodies while diagnosing failures.
- For privacy or Meta data deletion requests, follow the public Privacy Policy. Disconnecting authorization does not itself erase retained data.
Related Docs
WhatsApp Setup
Customer-owned Embedded Signup, connection readiness, and channel-specific acceptance.
Messenger Setup
Page consent, destination-scoped replies, and human handoff.