Integrating with External Services via API

Imagine you're trying to get updates from a friend who only communicates through notes left in a specific mailbox. You need to know where the mailbox is and have the key to open it. Similarly, to get data from online services like Telegram, you need a specific "address" and a "key."

By the end of this lesson, you'll be able to retrieve data from external services like Telegram using API calls and process it within Claude Code.

Core idea

Many online services offer an Application Programming Interface (API), which is a set of rules and protocols that allows different software applications to communicate with each other. Think of an API as a waiter in a restaurant: you (your application) tell the waiter (the API) what you want (data from a service), and the waiter goes to the kitchen (the service's servers) to get it for you.

For services like Telegram, the API provides specific web addresses (URLs) that you can "visit" to request data. To ensure only authorized users access this data, these URLs often require a token. A token is a unique string of characters that acts like a digital key or password, verifying your identity and permissions to the service. When you include your token in an API request, the service knows it's you asking for the data and sends it back.

The data returned by an API is typically formatted in a structured way, most commonly as JSON (JavaScript Object Notation). JSON is a human-readable format for representing structured data, using key-value pairs and arrays. It's like receiving a neatly organized list of items rather than a jumbled mess. Claude Code can then easily parse and work with this JSON data.

Example: Getting Telegram messages

Let's say you want to retrieve messages sent to your Telegram bot. You'll use the Telegram Bot API, which has a specific endpoint (URL) for getting updates.

Task: Ask Claude Code to construct the API URL for retrieving Telegram bot updates and then open it in your browser.

1. Ask Claude Code to build the URL:

Claude Code will generate a URL that looks something like this (your token will be different):
`https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`

2. Open the URL in your browser: Copy the generated URL and paste it into your web browser's address bar.

3. Observe the initial response: You'll likely see a response similar to {"ok":true,"result":[]}. This means the API call was successful ("ok":true), but there are no new messages ("result":[]).

4. Send messages to your bot: Open Telegram and send a few messages to your bot.

5. Refresh the browser page: Go back to your browser tab with the API URL and refresh the page.

You should now see your messages appear within the JSON structure. It might look complex at first, but you'll find your message text embedded within the text field of one of the message objects. This raw JSON is what Claude Code can then process.

Common mistakes

• Incorrect token: If your token is wrong or missing, the API request will fail, often returning an error message like "Unauthorized" or "Bad Request." Double-check that you're using the correct token from your .env file.
• Misunderstanding JSON structure: The JSON returned by APIs can be nested and complex. Don't expect to see just your message text directly. You'll need to navigate through the JSON object to find the specific data points you need. Claude Code is good at this, but it helps to understand the general structure.
• Forgetting to refresh: When testing in a browser, new messages won't appear until you refresh the page, as the browser only makes the API call once.

Key takeaways

• APIs allow software applications to communicate and exchange data with external services.
• A token is a digital key used for authentication when making API requests.
• API responses are often formatted as JSON, a structured, human-readable data format.
• You can retrieve data from services like Telegram by constructing a specific API URL with your token.
• Claude Code can generate and execute these API calls, then process the returned JSON data.