Adding Messaging Channel Capabilities
You can use an integration to add any messaging channel to your bot, such as Line, Facebook Messenger, or Instagram.
In this tutorial, we'll extend your existing integration to send and receive text messages to Telegram. We'll also create a bot to test it out. You can follow the instructions below or follow along the video.
Modify the Integration Definition
First, let's add the necessary configuration to your existing your integration definition, so your users will be able to use Telegram to connect to their own channel.
Step 1: Add Telegram Configuration
Add the following configuration schema to you integration.definition.ts
:
// integration.definition.ts
import { IntegrationDefinition, z } from '@botpress/sdk' // import the zod library like this
export default new IntegrationDefinition({
// ...existing properties
configuration: {
schema: z.object({
botToken: z.string(), // users of your integration will provide this token to connect to their Telegram bot
}),
},
// ...existing properties
})
The configuration schema is used to validate the integration's configuration and ask users to provide information when adding the integration to their bot. In this case, we are adding a botToken
which will store the Telegram Bot API token.
Step 2: Define Telegram Channels and Tags
Next update the channels
and user
properties to support Telegram-specific functionality:
// integration.definition.ts
export default new IntegrationDefinition({
// ...existing properties
channels: {
group: {
// messages: messages.defaults, // use this to support all message types supported in Botpress Studio
messages: {
text: messages.defaults.text, // For our example, we'll specify text messages only
},
message: {
tags: {
id: {}, // Add this line to tag messages
},
},
conversation: {
tags: {
id: {}, // Add this line to tag conversations
},
},
},
},
user: {
tags: {
id: {}, // Add this line to tag users
},
},
// ...existing properties
})
The channels
property defines the communication channels your integration supports. Here, we define a group
channel to send messages to a specific group in Telegram. The messages
property, on the other hand, defines the message types that this channel support. We set it to messages.defaults.text
, for it to support text
messages in the Botpress Studio. Tags are used to identify users, conversations, and messages within the Telegram system.
Add the Integration Logic
Now that we've handled all the definitions, let's handle the logic that allows messages to flow to / from Botpress and Telegram. We'll use the Telegraf library to manage calls to the Telegram API.
Let's install it:
npm i telegraf
Step 3: Register and Unregister Webhooks
Update your src/index.ts
to manage the lifecycle of the integration:
// src/index.ts
import { Telegraf } from 'telegraf'
import { Integration, RuntimeError } from '@botpress/sdk' // import the RuntimeError class
export default new Integration({
// ...existing properties
register: async ({ webhookUrl, ctx }) => {
const telegraf = new Telegraf(ctx.configuration.botToken)
try {
await telegraf.telegram.setWebhook(webhookUrl)
} catch (error) {
throw new RuntimeError(
'Configuration Error! The Telegram bot token is not set. Please set it in your bot integration configuration.'
)
}
},
unregister: async ({ ctx }) => {
const telegraf = new Telegraf(ctx.configuration.botToken)
await telegraf.telegram.deleteWebhook({ drop_pending_updates: true })
},
// ...existing properties
})
The register
function sets up the webhook for Telegram when the integration is added to a bot. The unregister
function removes the webhook when the integration is removed from a bot. These functions also validate the configuration.
If the configuration is invalid, a RuntimeError
is thrown, which will be displayed to the user in the Bot's Integration configuration page.
Step 4: Handle Incoming Messages
Add the handler function to process incoming messages from Telegram:
// src/index.ts
export default new Integration({
// ...existing properties
handler: async ({ req, client }) => {
const data = JSON.parse(req.body)
const conversationId = data?.message?.chat?.id
const userId = data?.message?.from?.id
const messageId = data?.message?.message_id
if (!conversationId || !userId || !messageId) {
return {
status: 400,
body: "Handler didn't receive a valid message",
}
}
const { conversation } = await client.getOrCreateConversation({
channel: 'group',
tags: { 'id': `${conversationId}` },
})
const { user } = await client.getOrCreateUser({
tags: { 'id': `${userId}` },
})
await client.createMessage({
tags: { 'id': `${messageId}` },
type: 'text',
userId: user.id,
conversationId: conversation.id,
payload: { text: data.message.text },
})
},
// ...existing properties
})
The handler
function processes incoming requests from Telegram. It extracts the conversation ID, user ID, and message ID, then creates or retrieves the conversation, user, and message using the client parameter. Finally, it creates a message in the conversation, which will be sent to the bot as an incoming message from Telegram.
Step 5: Send Messages to Telegram
Implement the text
message type in the group
channel:
// src/index.ts
export default new Integration({
// ...existing properties
channels: {
group: {
messages: {
text: async ({ payload, ctx, conversation, ack }) => {
const client = new Telegraf(ctx.configuration.botToken)
const message = await client.telegram.sendMessage(conversation.tags['id']!, payload.text)
await ack({ tags: { 'id': `${message.message_id}` } })
},
},
},
},
// ...existing properties
})
The channels
object implements the group
channel we defined earlier. The text
message type sends a text message to the specified Telegram group. This function is called every time the bot sends a text message to the group
channel.
Try it Out
Before trying it out, make sure you either run npm run deploy
or npm run start
to deploy the changes to your Botpress Cloud workspace.
- Send a message to the BotFather (opens in a new tab) on Telegram and create a new bot. It will provide you with a token.
- Go to your Botpress Cloud workspace (opens in a new tab).
- Click your bot's name.
- Click on "Integrations" in the sidebar.
- Click your integration name.
- Add your Telegram Bot API token in the configuration in the input.
- Make sure the integration is enabled.
- Hit "Save".
- Open your bot in Telegram and chat with it!
Congratulations! You've just added Telegram chat capabilities to your bot. Now, you can use this integration in any bot that you create in this workspace.
Next up, we'll add action cards and external triggers to your integration.