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.

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.

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

✓ Now you have $SETUP_ID.

GETGet your account

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.

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.

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.

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"

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.

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.

5. Place a call

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

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.

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.

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"