API docs by Redocly

TelAPI (0.9.14-patch1)

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
}

Upgrade a text session to voice

Serialises the active TelAPI text FlowEngine session to Redis, then re-issues a voice_conversation token for the same sessionId so TelPhi can resume conversation context when the WebRTC leg connects.

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

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "endpointId": "c8d2c7e1-e4b1-4108-9e29-3429a36a1ef3"
}

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "wsToken": "string",
  • "wsTokenExpiresIn": 0,
  • "expiresIn": 0,
  • "telproDomain": "string",
  • "webrtcGatewayUrl": "string",
  • "traceId": "string",
  • "spanId": "string"
}

Downgrade a voice session back to text

After the WebRTC leg ends, re-issues a text session token for the same sessionId so TelAPI can resume chat with persisted conversation history.

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

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "endpointId": "c8d2c7e1-e4b1-4108-9e29-3429a36a1ef3"
}

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "wsToken": "string",
  • "wsTokenExpiresIn": 0,
  • "expiresIn": 0,
  • "traceId": "string",
  • "spanId": "string"
}

Webhooks

Webhook receivers

Receive TOBi chatbot callback

Receives message callbacks from a TOBi chatbot and forwards them to TelPhi. Call/trace correlation is loaded from the Redis callback session written by TelPhi. The callback URL only needs ?token=; legacy trace/call query params are ignored when a session exists. 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
token
string

Optional legacy auth token echo from Vodafone callback URLs. Prefer the token header.

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

TOBi callback payload sent by Vodafone (SendMessageResponse). TelAPI requires conversation.identifier.id so the callback can be correlated to the TOBi channel.

object
object
object
object

Legacy provider metadata. Vodafone recommends channelData instead, but TelAPI forwards metadata when present.

Array of objects

Outgoing channel data returned by TOBi on callbacks (Vodafone OutgoingChannelData). This is bot-to-platform context such as scenario flags or routing hints.

Do not confuse this with Delphi inbound channel-data forwarding configured in TelWeb (Flow Builder → channelDataRules), which maps SIP INVITE headers into channelData on create-conversation requests sent to TOBi. Callback channelData travels in the opposite direction and is forwarded opaquely on the TelPhi Redis stream for observability.

object

Responses

Request samples

Content type
application/json
Example

Spoken or written bot content only. TelAPI extracts text from messages and forwards it to TelPhi.

{
  • "conversation": {
    },
  • "messages": {
    },
  • "channelData": [
    ],
  • "metadata": {
    }
}

Response samples

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