# VoxAgent Quickstart

Official website: https://vox-ai.teddymobile.cn/

This file is a public, AI-readable quickstart for teams that want to understand VoxAgent outbound calls, custom bots, and HTTP POST + SSE conversation flow.

## Goal

Use the shortest path to understand the VoxAgent integration flow:

- Register or prepare an organization entry.
- Apply for a trial or sandbox environment.
- Review the public outbound call request shape.
- Understand notification bots, custom bots, and voiceType selection.
- Configure an HTTPS POST endpoint that returns text/event-stream responses.
- Continue to the full API documentation for outbound call, HMAC authentication, custom bot payloads, and SSE details.

## Who This Is For

This quickstart is for teams that already have one or more of the following:

- A text-based AI Agent.
- A business backend service.
- An HTTPS service that can respond with text/event-stream.
- A phone use case such as sales follow-up, customer service, medical follow-up, education, or professional consultation.

## Step 1: Register And Verify Contact Identity

Create the organization entry and verify the responsible contact email. This ensures later trial resources, KYC information, launch review, and operational notifications can be attached to the correct organization.

Human page: https://vox-ai.teddymobile.cn/register

## Step 2: Apply For Trial And Sandbox Resources

Submit the scenario, expected usage, and region information. The current MVP flow can return tenant-level shared appId / secret information and attach sandbox resources to the default project.

Human page: https://vox-ai.teddymobile.cn/trial/apply

Typical information to prepare:

- Business scenario.
- Expected call volume.
- Region or market.
- Responsible contact.
- SSE endpoint or backend readiness.

## Step 3: Configure An SSE Conversation Endpoint

Expose an HTTPS POST endpoint from your server. Vox sends each conversation turn with fields such as `turn`, `callid`, `requestid`, and `message`; your service responds with `text/event-stream` chunks and finishes the turn with `data: [DONE]`.

Minimal Node.js example:

```js
import express from 'express';

const app = express();
app.use(express.json());

app.post('/developer-api', async (req, res) => {
  const { requestid, message, turn } = req.body;

  console.log('Vox turn:', turn, 'user message:', message);

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  const chunk = JSON.stringify({
    id: requestid,
    created: Math.floor(Date.now() / 1000),
    message: 'Hello, I can help with the next step.',
  });
  res.write('data: ' + chunk + '\n\n');
  res.write('data: [DONE]\n\n');
  res.end();
});

app.listen(3001);
```

## Step 4: Validate The Outbound And SSE Flow

Use the demo, sandbox path, or API documentation to confirm the outbound payload shape and SSE response behavior before connecting full business logic.

Human page: https://vox-ai.teddymobile.cn/demo

Recommended validation points:

- The SSE endpoint is reachable over HTTPS.
- Outbound requests include `appId`, `callee`, `requestId`, and the correct `botid` or `botType=custom` payload.
- `extra.notification`, `extra.agent_profile`, and `extra.voiceType` are shaped according to the public API docs.
- SSE response chunks include `id`, `created`, and non-empty `message`.
- Each turn ends with `data: [DONE]`.

## Environment Variables

Example variable names:

```txt
VOXAGENT_APP_ID=your_app_id
VOXAGENT_SECRET=your_secret
VOXAGENT_WEBHOOK_SECRET=your_webhook_secret
VOXAGENT_BASE_URL=https://api.example.com
APP_BASE_URL=https://your-app.example.com
```

Do not put real production secrets in public code, prompts, screenshots, or AI chat windows.

## Next Documents

- Concepts: https://vox-ai.teddymobile.cn/concepts.md
- API reference page: https://vox-ai.teddymobile.cn/api-reference
- Full API markdown: https://vox-ai.teddymobile.cn/docs.md
- Full API metadata: https://vox-ai.teddymobile.cn/docs.json
- FAQ: https://vox-ai.teddymobile.cn/faq.md