# Getting started

Each step saves a value the next one uses — keep the shell open. The requests use `curl` and `jq`; if a value comes back empty or `null`, the request before it failed, so rerun that one without `-s` to see why.

## 0. Get an access token

Authenticate with an access token. Copy it from the Developers page of the Botnoi Voice console and send it on every request as `Authorization: Bearer <access_token>`. Read it into your shell without echoing it or leaving it in your history: paste it, then press Enter.

Treat it like a password. It does not expire, it can act on everything in your account, and you cannot revoke it yourself yet. Keep it out of source control and client-side code. Self-service API keys you can issue and revoke are coming.

```bash
read -rs TOKEN && export TOKEN
```

Now you have `$TOKEN`.

## 1. Find your setup ID

Your account's `_id` is your setup ID, the value every Telephony setup and call request takes.

```bash
export SETUP_ID=$(curl -s https://api-voicebot-stg.botnoigroup.com/me -H "Authorization: Bearer $TOKEN" | jq -r ._id)
```

Now you have `$SETUP_ID`.

- [Get your account](/docs/get-me)

## 2. Create an agent

This creates the agent, or updates it when it already exists. Catalog lists the speech-to-text and text-to-speech providers to pick from.

```bash
export AGENT_ID=$(curl -s -X PUT https://api-voicebot-stg.botnoigroup.com/agent/create_update_agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "bot_name": "front-desk" }' | jq -r .bot_info.agent_id)
```

Now you have `$AGENT_ID`.

- [Create or update an agent](/docs/put-agent-create_update_agent)
- [List speech-to-text providers](/docs/get-info-asr_providers)
- [List text-to-speech providers](/docs/get-info-get_tts_providers)

## 3. Create your Telephony setup

This registers your trunk and turns the service on. `outbound` turns on calling out, which step 5 uses; send `null` for an inbound-only setup. A Fixed IP trunk is the other shape: see the examples on Create your Telephony setup. Then check that the trunk registered.

```bash
curl -s -X PUT https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bot": {},
  "pbx": {
    "mode": "register",
    "transport": "udp",
    "address": "pbx.example.com:5060",
    "source_ips": [],
    "auth": {
      "username": "acme-trunk",
      "password": "<trunk password>",
      "registrar": "pbx.example.com:5060"
    }
  },
  "transfer_targets": {},
  "outbound": {
    "enabled": true,
    "default_path": "pbx"
  },
  "inbound": {}
}'

curl -s https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID/trunk/status \
  -H "Authorization: Bearer $TOKEN"
```

- [Create your Telephony setup](/docs/put-v1-provisioning-tenants-tenant_id)
- [Get trunk status](/docs/get-v1-provisioning-tenants-tenant_id-trunk-status)

## 4. Get a number and bind your agent

Assign yourself a number, then bind your agent to it. Call this number now; your agent answers.

```bash
export DID=$(curl -s -X POST https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID/dids/assign \
  -H "Authorization: Bearer $TOKEN" | jq -r .canonical_did)

curl -s -X PUT https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID/dids/$DID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "'"$AGENT_ID"'" }'
```

Now you have `$DID`.

- [Assign a number](/docs/post-v1-provisioning-tenants-tenant_id-dids-assign)
- [Bind a number to an agent](/docs/put-v1-provisioning-tenants-tenant_id-dids-did)

## 5. Place a call

Have your agent call a phone number, then read the call's status.

```bash
export CALL_ID=$(curl -s -X POST https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID/calls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "<phone number to call>", "agent_id": "'"$AGENT_ID"'" }' | jq -r .call_id)

curl -s https://api-voicebot-stg.botnoigroup.com/v1/provisioning/tenants/$SETUP_ID/calls/$CALL_ID \
  -H "Authorization: Bearer $TOKEN"
```

Now you have `$CALL_ID`.

- [Place a call through your trunk](/docs/post-v1-provisioning-tenants-tenant_id-calls)
- [Get a call's status](/docs/get-v1-provisioning-tenants-tenant_id-calls-call_id)

## 6. See what happened

List today's call logs for your agent, then read one with the `file_path` from the list. Dates are Bangkok calendar days as `YYYY/MM/DD`, and both ends are included; leave them out and the list covers a fixed default window instead. Both paths keep their trailing slash.

```bash
export TODAY=$(TZ=Asia/Bangkok date +%Y/%m/%d)

curl -s "https://api-voicebot-stg.botnoigroup.com/logs/list_file/?agent_id=$AGENT_ID&start_date=$TODAY&end_date=$TODAY" \
  -H "Authorization: Bearer $TOKEN"

curl -s -G "https://api-voicebot-stg.botnoigroup.com/logs/read_log/" \
  --data-urlencode "file_path=<file_path from the list>" \
  -H "Authorization: Bearer $TOKEN"
```

- [List conversation files](/docs/get-logs-list_file)
- [Read a conversation transcript](/docs/get-logs-read_log)