> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/human-connections/telegram/telegram.md).

# Telegram

<p align="center"><a class="button primary" data-icon="circle-caret-right">Try @Human</a><a class="button primary" data-icon="check">Buy @Human Subscription</a><a class="button primary" data-icon="comments">Join @Human Community</a></p>

<figure><img src="/files/cn1fOLqqhuk2M5U1T0gb" alt="" width="188"><figcaption></figcaption></figure>

<h3 align="center">Put Telegram to Work with @Human Automations and @Human Agents</h3>

<p align="center">The Telegram Connection documents all Triggers, Actions and Query Operations available for creating automations via the Telegram API.</p>

{% embed url="<https://www.youtube.com/watch?v=CyuUuaBSZzA>" %}

#### What can you do with the Telegram Connection?

* Connect to the Telegram API in a few clicks
* Use the related Telegram Operations (see below) in @Human Automations or @Human Agents

### Related Operations

#### Trigger Operations

**New Message**

Triggers on: messages/new\_message

Triggered when a new message is received in a Telegram chat.

#### Action Operations

[Action: Send Message](/human-connections/telegram/telegram/action-send-message.md)

[Action: Send Poll](/human-connections/telegram/telegram/action-send-poll.md)

[Action: Send Photo](/human-connections/telegram/telegram/action-send-photo.md)

#### Query Operations

Example link

### Related Automations

Example link

### Obtaining Access Credentials <a href="#obtaining-access-credentials" id="obtaining-access-credentials"></a>

To obtain a **Personal Access Token (PAT)** for **Telegram Bot API**, follow these steps:

#### **Steps:**

1. **Log in to Telegram**
   * Use an account with admin privileges (if managing a bot for an organization).
2. **Create a Bot (if not already done)**
   * Open a chat with [@BotFather](https://t.me/BotFather).
   * Send `/newbot` and follow prompts to name and generate a bot.
   * Copy the **Bot Token** (this is your PAT).
3. **Access the Token**
   * The token is immediately provided by @BotFather after creation.
   * Store it securely (e.g., environment variables, secrets manager).

### Configuring Webhooks

1. **Obtain the Bot Token**: Acquire the unique API token for your bot from [@BotFather](https://t.me/BotFather) as described in the access credentials section.
2. **Configure a Secure Endpoint**: Prepare a public HTTPS-enabled URL on your server to receive JSON-formatted update payloads from Telegram.
3. **Register the Webhook**: Send a `POST` or `GET` request to the Telegram Bot API using the `setWebhook` method: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=<YOUR_PUBLIC_HTTPS_URL>`.
4. **Validate the Setup**: Confirm the registration was successful by checking the API response for an `"ok": true` status and a success message.
5. **Inspect Webhook Information**: Submit a request to the `getWebhookInfo` endpoint (`https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo`) to review the current configuration and troubleshoot any delivery issues.

### Code (Apache v2.0): Service Connectivity and Metadata

```
{
  "handle": "telegram",
  "status": "active",
  "meta": {
    "short": "Telegram",
    "description": "Connect to Telegram's API to send messages, manage chats, and interact with bots.",
    "icon": "telegram",
    "tags": ["messaging", "chat", "bot", "api"]
  },
  "service": {
    "baseURL": {
      "value": "https://api.telegram.org/bot{{botToken}}"
    },
    "protocol": "https",
    "contentType": "application/json",
    "headers": {},
    "auth": {
      "method": "api_token",
      "params": {
        "apiToken": {
          "token": {
            "value": "{{botToken}}"
          },
          "headerName": {
            "value": ""
          }
        }
      }
    }
  }
}

```

### Code (Apache v2.0): List of External Resources and Internal Mapping

```
[
  {
    "handle": "users",
    "meta": {
      "short": "Users",
      "description": "Manage bots and user metadata."
    },
    "endpoint": "/bot{{token}}/getMe",
    "fields": [
      {
        "name": "id",
        "type": "Integer",
        "selector": [
          "result",
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the bot or user."
        }
      },
      {
        "name": "is_bot",
        "type": "Boolean",
        "selector": [
          "result",
          "is_bot"
        ],
        "meta": {
          "description": "True, if this user is a bot."
        }
      },
      {
        "name": "first_name",
        "type": "String",
        "selector": [
          "result",
          "first_name"
        ],
        "meta": {
          "description": "User's or bot's first name."
        }
      },
      {
        "name": "username",
        "type": "String",
        "selector": [
          "result",
          "username"
        ],
        "meta": {
          "description": "User's or bot's username."
        }
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": "",
        "queryParams": {},
        "placeholders": []
      }
    }
  },
  {
    "handle": "messages",
    "meta": {
      "short": "Messages",
      "description": "Send and receive messages in Telegram chats."
    },
    "endpoint": "/bot{{token}}/sendMessage",
    "fields": [
      {
        "name": "chat_id",
        "type": "Integer",
        "selector": [
          "chat_id"
        ],
        "meta": {
          "description": "Unique identifier for the target chat."
        }
      },
      {
        "name": "text",
        "type": "String",
        "selector": [
          "text"
        ],
        "meta": {
          "description": "Text of the message to be sent."
        }
      },
      {
        "name": "message_id",
        "type": "Integer",
        "selector": [
          "result",
          "message_id"
        ],
        "meta": {
          "description": "Unique identifier for the sent message."
        }
      },
      {
        "name": "date",
        "type": "Integer",
        "selector": [
          "result",
          "date"
        ],
        "meta": {
          "description": "Date the message was sent in Unix time."
        }
      },
      {
        "name": "result_chat_id",
        "type": "Integer",
        "selector": [
          "result",
          "chat",
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the chat."
        }
      },
      {
        "name": "result_chat_type",
        "type": "String",
        "selector": [
          "result",
          "chat",
          "type"
        ],
        "meta": {
          "description": "Type of chat (private, group, supergroup, channel)."
        }
      }
    ],
    "operations": {
      "create": {
        "method": "POST",
        "path": "",
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"chat_id\": {{chat_id}}, \"text\": \"{{text}}\"}",
          "placeholders": [
            {
              "name": "chat_id",
              "type": "Integer",
              "description": "Unique identifier for the target chat.",
              "required": true
            },
            {
              "name": "text",
              "type": "String",
              "description": "Text of the message to be sent.",
              "required": true
            }
          ]
        }
      }
    },
    "webhooks": [
      {
        "event": "new_message",
        "path": "/webhooks/telegram/messages",
        "payload": [
          {
            "name": "message_id",
            "type": "Integer",
            "selector": [
              "message",
              "message_id"
            ],
            "meta": {
              "description": "Unique identifier for the message."
            }
          },
          {
            "name": "chat_id",
            "type": "Integer",
            "selector": [
              "message",
              "chat",
              "id"
            ],
            "meta": {
              "description": "Unique identifier for the chat."
            }
          },
          {
            "name": "chat_type",
            "type": "String",
            "selector": [
              "message",
              "chat",
              "type"
            ],
            "meta": {
              "description": "Type of chat."
            }
          },
          {
            "name": "text",
            "type": "String",
            "selector": [
              "message",
              "text"
            ],
            "meta": {
              "description": "Text of the message."
            }
          }
        ]
      }
    ]
  },
  {
    "handle": "photos",
    "meta": {
      "short": "Photos",
      "description": "Send photos to a chat."
    },
    "endpoint": "/bot{{token}}/sendPhoto",
    "fields": [
      {
        "name": "chat_id",
        "type": "Integer",
        "selector": [
          "chat_id"
        ],
        "meta": {
          "description": "Unique identifier for the target chat."
        }
      },
      {
        "name": "photo",
        "type": "String",
        "selector": [
          "photo"
        ],
        "meta": {
          "description": "Photo to send. Pass a file_id or URL."
        }
      },
      {
        "name": "caption",
        "type": "String",
        "selector": [
          "caption"
        ],
        "meta": {
          "description": "Photo caption."
        }
      },
      {
        "name": "message_id",
        "type": "Integer",
        "selector": [
          "result",
          "message_id"
        ],
        "meta": {
          "description": "Unique message identifier."
        }
      },
      {
        "name": "result_chat_id",
        "type": "Integer",
        "selector": [
          "result",
          "chat",
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the chat."
        }
      }
    ],
    "operations": {
      "create": {
        "method": "POST",
        "path": "",
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"chat_id\": {{chat_id}}, \"photo\": \"{{photo}}\", \"caption\": \"{{caption}}\"}",
          "placeholders": [
            {
              "name": "chat_id",
              "type": "Integer",
              "description": "Unique identifier for the target chat.",
              "required": true
            },
            {
              "name": "photo",
              "type": "String",
              "description": "Photo to send.",
              "required": true
            },
            {
              "name": "caption",
              "type": "String",
              "description": "Photo caption.",
              "required": false
            }
          ]
        }
      }
    }
  },
  {
    "handle": "polls",
    "meta": {
      "short": "Polls",
      "description": "Send a poll to a chat."
    },
    "endpoint": "/bot{{token}}/sendPoll",
    "fields": [
      {
        "name": "chat_id",
        "type": "Integer",
        "selector": [
          "chat_id"
        ],
        "meta": {
          "description": "Unique identifier for the target chat."
        }
      },
      {
        "name": "question",
        "type": "String",
        "selector": [
          "question"
        ],
        "meta": {
          "description": "Poll question, 1-300 characters."
        }
      },
      {
        "name": "options",
        "type": "Array",
        "selector": [
          "options"
        ],
        "meta": {
          "description": "A JSON-serialized list of answer options, 2-10 strings."
        }
      },
      {
        "name": "message_id",
        "type": "Integer",
        "selector": [
          "result",
          "message_id"
        ],
        "meta": {
          "description": "Unique message identifier."
        }
      },
      {
        "name": "poll_id",
        "type": "String",
        "selector": [
          "result",
          "poll",
          "id"
        ],
        "meta": {
          "description": "Unique poll identifier."
        }
      }
    ],
    "operations": {
      "create": {
        "method": "POST",
        "path": "",
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"chat_id\": {{chat_id}}, \"question\": \"{{question}}\", \"options\": {{options}}}",
          "placeholders": [
            {
              "name": "chat_id",
              "type": "Integer",
              "description": "Unique identifier for the target chat.",
              "required": true
            },
            {
              "name": "question",
              "type": "String",
              "description": "Poll question.",
              "required": true
            },
            {
              "name": "options",
              "type": "Array",
              "description": "Options array.",
              "required": true
            }
          ]
        }
      }
    }
  },
  {
    "handle": "updates",
    "meta": {
      "short": "Updates",
      "description": "Receive incoming updates from Telegram."
    },
    "endpoint": "/bot{{token}}/getUpdates",
    "fields": [
      {
        "name": "offset",
        "type": "Integer",
        "selector": [
          "offset"
        ],
        "meta": {
          "description": "Identifier of the first update to be returned."
        }
      },
      {
        "name": "limit",
        "type": "Integer",
        "selector": [
          "limit"
        ],
        "meta": {
          "description": "Limits the number of updates to be retrieved."
        }
      },
      {
        "name": "timeout",
        "type": "Integer",
        "selector": [
          "timeout"
        ],
        "meta": {
          "description": "Timeout in seconds for long polling."
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": "",
        "queryParams": {
          "offset": "{{offset}}",
          "limit": "{{limit}}",
          "timeout": "{{timeout}}"
        },
        "placeholders": [
          {
            "name": "offset",
            "type": "Integer",
            "description": "Identifier of the first update.",
            "required": false
          },
          {
            "name": "limit",
            "type": "Integer",
            "description": "Limits the number of updates.",
            "required": false
          },
          {
            "name": "timeout",
            "type": "Integer",
            "description": "Timeout in seconds.",
            "required": false
          }
        ]
      }
    }
  },
  {
    "handle": "chats",
    "meta": {
      "short": "Chats",
      "description": "Manage Telegram chats and retrieve information about them."
    },
    "endpoint": "/bot{{token}}/getChat",
    "fields": [
      {
        "name": "chat_id",
        "type": "Integer",
        "selector": [
          "chat_id"
        ],
        "meta": {
          "description": "Unique identifier for the target chat."
        }
      },
      {
        "name": "id",
        "type": "Integer",
        "selector": [
          "result",
          "id"
        ],
        "meta": {
          "description": "Unique identifier for this chat."
        }
      },
      {
        "name": "type",
        "type": "String",
        "selector": [
          "result",
          "type"
        ],
        "meta": {
          "description": "Type of chat (e.g., private, group, supergroup, channel)."
        }
      },
      {
        "name": "title",
        "type": "String",
        "selector": [
          "result",
          "title"
        ],
        "meta": {
          "description": "Title of the chat (for groups, supergroups, and channels)."
        }
      },
      {
        "name": "username",
        "type": "String",
        "selector": [
          "result",
          "username"
        ],
        "meta": {
          "description": "Username, for private chats, supergroups and channels if available."
        }
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": "",
        "queryParams": {
          "chat_id": "{{chat_id}}"
        },
        "placeholders": [
          {
            "name": "chat_id",
            "type": "Integer",
            "description": "Unique identifier for the target chat.",
            "required": true
          }
        ]
      }
    }
  },
  {
    "handle": "webhooks",
    "meta": {
      "short": "Webhooks",
      "description": "Manage webhook configuration for receiving updates."
    },
    "endpoint": "/bot{{token}}/setWebhook",
    "fields": [
      {
        "name": "url",
        "type": "String",
        "selector": [
          "url"
        ],
        "meta": {
          "description": "HTTPS URL to send updates to."
        }
      },
      {
        "name": "result",
        "type": "Boolean",
        "selector": [
          "result"
        ],
        "meta": {
          "description": "True on success."
        }
      },
      {
        "name": "description",
        "type": "String",
        "selector": [
          "description"
        ],
        "meta": {
          "description": "Error or success description."
        }
      }
    ],
    "operations": {
      "create": {
        "method": "POST",
        "path": "",
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"url\": \"{{url}}\"}",
          "placeholders": [
            {
              "name": "url",
              "type": "String",
              "description": "HTTPS URL to send updates to.",
              "required": true
            }
          ]
        }
      }
    }
  }
]
```

<p align="center"><a class="button primary" data-icon="square-caret-right">Try @Human</a><a class="button primary" data-icon="check">Buy @Human Subscription</a><a class="button primary" data-icon="comments">Join @Human Community</a></p>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.planetcrust.com/human-connections/telegram/telegram.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.