API docs by Redocly

TelAPI (0.9.17-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"
}

Aggregated SIP trunk health

Returns per-trunk health for all voice servers from Redis heartbeats plus DB fallback. Requires an internal API token with the read:trunk_health permission.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "generatedAt": "2019-08-24T14:15:22Z",
  • "count": 0,
  • "servers": [
    ]
}

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. Each callback must include the per-conversation callback token in the token header. A ?token= query echo is legacy only and is not sufficient by itself. Legacy trace/call query params are ignored when a Redis callback session exists.

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.

traceId
string
parentSpanId
string
callId
string
header Parameters
token
required
string
Example: <token>

Required. Per-conversation TOBi callback token. Vodafone must send this as the literal token header value (not Bearer, not only a query parameter).

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

Sender identity of the callback (bot user). Accepted for TOBi API compatibility; currently not used by Delphi.

object
object

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

expectAnotherBotMessage
boolean

Top-level AudioCodes continuation hint. true means another bot message is expected; false means this response completes the bot turn.

object

Session parameters at the body root. Only expectAnotherBotMessage is evaluated here; dynamic call-configuration changes (DTMF, STT/TTS, barge-in, …) must be sent as a config custom event instead.

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 and application metadata attributes), which maps carrier SIP INVITE headers into channelData on create-conversation requests sent to TOBi. Internal Delphi headers (X-Trace-ID, X-Span-ID, X-VGW-IpTelpro, X-Delphi-*, etc.) are stripped before header forwarding. Callback channelData travels in the opposite direction. The case-insensitive sensitiveInfoOnStorage key updates sticky per-call storage protection; when duplicate keys are present the last entry is authoritative. A config custom event in the same callback overrides channelData. Other entries remain available on the TelPhi Redis stream.

object

NLU analysis (intents, entities, sentiment) from the bot. Delphi does not interpret this data; it is forwarded unmodified on the internal message stream for downstream consumers.

eventName
string

SeeTest alias for a top-level control event name (hangup, transfer). Prefer messages[].content.event.custom.

name
string

Canonical top-level control event name. Same meaning as eventName.

object

SeeTest alias for the control-event value (headers, reasons). Merged into the hangup/transfer command.

object

Canonical top-level control-event value. Same meaning as input.

handoverReason
string

Optional hangup/transfer reason when the control event is sent at the body root. Blank or omitted uses the Flow Designer default.

hangupReason
string

Alias for handoverReason on a top-level hangup event.

Array of objects

BYE headers when the hangup event is sent at the body root.

Array of objects or objects

Managed callback actions array. Each item is { name, value } or { eventName, input }.

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"
}

Usage

Aggregated team-level usage reports (TTS character ingestion, etc.)

Get total TTS character consumption for the calling team

Returns the aggregated TTS character ingestion (total, cached, generated, cache-hit ratio) for the team that owns the API key, within the requested [from, to] window. Apps that are excluded from the dashboard are not included in the aggregation. Requires a team API key with the READ_TEAM_USAGE scope.

Authorizations:
apiKey
query Parameters
from
string <date-time>

Start of the report window (ISO 8601). Defaults to epoch if both from and to are omitted.

to
string <date-time>

End of the report window (ISO 8601). Defaults to "now" if both from and to are omitted.

timeframe
string
Default: "total"
Enum: "day" "week" "month" "total"

Timeframe label echoed in the response (does not change aggregation; informational).

Responses

Response samples

Content type
application/json
{
  • "teamId": "5e2c1f04-6a3b-4d6f-8b1d-9c1b8b1b8b1b",
  • "timeframe": "total",
  • "from": "2026-06-01T00:00:00.000Z",
  • "to": "2026-07-01T00:00:00.000Z",
  • "charactersTotal": 12345,
  • "charactersFromCache": 4321,
  • "charactersGenerated": 8024,
  • "cacheHitRatio": 0.35
}