---
title: "Open a private chat by Telegram username"
method: POST
path: "/chats/start"
---

# Open a private chat by Telegram username

`POST /chats/start`

## Request

- Base URL: `https://gramclaw.com/api/v1`
- URL: `https://gramclaw.com/api/v1/chats/start`
- Auth: HTTP bearer

Requires a send-scoped key, the Start Chat feature gate, and Idempotency-Key. Accepts only usernames and supported t.me username links. Resolves and opens the chat without sending a message; no Unipile or legacy provider fallback.

## Headers

- `Idempotency-Key` string, required

## Request body

- StartChatRequest
  - `account_id` string, required
  - `identifier` string, required: Telegram username, @username, or supported t.me username link.

## Response `200`

Exact account-scoped private chat, or replay of the completed operation

## Other responses

- `400`: Invalid username, phone number, unsupported input, or idempotency collision
- `403`: Missing send scope or unavailable account
- `404`: Username not found
- `409`: Suppressed/ineligible identity, in-flight request, or ambiguous prior outcome
- `429`: Telegram lookup/open rate limit or FLOOD_WAIT
- `503`: REST or Start Chat feature disabled

---

[API](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api.md) · [All operations](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api/revisions/7506dc9c905a?raw)