Inbox

Pillar 2 of 3

Direct messages and comments arrive on a single message resource with one shape, and replies go back out through the same call.

Live on Telegram

Coverage today

The inbox is live on Telegram — channels, groups and direct chats — and read-only everywhere else. Support for the remaining networks is in build behind the same resource, so adding them will not change the shape of your code.

The inbox holds what arrived while Nylon was connected. There is no backfill: the network pushes new messages to us, and nothing exists for a conversation that happened before the account was connected.

The model

One resource, two kinds of thread. A direct message and a comment thread are the same object with kind set to dm or comment, because an integration triaging “what came in and what has nobody answered” wants one list rather than two.

One conversation shape

A Telegram group and a direct chat carry the same participant, unread count and last message. Only kind and network differ.

Replies go back the same way

One call answers either. A comment thread gets a public reply; a direct message gets a private one — Nylon picks the right API from the thread.

Unread is a queue, not a view

Reading a thread does not clear it. Marking read is its own call, so two agents on one inbox do not clear each other’s work.

Told, not polled

The inbox webhook events fire as things happen — arrived, sent, delivered, read, edited, unsent, reacted to — so nothing has to sit in a loop asking. Everything they report is stored regardless: the webhook is a notification about the inbox, not the inbox itself.

Endpoints


`GET /v1/inbox/conversations`	Threads, most recent activity first. Filter by network, kind, profile, or `unread=true`.
`GET /v1/inbox/conversations/{id}`	One thread.
`GET /v1/inbox/conversations/{id}/messages`	The messages in it, newest first.
`POST /v1/inbox/conversations/{id}/messages`	Reply, sent immediately.
`POST /v1/inbox/conversations/{id}/read`	Clear the unread count.

curl "https://api.nylon.dev/v1/inbox/conversations?unread=true" \
  -H "Authorization: Bearer nylon_live_YOUR_API_KEY"

{
  "data": [
    {
      "id": "cly8a1b2c0001x8b3d4e5f0gg",
      "profile_id": "cly7p2q4k0003x8b3j6k2f0cc",
      "network": "telegram",
      "kind": "dm",
      "participant": { "id": "17841400000", "name": "Rasa", "handle": null, "avatar_url": null },
      "status": "open",
      "unread_count": 2,
      "last_message": { "text": "do you ship to Lithuania?", "at": "2026-09-23T09:14:02Z" }
    }
  ],
  "meta": { "pagination": { "limit": 25, "has_more": false, "next_cursor": null } }
}

Pagination

The inbox is cursor-paged, unlike the rest of the API. An inbox reorders while you read it — every arriving message moves a thread to the top — so an offset would show you the same conversation on page one and page two while something else slipped through the gap. Pass meta.pagination.next_cursor back as cursor.

Replying

curl -X POST https://api.nylon.dev/v1/inbox/conversations/cly8a1b2c0001x8b3d4e5f0gg/messages \
  -H "Authorization: Bearer nylon_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"We do — shipping is free over €50."}'

A reply in a comment thread is public. The same call in a dm thread is private. Check kind before you send something you would not post.

Message kinds

Kind	Telegram
Direct message	Yes
Comment	—
Mention	—

kind and network are part of the shape rather than of Telegram, so a comment thread on a network added later needs no change at the call site. A Telegram chat — whether a private message, a group or a channel — is one conversation, because a chat is the place you answer.

Connecting

Telegram has no consent screen, because a bot only learns a chat exists once somebody speaks to it. Connecting is two steps, both in Telegram:

Add Nylon’s bot to the channel, group or chat, as an admin so it can post.
Send /connect <code> in that chat. The code comes from Connections → Telegram in Nylon and lasts 15 minutes.

The chat appears in your connections as soon as the bot replies, and messages sent there reach the inbox from that moment. Nothing from before it was connected is available — Telegram does not offer history to a bot.

Every Nylon connection posts as the same bot, so there is no token to store, rotate or reconnect. Replies are sent as the bot, not as a person.

Get started

Capabilities

Guides

Coverage today

The model

One conversation shape

Replies go back the same way

Unread is a queue, not a view

Told, not polled

Endpoints

Replying

Message kinds

Connecting

​Coverage today

​The model

One conversation shape

Replies go back the same way

Unread is a queue, not a view

Told, not polled

​Endpoints

​Pagination

​Replying

​Message kinds

​Connecting

Coverage today

The model

Endpoints

Pagination

Replying

Message kinds

Connecting