Skip to main content
Open In Colab Open on GitHub In this notebook we introduce send and retrieve message tools for 3 messaging platforms: Discord, Slack, and Telegram. These tools can be added to your AG2 agents, enabling them to send messages during a workflow and/or retrieve messages for use by the workflow. There are two types of tools, with one for each platform:
  • Sending a message (DiscordSendTool, SlackSendTool, TelegramSendTool)
  • Retrieving messages (DiscordRetrieveTool, SlackRetrieveTool, TelegramRetrieveTool)
You can attach one or more of them to an agent, though it may be most typical that you create an agent for each platform and attach their respective send and/or retrieve tools. This would allow you to tailor your system message for your agent to the messaging style used for the platform.
These tools are currently in our experimental namespace, indicating that we have tested the functionality but they have not been confirmed for use in production. Please use them with that in mind and we appreciate any feedback on them.If you do find any bugs please log an issue in the AG2 repository. If you would like to add more tools or functionality, we would love your contribution.

Installation

Each messaging platform requires installation of a package specifically for that platform. To use the Discord tools install AG2 with the commsagent-discord extra:
Similarly, for slack and telegram:
and
You’re all set! Now you can start sending to and retrieving messages from these platforms.

LLM Configuration

The examples in this notebook will use OpenAI’s GPT-4o mini model and the OPENAI_API_TOKEN will be retrieved from environment variables, we can use an LLM configuration as follows:
For further information on LLM configurations and how to set your environment variables up, check out our Basic Concepts guide.

Protecting details from the LLM

These tools utilise dependency injection to protect your authentication and channel/group details from being sent to the LLM. For more about AG2’s dependency injection, see this notebook.

Discord Send/Retrieve Messages

Tokens, Guilds, and Channels

The Discord tools, DiscordSendTool and DiscordRetrieveTool, require authentication (bot token), server (guild name), and channel details in order to send/retrieve messages. Here are some references to help you establish those details:
  • Creating a Bot Account, and another reference
  • Adding a Bot to a server
  • Bot Permissions you will need:
    • General Permissions: View Channels
    • Text Permissions: Send Messages, Read Message History, Use Slash Commands
  • Server/Guild Name - Right-click the Server > Server Settings > Overview, see the Server Name at the top right (e.g. “My Test Server”)
  • Channel name - The text after the hash (e.g. “general”)

Sending and retrieving messages with Discord

Let’s add the Discord Send and Retrieve tools to an agent and have them executed by another agent in a simple 2-agent chat.
Create our two agents.
Prepare our authentication, server/guild, channel details, then create our tools, and finally register them with the agents.
Let’s send a message to Discord, all about the wonders of Australia. We’ll limit it to 2 turns, allowing the Discord agent to receive the request, construct and recommend the send tool, and then the executor agent to execute the tool, sending the message to Discord.
And here’s the message it sent: And the output:
Let’s now retrieve the last two messages from the channel, this will include the message we sent as well as a previous one.
Output:

Slack Send/Retrieve Messages

Tokens and Channels

The Slack tools, SlackSendTool and SlackRetrieveTool, require authentication (OAuth token) and channel details in order to send/retrieve messages. Here are the steps to get a token:
  • Create an app, from scratch, at https://api.slack.com/apps
  • In your app settings, go to Features > OAuth & Permissions:
    • Under “Bot Token Scopes”, add these permissions:
      • chat:write (to send messages)
      • channels:history
      • channels:read (to access channel info)
      • groups:read (for private channels)
      • im:read (for direct messages)
      • users:read (to get user info)
      • files:read (to access file attachments)
      • groups:history
      • im:history
      • mpim:history
  • With your app setup, now install it in your workspace, using the “Install App” menu, to create an OAuth Token.
To get the ID for your channel:
  • Open Slack in a browser
  • Navigate to your channel
  • Get the channel ID from the URL (e.g., …/C12345678)
Finally you need to add the bot to your channel:
  • In Slack, go to your channel
  • Type /invite @YourBotName, e.g. /invite @ag2commsagent
Now you should be good to go with your OAuth token, channel ID, and a bot on your channel ready to send and retrieve messages!

Sending and retrieving messages with Slack

Let’s add the Slack Send and Retrieve tools to an agent and have them executed by another agent in as simple 2-agent chat. This time, we’ll include a weather tool so that we can send a weather forecast.
Create our two agents.
Prepare our authentication and channel details, then create our tools, and finally register them with the agents.
Here’s our weather tool and we’ll register it to the two agents, but this time using the register_function method to do it in one go.
Let’s send a message to Slack, giving everyone a weather forecast for today. We’ll limit it to 3 turns, allowing the Slack agent to receive the request, recommend the weather tool, and go around the agents and then construct and recommend the send tool. The executor agent will execute each tool request.
And here’s the message it sent: And the output:
Let’s now retrieve the last 5 messages to give a picture of the weather for the last week.
Output:

Telegram Send/Retrieve Messages

Tokens, Bots, Groups, and Channels

The Telegram tools, TelegramSendTool and TelegramRetrieveTool, require authentication (API ID and hash) and target Bot/Group/Channel details in order to send/retrieve messages. The Telegram tool is different to the Discord and Slack tools in that you can send/retrieve messages to/from a bot channel, a group channel, a channel, or even your own private channel. This is all handled by giving the respective ID to the chat_id parameter when creating the tool. Here’s how to establish your API ID and Hash: If you want to create a bot, which is optional but allows you to send messages to the bot channel:
  • In Telegram, search for (BotFather?)
  • Click on (BotFather?) (make sure it’s the correct one!) and click START
  • Message /newbot
  • Give it a name then a username
  • You’ll then receive a token for your bot and you see the links below to get the ID for your bot
There are four types of chat_ids you can send to:
  • Bot chat
  • Group chat
  • Channel chat
  • Private chat (noted in Telegram as Saved Messages)
To find these the IDs for these, here are some references: It takes a bit of time to get this sorted, but once you have your token and IDs, you’re ready to go!
You may be prompted for Telegram verification during the AG2 chat session. This typically happens when you first run it and is not required during subsequent runs.

Sending and retrieving messages with Telegram

Let’s add the Telegram Send and Retrieve tools to an agent and have them executed by another agent in as simple 2-agent chat.
Create our two agents.
Prepare our authentication and target chat id details, then create our tools, and finally register them with the agents. For this send, we’ll send it to a group using the group’s ID in our chat_id.
Let’s send a message to our Telegram channel, with a joke for the day. We’ll limit it to 2 turns, allowing the Telegram agent to receive the request, construct and recommend the send tool, and then the executor agent to execute the tool, sending the message to the Telegram group.
And here’s the joke message it sent: Telegram message And the output:
Let’s now retrieve the last 10 messages and get their IDs
Output with our messages and IDs (including our joke):
And, finally, let’s get all messages after a given ID, in this case ID 85. This should return 4 messages (IDs 90, 91, 92 ,98).
Output:
And that’s it! In this notebook we’ve seen how to send and receive messages across Discord, Slack, and Telegram!