Telephony API: connections, scenarios and calls

The Telephony API manages a project's SIP connections and AI call settings, starts outbound calls and reads call results. Its public base address is https://api.sensever.com/v1/telephony. Every request needs X-Workspace-Id with the numeric Sensever project ID. The gateway and service check the signed-in person's project access.

Create an API key

In Sensever, open Profile → API, name a new key, select the AI assistant calls permissions and choose the projects it may use. The three permissions are independent: View (telephony:read) reads settings, calls, transcripts and recording status; Manage (telephony:write) changes connections, agents and scenarios; Start calls (telephony:call) starts outbound and test calls. Select each permission your integration needs. Only project owners and administrators can grant their projects. Copy the ak1.… secret when it appears; it is shown once. You can set an expiration and revoke the key in the same section.

Send the key from your server in Authorization: Bearer, and send the numeric project ID in X-Workspace-Id on every request. A key works only for its selected projects and permissions. The service also checks that the key's owner still has access to the project. Removing project access stops its use; key revocation can take up to 60 seconds to reach the gateway because key checks are cached. Keep the secret on your server, away from browser code and public repositories.

curl 'https://api.sensever.com/v1/telephony/connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Id: 123' \
  -H 'Accept: application/json'

Requests from the Sensever interface can also use the signed-in browser session. A browser client on sensever.com sends the API cookie with credentials: "include" and the site's origin; server integrations should use an API key.

For an interactive client running on sensever.com with a valid API session, a read looks like this:

const projectId = '123'; // numeric project ID, not an agent or connection UUID
const response = await fetch('https://api.sensever.com/v1/telephony/connections', {
  credentials: 'include',
  headers: { Accept: 'application/json', 'X-Workspace-Id': projectId },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error?.code || body.error || 'request_failed');
console.log(body.data);

Use Content-Type: application/json for JSON writes. Responses from Telephony use error.code, error.message_key and, for validation, error.details; keep the response's X-Request-ID when reporting an error. IDs for connections, agents, scenarios and calls are UUIDs, while the project header is a numeric ID. Data belongs to that project; an ID from another project is not accessible. A request without the required key scope or project access receives 403.

Routes

Create a PBX extension connection with POST /connections:

{"type":"sip_register","name":"Sales line","server":"pbx.example.com","username":"205","password":"YOUR_EXTENSION_PASSWORD","transport":"tls","port":5061}

server, username and password are required for sip_register; UDP/5060 is the default if transport and port are omitted. The API also supports sip_uri for PBXs that route to a SIP URI. A connection's password and SIP URI secret are write-only; save a newly issued URI secret when it is returned. Use PATCH /connections/{id} to set its default_agent_id after creating a call agent. Set the agent's connection_ids to include the connection. The interface in Phone calls with your project AI assistant guides you through this setup.

An agent has a name, optional assistant_id linking the project assistant, language, voice, greeting, instructions and connection_ids. You can also set max_duration_sec, silence_prompt_sec, silence_hangup_sec, transfer_to, phone tools and verification_methods. To permit ordinary outbound calls, set outbound to {"enabled":true,"prefixes":["+7"],"daily_minutes":60}. Allowed prefixes and daily minutes are checked before a call starts; the PBX must also allow external calls.

Start a call and inspect it

Create a scenario with POST /scenarios and a body like {"name":"Delivery follow-up","greeting":"Hello, this is the delivery assistant.","instructions":"Confirm the delivery day and record any change."}. name and instructions are required. The scenario ID can then be used for a specific call; its greeting and instructions are snapshotted when the call starts.

Call POST /calls with a stable Idempotency-Key of 8–200 printable characters for one business action, connection_id, an international to number such as +79001234567, and optional scenario_id and caller_id. If agent_id is omitted, the connection's default agent is used. Repeating the same key and body returns the same call; reusing the key for a different call is refused.

curl 'https://api.sensever.com/v1/telephony/calls' \
  -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Id: 123' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-business-action-123' \
  -d '{"connection_id":"YOUR_CONNECTION_UUID","scenario_id":"YOUR_SCENARIO_UUID","to":"+79001234567"}'

Read GET /calls/{id} for the outcome and GET /calls/{id}/transcript for the conversation. GET /calls?limit=50 lists project calls; filters include connection_id, agent_id and a cursor for the next page. search matches numbers, scenario text and call IDs without leaving the project. GET /calls/{id}/recording returns a status; it supplies a short-lived protected playback URL only when the recording is ready. Historical calls without a recording remain unavailable.