API docs by Redocly

TelAPI (edge)

Download OpenAPI specification:

TelAPI issues SDK session tokens, exposes endpoint runtime capabilities, receives provider webhooks under /api/v1/webhooks, and hosts the /ws/session WebSocket channel. Authenticated REST endpoints require a team API key in the X-API-Key header with the documented scope for each operation.

Endpoints

Team endpoint discovery using team API keys

List team endpoints

Returns all endpoints belonging to the team associated with the API key. Requires a team API key with READ_TEAM_APPS scope.

Authorizations:
apiKey
query Parameters
page
string^[1-9][0-9]*$
Default: "1"
Example: page=1

Page number (1-based)

limit
string^[1-9][0-9]*$
Default: "20"
Example: limit=20

Items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "endpoints": [
    ],
  • "pagination": {
    }
}

Health

GET /health — minimal probe (Redis); detail via OpenTelemetry

Service health

Returns 200 when required dependencies (Redis) are reachable; otherwise 503. Minimal body — monitor detail via OpenTelemetry.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Runtime

Runtime capability discovery for SDK clients

Discover endpoint runtime capabilities

Returns the interaction modes, transport preferences, flow entry points, and browser actions the SDK can use for an endpoint. Requires a team API key with CREATE_CALL_TOKEN scope.

Authorizations:
apiKey
query Parameters
endpointId
required
string <uuid>
Example: endpointId=0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f

Endpoint to inspect. Must belong to the API key team.

Responses

Response samples

Content type
application/json
{
  • "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
  • "flowDefinitionId": "7e0dca65-b70b-461e-9d12-c18e0ab6e626",
  • "runtime": {
    },
  • "interactionModes": {
    },
  • "transports": {
    },
  • "flows": {
    }
}

Sessions

Session-token issuance for text, audio playback, voice, and browser-action SDK modes

Request a session token

Issues a runtime session id and a short-lived WebSocket token for the requested SDK mode.

After this call, connect the browser SDK to: /ws/session?sessionId={sessionId}&token={wsToken}

WebSocket wire format:

  • Messages use the ChannelMessage envelope (see components.schemas.ChannelMessage).
  • The server sends an initial status message with state=connected.

WebSocket close codes:

  • 4001 — missing sessionId or token
  • 4003 — invalid token or expired session
  • 4000 — superseded by a newer connection
  • 4500 — internal server error

Authentication: requires a team API key with CREATE_CALL_TOKEN scope.

voice_conversation responses also include WebRTC gateway metadata (telproDomain, webrtcGatewayUrl).

Authorizations:
apiKey
Request Body schema: application/json
required
endpointId
required
string <uuid>

Endpoint to open a session against. It must belong to the API key team.

mode
required
string
Enum: "text" "audio_playback" "voice_conversation" "browser_actions" "listen"

Session mode to provision: text chat, browser TTS playback, WebRTC voice, browser action dispatch, or interpretation listening.

Responses

Request samples

Content type
application/json
Example
{
  • "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
  • "mode": "text"
}

Response samples

Content type
application/json
Example
{
  • "sessionId": "call-loc5q7g0-k7p3f9x2",
  • "wsToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "wsTokenExpiresIn": 300,
  • "expiresIn": 3600
}

Webhooks

Webhook receivers

Receive TOBi chatbot callback

Receives message callbacks from Vodafone TOBi chatbot and forwards to TelPhi. Trace context (traceId, parentSpanId, callId) can be passed via query parameters for distributed tracing correlation. Each callback must include the per-conversation callback token in the token header.

path Parameters
channelId
required
string

The channel ID this callback belongs to (TOBi conversation ID)

query Parameters
traceId
string^[a-fA-F0-9]{32}$

Trace ID for distributed tracing (32-char hex)

parentSpanId
string^[a-fA-F0-9]{16}$

Parent span ID for distributed tracing (16-char hex)

callId
string

Call ID from voiceai:calls: for correlation

header Parameters
token
string
Example: <token>

Per-conversation TOBi callback token. Vodafone submits this as the literal token header value.

Request Body schema: application/json
required

Vodafone TOBi callback payload. TelAPI requires conversation.identifier.id so the response can be correlated to the TOBi channel.

object
object
object
object

Provider metadata forwarded to TelPhi as JSON.

Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "conversation": {
    },
  • "messages": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "received": true,
  • "streamId": "1778022191343-0"
}