Telegram

Telegram Connection

Put Telegram to Work with @Human Automations and @Human Agents

The Telegram Connection documents all Triggers, Actions and Query Operations available for creating automations via the Telegram API.

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

Action: Send Poll

Action: Send Photo

Query Operations

Example link

Related Automations

Example link

Obtaining Access Credentials

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.

   • 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 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
            }
          ]
        }
      }
    }
  }
]