Session events

When you build your own client, the conversation runs between the visitor's browser and the voice provider. Send session events so the console can show the session's length, transcript and errors, the same as for the VoisX widget.

Send session events

POST/widget/v1/analytics

Records one or more events for a session. You can send several events in one request.

Requires the widget:read permission.

Headers

X-API-Keystringrequired

Your project API key.

Body

session_idstringrequired

The session_id from Start a session.

agent_idintegerrequired

The agent the session is with.

eventsarrayrequired

The events to record.

events[].typestringrequired

The event type. See the table below.

events[].timestampstringrequired

When the event happened, in ISO 8601.

events[].dataobjectoptional

Extra details for the event type.

Event types

type	data fields	What it records
session_start	visitor_id (optional)	The session started.
session_end	duration_seconds (number)	The session ended and how long it lasted.
transcript	transcript_data (array of turns)	The conversation. Each turn has role (user or assistant), text and timestamp.
message	message (string)	One message in the conversation, for the session log.
error	error_type, message	An error your client hit.
tool_call_made	none	The agent asked for a tool.
tool_call_success	none	A tool call succeeded.

Unknown types are accepted and ignored. Tool calls you run through POST /widget/v1/tools/execute are already counted, so you do not need to send tool_call_made or tool_call_success for them.

tip

Send the transcript event once, with the full conversation, when the session ends. VoisX analyses each transcript it receives to work out the session's outcome, so sending it more than once can repeat that work.

Response fields

successbooleanoptional

Always true when the request was accepted.

receivedintegeroptional

How many events were in the request.

persistedintegeroptional

How many events were recorded. An event that cannot be recorded is skipped and does not fail the request.

Responses

200

The events were received.

401

The key is invalid, revoked, lacks widget:read, or is not allowed from this domain.

403

The key cannot use this agent, or the agent is in another project.

404

The agent was not found.

422

A required field is missing or has the wrong type.

429

The key's rate limit was reached.

cURL

curl -X POST https://in.api.voisx.ai/widget/v1/analytics \
  -H "X-API-Key: $VOISX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "6f1c2a9e-3b7d-4e2a-9c51-0d8e4f7a1b23",
    "agent_id": 2210,
    "events": [
      {
        "type": "transcript",
        "timestamp": "2026-10-05T09:14:02Z",
        "data": {
          "transcript_data": [
            { "role": "assistant", "text": "Hi, how can I help?", "timestamp": "2026-10-05T09:12:10Z" },
            { "role": "user", "text": "When do you open?", "timestamp": "2026-10-05T09:12:14Z" }
          ]
        }
      },
      {
        "type": "session_end",
        "timestamp": "2026-10-05T09:14:02Z",
        "data": { "duration_seconds": 112 }
      }
    ]
  }'

Node.js

await fetch("https://in.api.voisx.ai/widget/v1/analytics", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.VOISX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session_id: session.session_id,
    agent_id: 2210,
    events: [
      {
        type: "session_end",
        timestamp: new Date().toISOString(),
        data: { duration_seconds: 112 },
      },
    ],
  }),
});

Python

import os
from datetime import datetime, timezone
import requests

requests.post(
    "https://in.api.voisx.ai/widget/v1/analytics",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
    json={
        "session_id": session_id,
        "agent_id": 2210,
        "events": [
            {
                "type": "session_end",
                "timestamp": datetime.now(timezone.utc).isoformat(),
                "data": {"duration_seconds": 112},
            }
        ],
    },
)

200 OK

{
  "success": true,
  "received": 2,
  "persisted": 2
}