Concepts & Architecture

Before making your first request, understanding these concepts will prevent most integration questions and errors.

Application

An Application is the main organizational unit within Hub Chatt2.me. It:

• Groups one or more communication channels
• Has its own API Key
• Controls the access scope — a key can only see the channels of its own Application

Think of the Application as your "project" or "product" within the platform.

Channel

A Channel is the connection between your Application and a messaging platform. Examples:

Channel	What it represents
WhatsApp	A phone number connected via the WhatsApp Business API with Meta
Instagram	An Instagram Business account authorized via OAuth (Facebook or Instagram)
Facebook Messenger	A connected Facebook Page
Telegram	A Telegram Bot (via Bot Token)
SMS	An SMS number configured via Twilio
Web Chatt	A first-party web chat widget embedded on your site (configured in Hub)

The from field

The from field identifies the sending channel. A channel UUID works as a fallback; channel-specific aliases are also accepted. Discover available channels with GET /v1/integration/application/channels and use the returned from. For example, Web Chatt accepts its display name ignoring case, and Messenger accepts its Page username. A UUID-based request is:

{
  "from": "6cbd6789-1d2b-47e0-9391-5eb91d2839ea",
  "to": "5511993986082",
  "content": { "text": "Hello!" }
}

This UUID is generated by the platform when you connect the channel. You can find the channel UUID in the Application dashboard, under the Channels section.

tip

Store your channel UUIDs as environment variables in your backend. They do not change unless the channel is disconnected and reconnected.

Message

A Message is the sending payload — what you want to send and to whom. Every message has:

• from — sending channel UUID or supported channel alias
• to — recipient identifier in the channel
• content — the content (text, image, interactive, etc.)

The to field

The format of to varies by channel:

Channel	Format of to	Example
WhatsApp	E.164 number (without +)	5511993986082
Instagram	IGSID (Instagram user ID)	847495124317323
Messenger	PSID (Messenger conversation ID)	26203292189261166
Telegram	user/group chat_id	8568649397
SMS	E.164 number (with +)	+5511944574999
Web Chatt	Visitor identifier (from webhooks when the visitor messages you)	(per inbound payload)

Web Chatt setup

Connecting the widget and allowed origins are done in the Hub UI. See Web Chatt.

Message status

An ordinary successful send response includes messageId and status:

{
  "messageId": "9307b9ab-5fab-4151-b7c2-b00c2a8a6e8e",
  "status": "sent"
}

Status	Meaning
sent	Accepted by Telegram, Instagram, SMS, or Web Chatt; this does not guarantee the recipient read it.
enqueued	Queued for WhatsApp, Messenger, or any sandbox send.
error	Send failed — check errorMessage and errorCode in the response

Use messageId to correlate an ordinary send with webhook events. Control actions can return an empty ID or acknowledge an existing message. HTTP validation/authentication errors use the common error envelope instead of this result. See send responses for channel and control-action details.

Webhook

A Webhook is an HTTP endpoint you register to notify your integrated system of subscribed events. Hub receives and persists supported conversations independently of your external consumer. A webhook subscription controls which notifications reach your system; it does not create the provider connection.

Event family	Public event names
Conversation	message, message_status, end_chat
Operations	flag_for_review, session_transfer
Instagram comments	comment_automation
Appointments	appointment_action_required, appointment_confirmed, appointment_alternatives_requested, appointment_rescheduled, appointment_cancelled, appointment_rejected, appointment_expired

Configure an active, verified webhook and the channel subscriptions needed for your integration. Channel subscriptions can use provider-specific names; the delivered envelope uses the normalized eventType. Agent transfer policy also filters notifications. See webhook events for payloads and exact subscription mappings.

Workspace and session

A Workspace contains the Agent's knowledge, model and tools within one application. Select its ID in the channel's Agent configuration. A Session belongs to a channel and visitor and can reference that workspace; it tracks the conversation's lifecycle.

For message-linked operations, take the session UUID from payload.message.sessionId in a normalized webhook. It is separate from payload.message.id (a message ID) and a send response's messageId. Save the session UUID with the conversation. Workspaces and sessions explains discovery, tools, queues and closing. Session Assist supports ongoing sessions; CX Score requires a closed or expired session. Ordinary API sends can transfer an active Agent session to external handling; see session and billing effects.

Full flow

Your API Key
    │
    ▼
Application (groups channels and defines key scope)
    │
    ├── Channel WhatsApp  (from: uuid-wa)
    ├── Channel Telegram  (from: uuid-tg)
    └── Channel Instagram (from: uuid-ig)
         │
         ▼
    POST /v1/communication/{channel}/message
    { from, to, content }
         │
         ▼
    { messageId, status }
         │
         ▼  (asynchronous, via webhook)
    Your endpoint receives message received / status events