echo-ai

连接到 Echo AI — 客户互动平台。列出助手、检索知识库，并与由企业和创作者构建的人工智能驱动的 Echos 聊天。在 https://echoai.so 获取 API 密钥

# Echo AI

Connect your agent to [Echo AI](https://echoai.so) — a platform where businesses and creators build AI-powered assistants (called Echos) for sales, support, and customer engagement.

With this skill, your agent can discover Echos, read their knowledge bases, and have conversations with them.

## Get started

1. Sign up at [echoai.so](https://echoai.so) (free tier available)
2. Create your first Echo or browse existing ones
3. Go to Settings → API Keys and generate a key
4. Set the environment variable `ECHO_API_KEY` to your key

## What this skill can do

### 1. List available Echos (free, no credits)

Discover which AI assistants are available under your API key.

```
GET https://auth.echoai.so/functions/v1/api/assistants
Header: X-API-Key: $ECHO_API_KEY
```

Response:
```json
{
  "assistants": [
    {
      "id": "uuid",
      "name": "Sales Assistant",
      "bio": "I help qualify leads and answer product questions",
      "slug": "sales-assistant",
      "avatar_url": "https://...",
      "tone": "professional",
      "style": "concise",
      "topics": ["pricing", "features", "onboarding"]
    }
  ]
}
```

### 2. Get Echo details and knowledge base (free, no credits)

Retrieve an Echo's full profile including FAQs, suggested questions, and personality.

```
GET https://auth.echoai.so/functions/v1/api/assistant/{id}
Header: X-API-Key: $ECHO_API_KEY
```

Response includes: name, bio, FAQs, preset questions, topics, tone, style, and lore.

**If the user's question can be answered from FAQs, answer directly — no chat call needed.**

### 3. Chat with an Echo (costs credits)

Send a message and get a response from the Echo's AI.

```
POST https://auth.echoai.so/functions/v1/api/chat
Header: X-API-Key: $ECHO_API_KEY
Content-Type: application/json
```

Request:
```json
{
  "message": "What pricing plans do you offer?",
  "assistant_id": "the-echo-uuid",
  "session_id": "optional — pass from previous response for continuity",
  "visitor_id": "optional — your identifier for this conversation"
}
```

Response:
```json
{
  "response": "We offer three plans: Starter at $29/mo, Pro at $79/mo...",
  "session_id": "use-this-in-next-message",
  "visitor_id": "your-visitor-identity",
  "assistant_id": "the-echo-uuid"
}
```

**Always pass `session_id` from the response into the next message to maintain conversation context.**

## Workflow

### When asked to find or list Echos:
1. Call `GET /api/assistants`
2. Present the results with name, bio, and topics
3. Ask if the user wants details on a specific one

### When asked about a specific Echo:
1. Call `GET /api/assistant/{id}`
2. Present the Echo's profile, FAQs, and suggested questions
3. If the question can be answered from FAQs, answer directly (zero cost)

### When the user wants to chat with an Echo:
1. **Warn the user**: "This will send a message to the Echo and consume the Echo owner's credits. Proceed?"
2. If confirmed, call `POST /api/chat`
3. Return the response and save the `session_id` for follow-ups

## Error handling

| Status | Meaning | Action |
|--------|---------|--------|
| 401 | API key missing or invalid | Check `ECHO_API_KEY` is set correctly |
| 402 | Echo owner out of credits | Inform the user, cannot proceed |
| 403 | Key doesn't have access to this Echo | Use correct key or request access |
| 429 | Rate limit exceeded | Wait and retry (default: 60 req/min) |
| 404 | Echo or endpoint not found | Verify the Echo ID or endpoint path |

## Important rules

- **Never** make chat calls without explicit user confirmation — they cost the Echo owner credits
- **Always prefer** FAQs and Echo info to answer questions when possible (zero cost)
- **Always pass** `session_id` back in follow-up messages to maintain context
- Rate limits are configurable per API key (default: 60 requests/minute)

## About Echo AI

Echo is a platform where anyone can create AI-powered assistants for their business. Echos can be deployed on websites, WhatsApp, Instagram, Telegram, Discord, Slack, and more. They handle sales conversations, customer support, lead qualification, and appointment booking.

Learn more: [echoai.so](https://echoai.so)

---

## 中文说明

# Echo AI

将你的智能体连接到 [Echo AI](https://echoai.so) —— 一个让企业和创作者构建 AI 驱动助手（称为 Echos）以用于销售、支持和客户互动的平台。

借助本技能，你的智能体可以发现 Echos、读取它们的知识库，并与它们对话。

## 开始

1. 在 [echoai.so](https://echoai.so) 注册（提供免费层级）
2. 创建你的第一个 Echo 或浏览现有的
3. 进入 Settings → API Keys 并生成一个密钥
4. 将环境变量 `ECHO_API_KEY` 设置为你的密钥

## 本技能可以做什么

### 1. 列出可用的 Echos（免费，不消耗额度）

发现你的 API 密钥下有哪些可用的 AI 助手。

```
GET https://auth.echoai.so/functions/v1/api/assistants
Header: X-API-Key: $ECHO_API_KEY
```

响应：
```json
{
  "assistants": [
    {
      "id": "uuid",
      "name": "Sales Assistant",
      "bio": "I help qualify leads and answer product questions",
      "slug": "sales-assistant",
      "avatar_url": "https://...",
      "tone": "professional",
      "style": "concise",
      "topics": ["pricing", "features", "onboarding"]
    }
  ]
}
```

### 2. 获取 Echo 详情和知识库（免费，不消耗额度）

检索某个 Echo 的完整资料，包括常见问题、建议问题和个性。

```
GET https://auth.echoai.so/functions/v1/api/assistant/{id}
Header: X-API-Key: $ECHO_API_KEY
```

响应包括：name、bio、FAQs、预设问题、topics、tone、style 和 lore。

**如果用户的问题可以从常见问题中得到解答，直接回答 —— 无需调用聊天。**

### 3. 与 Echo 对话（消耗额度）

发送一条消息并从 Echo 的 AI 获取回应。

```
POST https://auth.echoai.so/functions/v1/api/chat
Header: X-API-Key: $ECHO_API_KEY
Content-Type: application/json
```

请求：
```json
{
  "message": "What pricing plans do you offer?",
  "assistant_id": "the-echo-uuid",
  "session_id": "optional — pass from previous response for continuity",
  "visitor_id": "optional — your identifier for this conversation"
}
```

响应：
```json
{
  "response": "We offer three plans: Starter at $29/mo, Pro at $79/mo...",
  "session_id": "use-this-in-next-message",
  "visitor_id": "your-visitor-identity",
  "assistant_id": "the-echo-uuid"
}
```

**始终把响应中的 `session_id` 传入下一条消息，以保持对话上下文。**

## 工作流

### 当被要求查找或列出 Echos 时：
1. 调用 `GET /api/assistants`
2. 用 name、bio 和 topics 展示结果
3. 询问用户是否想了解某个具体 Echo 的详情

### 当被问及某个具体 Echo 时：
1. 调用 `GET /api/assistant/{id}`
2. 展示该 Echo 的资料、常见问题和建议问题
3. 如果问题可以从常见问题中得到解答，直接回答（零成本）

### 当用户想与某个 Echo 对话时：
1. **警告用户**："这将向该 Echo 发送一条消息并消耗 Echo 所有者的额度。是否继续？"
2. 若确认，调用 `POST /api/chat`
3. 返回响应并保存 `session_id` 以供后续跟进

## 错误处理

| 状态 | 含义 | 操作 |
|--------|---------|--------|
| 401 | API 密钥缺失或无效 | 检查 `ECHO_API_KEY` 是否设置正确 |
| 402 | Echo 所有者额度不足 | 告知用户，无法继续 |
| 403 | 密钥无权访问此 Echo | 使用正确的密钥或请求访问权限 |
| 429 | 超出速率限制 | 等待后重试（默认：60 次/分钟） |
| 404 | 未找到 Echo 或端点 | 验证 Echo ID 或端点路径 |

## 重要规则

- 未经用户明确确认，**切勿**发起聊天调用 —— 它们会消耗 Echo 所有者的额度
- **始终优先**用常见问题和 Echo 信息来回答问题（零成本）
- **始终**在后续消息中回传 `session_id` 以保持上下文
- 速率限制可按每个 API 密钥配置（默认：60 次请求/分钟）

## 关于 Echo AI

Echo 是一个让任何人都能为其业务创建 AI 驱动助手的平台。Echos 可以部署在网站、WhatsApp、Instagram、Telegram、Discord、Slack 等之上。它们处理销售对话、客户支持、线索资格审核和预约。

了解更多：[echoai.so](https://echoai.so)