Messaging channels architecture #
Messaging channels connect a customer's chat app to the same conversation runtime that serves the web chat and the SDKs. This page describes the flow, the delivery guarantees and what is supported per channel. Channel-specific pages: Telegram and WhatsApp. The chat on your own website is described in Website chat widget.
Message flow #
- The provider (Telegram or Meta) sends each customer message to an HTTPS webhook of HeySora.
- The webhook address contains a secret path, and the request is verified with the provider's signature or secret header. Requests that fail verification are rejected.
- Every incoming event goes through durable deduplication, so a message that the provider delivers twice is processed once.
- The conversation runtime attaches the message to the right conversation of the right project.
- The AI agent answers from your approved knowledge, or hands the conversation to a human operator.
- The operator sees the conversation in the workspace inbox and can reply there.
- The outbound sender delivers every reply (AI or operator) to the provider and records the outcome.
Reliability #
- Idempotency. Incoming events are deduplicated by the provider's event identity, and outgoing replies carry an internal delivery key, so retries do not produce duplicate replies.
- Retries and backoff. Temporary provider errors are retried with exponential backoff. When the provider asks to slow down (a
Retry-Afterhint), the sender waits at least that long. - No silent failures. A reply that cannot be delivered ends in a visible final state (failed, or blocked with a reason), never in silence.
- Health visibility. Each connection shows its status and the last error in the workspace, so an administrator can see a broken credential or webhook without reading logs.
Project binding #
Every connection belongs to exactly one project of one organisation. The binding is enforced on the server for incoming and outgoing messages: a message can never be routed into another project or another organisation, whatever the provider payload contains.
Supported message types #
| Type | Telegram | |
|---|---|---|
| Text | Yes | Yes |
| Photo / image | Yes | Yes |
| Document | Yes | Yes |
| Voice / audio | Yes | Yes (audio) |
| Location | Polite "not supported" notice | Yes |
| Stickers | Polite "not supported" notice | Not part of the supported set |
| Video | Polite "not supported" notice | Not part of the supported set |
Types outside the supported set are not processed as content. Where the channel allows, the customer receives a short notice that the type is not supported and is invited to describe the request in text.
Delivery states #
| State | Telegram | |
|---|---|---|
| Sent | Yes | Yes |
| Delivered | No receipts from Telegram | Yes, from provider receipts |
| Read | No receipts from Telegram | Yes, from provider receipts |
| Failed | Yes | Yes |
| Blocked with reason | Not applicable | Yes (for example, outside the 24-hour window without an approved template) |
Setup, testing and troubleshooting #
Connection steps, credentials, project binding, testing and troubleshooting depend on your organisation and are available after you sign in: the Help centre holds the step-by-step connection guides and troubleshooting, and the Developers portal holds technical details and testing tools.