# Telegram

Each new submission is sent by your own Telegram bot to a chat, group or channel. You need the bot's token and the chat's id.

## What gets sent

On Pro, every submission that reaches the inbox is sent, and so is one you mark as not spam; spam is never sent. The message has:

- the title **New submission: \<form name\>**
- each field's name and value, leaving out fields hidden on the form's **Fields** tab
- an **Open in Formwire** link to the submission
- the page it was sent from

Field values are whatever the visitor typed. Read them as text from a stranger, not as instructions.

## 1. Make a bot

1. In Telegram, open a chat with [@BotFather](https://t.me/BotFather) and send `/newbot`.
2. Give the bot a name and a username ending in `bot`.
3. Copy the token it gives you. It looks like `123456789:AAE...`.

The token lets anyone act as your bot, so keep it out of your code and repos. If it leaks, send `/revoke` to @BotFather and paste the new token into Formwire.

## 2. Add the bot to the chat

- **A group:** add the bot as a member.
- **A channel:** add the bot as an administrator that can post messages.
- **A private chat with you:** open the bot and press **Start** (or send `/start`). A bot can't message you until you do.

## 3. Find the chat id

Send a message in the chat (in a channel, post something), then open this address in your browser with your token in it:

```text
https://api.telegram.org/bot<token>/getUpdates
```

Find your message in the reply and read `chat.id`:

```json title="Part of the reply"
{
  "message": {
    "chat": { "id": -1001234567890, "title": "Sales leads", "type": "supergroup" },
    "text": "hello"
  }
}
```

Groups and channels have negative ids, like `-1001234567890`; a private chat's id is positive. A public channel can use its `@username` instead. If the reply is empty, send another message and reload.

## 4. Add it in Formwire

In the dashboard, open the form, then **Settings**, **Integrations**. Under Telegram, choose **Add Telegram chat**, give it a name you'll recognise (such as `Sales group`), paste the bot token and the chat id, and save. It's live at once.

Choose **Send test** to send a sample submission to the chat. A form can have several Telegram chats, and up to 10 integrations in all. Each one can be switched off and on, edited or deleted from the same list.

## When a message fails

A failed message is retried automatically over a few hours. If five submissions in a row fail every retry, the chat is switched off and the workspace owners get an email. The last error shows beside it in the list; common causes are a bot removed from the chat, a channel bot that isn't an admin, or a private chat that was never started. Fix it and switch it back on.

Each submission's delivery list shows every message and its status, and you can retry a failed one from there.

## With the API or MCP

Integrations can be managed with the [API](/docs/api) too. Create one with a `type`, a `name` and its `config`:

```http title="Add a Telegram chat"
POST /v1/forms/{form_id}/integrations HTTP/1.1
Host: api.formwire.com
Authorization: Bearer fw_live_...
Content-Type: application/json

{
  "type": "telegram",
  "name": "Sales group",
  "config": { "bot_token": "123456789:AAE...", "chat_id": "-1001234567890" }
}
```

| Method | Path | What it does |
| ------ | ---- | ------------ |
| `GET` | `/forms/{form_id}/integrations` | The form's integrations. |
| `POST` | `/forms/{form_id}/integrations` | Add one. |
| `PATCH` | `/integrations/{integration_id}` | Rename it, switch it off or on, or replace its settings. |
| `DELETE` | `/integrations/{integration_id}` | Remove it. |
| `POST` | `/integrations/{integration_id}/tests` | Send a sample submission to it now. |

The bot token is never returned; `config_hint` shows the chat. One added or changed with an API key or through [MCP](/docs/mcp) sends nothing until a person confirms it in the dashboard, so an agent, or a prompt hidden in a submission, can't send your submissions somewhere new without you.