Run your first conversation turn

#!/usr/bin/env bash
# Recipe: first-conversation-turn
#
# Runs a real conversation against a Voiceflow agent over the REST API: launch
# it, then send a user message, reading the traces returned at each step.
#
# Required environment:
#   VF_PAT         personal access token (Settings -> Access tokens), vfp_..._...
#   VF_PROJECT_ID  the project ID (Settings -> General -> Metadata)
set -euo pipefail

: "${VF_PAT:?set VF_PAT to a personal access token from Settings -> Access tokens}"
: "${VF_PROJECT_ID:?set VF_PROJECT_ID to the project ID}"

BASE="https://realtime-api.voiceflow.com/v1/stable"
ENVIRONMENT="${VF_ENVIRONMENT:-main}"

# A conversation is identified by the userID in the path. There is no separate
# session to create: the first call starts one, and later calls with the same
# userID continue it.
USER_ID="cookbook-$(date +%s)"

# The runtime can emit raw control characters inside trace payload strings,
# which strict JSON parsers reject. Strip them before jq.
json() { tr -d '\000-\037'; }

# The runner keys on this prefix to tell a product change (exit 20) from a
# broken script (exit 30). Always route step failures through it.
fail() { echo "FAIL at $1" >&2; exit 1; }

send() {
  curl -sf -X PUT "$BASE/conversation/$USER_ID?projectID=$VF_PROJECT_ID&environmentAlias=$ENVIRONMENT" \
    -H "Authorization: Bearer $VF_PAT" \
    -H "Content-Type: application/json" \
    -d "$1"
}

# 1. Launch the conversation. `version` selects the draft or the published
#    build of the environment, so the same call can exercise either.
LAUNCH=$(send '{ "action": { "type": "launch" }, "version": "published" }') \
  || fail "launch the conversation (a 401 here means the token is wrong or expired; a 400 saying 'invalid environment tag' means the environmentAlias does not exist on this project)"
printf '%s' "$LAUNCH" | json | jq -e '.traces | length > 0' > /dev/null \
  || fail "launch returned no traces"

# 2. Send a user message to the SAME userID. The agent picks up where the
#    launch left off - nothing needs to be threaded through by hand.
REPLY=$(send '{ "action": { "type": "text", "payload": "What can you help me with?" }, "version": "published" }') \
  || fail "send a user message"
printf '%s' "$REPLY" | json | jq -e '.traces | length > 0' > /dev/null \
  || fail "reply returned no traces"

# 3. The agent's words arrive as `text` traces. Assert one came back, so the
#    recipe proves a real answer rather than just a 200.
printf '%s' "$REPLY" | json | jq -e '[.traces[] | select(.type == "text")] | length > 0' > /dev/null \
  || fail "reply contained no text trace (a voice agent answers with speak instead)"

echo "ok: launch returned $(printf '%s' "$LAUNCH" | json | jq '.traces | length') trace(s), reply returned $(printf '%s' "$REPLY" | json | jq '.traces | length') trace(s), types: $(printf '%s' "$REPLY" | json | jq -c '[.traces[].type] | unique')"