geckovision/ayuda-venezuela-bot

Analysis updated 2026-05-18

★ 1TypeScriptAudience · developerComplexity · 3/5LicenseSetup · moderate

Mindmap

mindmap
  root((ayuda-venezuela-bot))
    What it does
      Emergency shelter info
      Water safety
      Humanitarian aid
      Spanish conversation
    Architecture
      Telegram bot
      AI agent
      surfcall layer
      SOS Venezuela API
    Deployment
      Docker bot
      Vercel landing page
      CI via GitHub Actions
    Development
      Offline test mode
      Multi-provider LLM
      OpenAPI spec included

mindmap root((ayuda-venezuela-bot)) What it does Emergency shelter info Water safety Humanitarian aid Spanish conversation Architecture Telegram bot AI agent surfcall layer SOS Venezuela API Deployment Docker bot Vercel landing page CI via GitHub Actions Development Offline test mode Multi-provider LLM OpenAPI spec included

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Deploy a Telegram bot that answers emergency questions in Spanish using real data from the SOS Venezuela 2026 API.

USE CASE 2

Run the bot in offline recorded mode to develop and test locally without API costs or network calls.

USE CASE 3

Use the included OpenAPI spec for SOS Venezuela 2026 to build a different tool on top of the same data source.

USE CASE 4

Adapt the surfcall-based agent pattern to connect any OpenAPI-described data source to a Telegram bot.

What is it built with?

PythonTypeScriptNext.jsTelegram Bot APIDockerAnthropic API

How does it compare?

	geckovision/ayuda-venezuela-bot	abidoo22/pixelorama-mcp	aditya-pandey/slate
Stars	1	1	1
Language	TypeScript	TypeScript	TypeScript
Setup difficulty	moderate	moderate	easy
Complexity	3/5	3/5	2/5
Audience	developer	vibe coder	general

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires a Telegram bot token from BotFather and an AI provider API key, Anthropic Haiku recommended for production use.

MIT license: use, modify, and distribute freely for any purpose, including commercial use, as long as you keep the copyright notice.

In plain English

This is a Telegram bot built for the Build4Venezuela 2026 hackathon in response to the June 2026 earthquakes in Venezuela. It gives people in Venezuela real-time information about emergency shelters, drinking water safety, health resources, and humanitarian aid, all through a conversation in Spanish, with no app to download and no registration required. The bot works as an AI agent: when a user sends a question in Spanish, the agent calls the SOS Venezuela 2026 API to retrieve real data, then returns a clear answer. The integration layer, which the team calls surfcall, reads the API's structure and generates the correct API calls automatically, so the bot answers with actual information rather than guessing. Surfcall acts only as a coordination layer and does not store any messages or API response content. The repository contains two separate parts. The first is the Telegram bot itself, written in Python and deployable via Docker. It supports multiple AI providers including Anthropic and OpenRouter, and includes an offline mode that lets you run the bot and its tests without spending any API credits. The second part is a Next.js landing page that deploys to Vercel and is available in both Spanish and English. To run the bot, you need a Telegram bot token from Telegram's official bot setup tool and an API key from a supported AI provider. The recommended configuration uses Anthropic's Haiku model, which the README describes as reliable and inexpensive. All tests can run offline with no network calls and no credentials. The project also includes an OpenAPI specification for the SOS Venezuela 2026 API, contributed so that other developers can build additional tools on top of the same data source. The bot is MIT-licensed.

Copy-paste prompts

Prompt 1

I want to run ayuda-venezuela-bot locally. Walk me through setting up the .env file with a Telegram bot token and Anthropic API key, then starting the bot with uv.

Prompt 2

How does surfcall work inside ayuda-venezuela-bot? Explain how it reads the SOS Venezuela OpenAPI spec and generates the right API calls without custom integration code.

Prompt 3

I want to run the bot's test suite without spending any API credits. How do I use SOSBOT_MODE=recorded and what does it actually simulate?

Prompt 4

I have a different emergency data API with an OpenAPI spec. How would I adapt ayuda-venezuela-bot to use my API instead of SOS Venezuela 2026?

Frequently asked questions

What is ayuda-venezuela-bot?

A Spanish-language Telegram bot that gives Venezuelans real-time emergency information about shelters, water, and aid by querying the SOS Venezuela 2026 API.

What language is ayuda-venezuela-bot written in?

Mainly TypeScript. The stack also includes Python, TypeScript, Next.js.

What license does ayuda-venezuela-bot use?

MIT license: use, modify, and distribute freely for any purpose, including commercial use, as long as you keep the copyright notice.

How hard is ayuda-venezuela-bot to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is ayuda-venezuela-bot for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub geckovision on gitmyhub

Verify against the repo before relying on details.