Integrate Soarenity's automation, AI, and avatar into your app or site in minutes.
Questions? support@soarenity.ai
X-API-Key header.blue_action_listener.js (template), blue_knowledge.py, blue_app.py, gpt_service.py, elevenlabs_service.py, and blue_memory.py.
blue_action_listener.js in your frontend/scripts directory.blue_action_listener.js should be customized for your UI/flow; all other files are drop-in ready./soarenity_action endpoint in your backend.blue_action_listener.js and handle actions triggered by Blue.{"action":"some_action","parameters":{ }}{"status":"success"}Main endpoint for all automations, questions, and avatar interactions.
Request:POST /api/blue_v1
Headers:
X-API-Key: YOUR_API_KEY
Body:
{
"text": "Show me my orders",
"device_id": "USER_DEVICE_OR_SESSION_ID"
}device_id can be any string unique to the user/session/device. All state (memory, context) is scoped to this value.
Returns: JSON with these fields:
{
"response": "Here are your recent orders...",
"audio_url": "/static/audio/blue_tts_xxxx.mp3",
"avatar_state": "talking",
"next_action": {
"method": "GET",
"endpoint": "/user/orders",
"params": {}
},
"pending_action": {
"action": "refund_order",
"parameters": { }
}
}
- If pending_action is present, send the user's followup message and this entire object back in your next request to continue.
- If next_action is present, trigger automation via your own backend or via /soarenity_action.
This is your backend POST endpoint for Blue to trigger custom actions you have defined in your API Dashboard.
Blue will POST to this endpoint with:
{"action": "action_name", "parameters": { }}Complete Example Implementation:
@app.route("/soarenity_action", methods=["POST"])
def soarenity_action():
import sys
print("\n--- /soarenity_action CALLED ---", file=sys.stderr)
try:
data = request.get_json(force=True)
print("[soarenity_action] Received data:", data, file=sys.stderr)
except Exception as ex:
print("[soarenity_action] Failed to parse JSON:", ex, file=sys.stderr)
return jsonify({"error": "Failed to parse JSON", "detail": str(ex)}), 400
method = (data.get("method") or "GET").upper()
endpoint = data.get("endpoint") or "/"
# Defensive: Always ensure params is a dict, not None
params = data.get("params")
if params is None:
params = {}
print(f"[soarenity_action] method={method} endpoint={endpoint} params={params}", file=sys.stderr)
# Defensive: Make sure endpoint is a string
if not isinstance(endpoint, str):
print("[soarenity_action] ERROR: Endpoint is not a string", file=sys.stderr)
return jsonify({"error": "Invalid endpoint"}), 400
# Navigation action: GET with endpoint starting with "/" and NO params (fix: handle both None and empty dict)
if method == "GET" and endpoint.startswith("/") and (not params or params == {}):
print(f"[soarenity_action] Navigation detected: navigate to {endpoint}", file=sys.stderr)
return jsonify({"navigate": endpoint})
# External URL navigation (http/https)
if method == "GET" and endpoint.startswith("http"):
print(f"[soarenity_action] External navigation detected: navigate to {endpoint}", file=sys.stderr)
return jsonify({"navigate": endpoint})
# --- MAIN FIX: Convert local endpoints to full URLs ---
if endpoint.startswith("/"):
full_endpoint = request.host_url.rstrip("/") + endpoint
print(f"[soarenity_action] Converted local endpoint to full URL: {full_endpoint}", file=sys.stderr)
endpoint = full_endpoint
# Backend HTTP actions (supports GET, POST, PUT, DELETE, PATCH)
try:
import requests
print(f"[soarenity_action] Performing backend HTTP {method} to {endpoint}...", file=sys.stderr)
if method == "GET":
resp = requests.get(endpoint, params=params, timeout=12)
elif method == "POST":
resp = requests.post(endpoint, json=params, timeout=12)
elif method == "PUT":
resp = requests.put(endpoint, json=params, timeout=12)
elif method == "DELETE":
resp = requests.delete(endpoint, json=params, timeout=12)
elif method == "PATCH":
resp = requests.patch(endpoint, json=params, timeout=12)
else:
print(f"[soarenity_action] ERROR: Unsupported method {method}", file=sys.stderr)
return jsonify({"error": f"Unsupported method: {method}"}), 400
print(f"[soarenity_action] Response status: {resp.status_code}", file=sys.stderr)
try:
result = resp.json()
print(f"[soarenity_action] JSON result: {result}", file=sys.stderr)
return jsonify(result), resp.status_code
except Exception as ex:
print(f"[soarenity_action] Non-JSON result, sending raw text. Exception: {ex}", file=sys.stderr)
return jsonify({"raw_body": resp.text}), resp.status_code
except Exception as ex:
print(f"[soarenity_action] EXCEPTION in HTTP call: {ex}", file=sys.stderr)
return jsonify({"error": str(ex)}), 500
pending_action and a clarification response.pending_action in the next request.X-API-Key header.
blue_action_listener.js should be treated as drop-in. Only update if you need to add new backend actions or change the frontend UI.
blue_action_listener.js for integration hooks, example event handling, and how to wire up to your UI.
POST /api/blue_v1
Headers:
X-API-Key: YOUR_API_KEY
Body:
{
"text": "How do I track my order?",
"device_id": "DEVICE_OR_SESSION_ID"
}
device_id is required on every request.pending_action if more info is needed.For help, API keys, dashboard setup, or advanced use cases, contact our team.
