Skip to main content

Phone calls (SIP)

Any agent can answer a phone number and place phone calls. Orchestrate runs its own SIP gateway in your cluster: a Kamailio edge that faces your carrier or PBX, and a bridge behind it that joins each call to the agent. There is no hosted telephony service in between, so you bring your own carrier (any SIP trunk) or your own PBX.

A phone call is a voice session like a Playground call. The agent, its pipeline, tools, approvals that wait on the line, languages, voices, trace and audit work the same way. See Voice agents.

Requires network setup

The gateway is off by default. Your operator turns it on with sipGateway.enabled. A real carrier must reach the gateway's SIP port (5060) and its RTP media port range from outside the cluster, which means a node with a routable address or a load balancer, and firewall rules. That is infrastructure work outside the Helm chart. Without it, calls work only from inside the cluster. See Configuration.

Set up​

Open Telephony in the console. Viewers can see the set-up. Changing it needs the developer or admin role on the project. Calls need the licence's voice feature.

1. Add a trunk​

A trunk says how calls arrive and leave.

SettingWhat it means
Inbound, by addressThe carrier's signalling addresses, as CIDRs. A call is accepted only from those addresses and only to one of this trunk's numbers, because carriers share address ranges between customers.
Inbound, by passwordA username and password your PBX registers with (SIP digest). The username must be unique on the install.
No inboundThe trunk is used for outbound calls only.
OutboundThe carrier's host, port and transport (UDP, TCP, or TLS when the gateway has TLS), an optional username and password, the caller IDs the trunk may present, and its codecs.
Channel limitThe most calls the trunk carries at once. More are refused as busy.

Passwords go to Vault. The console only shows whether one is set.

2. Add a number​

A number belongs to a trunk and is answered by an agent. Per number you can set:

  • the call language, otherwise the agent's own voice settings
  • the greeting
  • whether calls are recorded
  • transfer targets, as name=number: the only places the agent may send a caller
  • the longest a call may last

Under Call recording, recording is off until an organization admin gives consent for the organization, and sets how long recordings are kept (30 days by default, up to 365). With consent off, nothing is recorded, whatever a number says.

Calls​

Inbound. The carrier sends the call to the gateway. Orchestrate checks the number, the trunk's channel limit, the licence, the project's and organization's budgets and the install's voice capacity, then the agent answers. A refusal is a SIP answer: 404 for an unknown number, 486 when the trunk is full, 480 over budget or licence, 503 with no voice capacity. A source the gateway doesn't know gets no answer at all.

Outbound. Choose Call a number in the console, or call POST /projects/{project_id}/sip/calls with the number to dial and the number (or the trunk and agent) to call from. The agent waits in the call. When the person answers, the agent greets them. With no answer within 45 seconds by default, the call is cancelled. Busy, no answer, rejected and failed calls are recorded as such.

The first sentence. Every call starts with the number's greeting. The default is "Hello, you're speaking with an AI assistant.", the AI disclosure several jurisdictions require at the start of a call. A recorded call always adds "This call is recorded.", even to a custom greeting.

The keypad. Key presses arrive as RFC 4733 events or SIP INFO. Orchestrate collects digits until # or 1.5 seconds of quiet, and gives the agent one turn such as (The caller pressed: 1 2 #). This works on every pipeline.

Ending and transferring. Every agent on a phone call has an end_call tool, which hangs up once its goodbye has played, and, when the number has transfer targets, a transfer_call tool that sends the caller to a target by name (a blind SIP REFER). Anything else is refused. This works on every pipeline:

  • Direct: the tools run in the voice worker.
  • Whole workflow: the two tools are added, for that call's turns only, to the step whose answer is spoken: a linear agent's last step, or the model steps that end a graph. A step with structured output never gets them. They need no approval and show in the trace. The stored agent version is unchanged.
  • Code agent: the two tools are offered to the code agent as client tools. A framework that doesn't take client tools is asked again without them, and the rest of the call skips them.

The agent hangs up or transfers once its answer has been spoken. A turn that says nothing first gets a short goodbye or "transferring you" line, and a refused transfer is apologised for.

In the console, Hang up ends a call. A call also ends when the caller hangs up, at the number's longest call, or after 60 seconds without media.

Barge-in. The caller can talk over the agent. On phone calls Orchestrate also shows partial transcripts while the caller speaks.

Recordings​

A call is recorded only with the organization's consent and the number's switch, checked again when the recording arrives. The recording is one stereo WAV file, caller on the left and agent on the right, kept in the install's object storage. It is deleted after the organization's retention period, when consent is withdrawn, and when the call record is deleted. Developers and admins play it from the call's row under Calls, and every play is audited.

A stored recording is labelled as AI-generated speech, inside the WAV file and in its stored metadata, and its download says so in a header. With a diarization model on the agent, the call's transcript says who spoke when. See Speaker labels on recordings.

Metering​

At the end of an answered call the gateway reports the billable seconds, from answer to hang-up. Every started minute is charged at the price of the model sip-minutes, which a platform admin sets under Usage > Model prices as a per-request price. The cost counts against the project's and organization's monthly budgets. The call's speech and model usage is metered as for any voice call. See Usage controls.

Capacity​

  • The install. The voice capacity covers browser and phone calls together. See Voice agents.
  • Each trunk. Its channel limit. Calls on one trunk are admitted one at a time, so a burst can't overrun it.
  • Each gateway pod. 50 calls by default, and one even RTP port per call from its port range. Add gateway replicas on host-network nodes, each with its own address on the carrier's trunk.

Security​

  • The edge holds no trunk passwords. It asks Orchestrate to authorise each source.
  • Flood limits, scanner filtering and topology hiding run at the edge.
  • The bridge takes a call's media only from the address the far end's SDP names, and then only from the one address and port it latched onto, so a stranger can't listen to or inject audio into a call. Your operator can relax this for a carrier whose media comes from an address its SDP doesn't name.

TLS and SRTP​

Both are off by default.

  • SIP over TLS. With sipGateway.tls.enabled and a TLS certificate Secret, the gateway also listens on port 5061, and a trunk can use transport TLS for outbound calls. Outbound TLS checks the carrier's certificate against the system CA bundle. The API refuses a TLS trunk while the gateway has no TLS, and the gateway never sends a TLS trunk's call in clear.

  • SRTP. sipGateway.srtp encrypts the media with SDES keys (AES_CM_128_HMAC_SHA1_80 and _32):

    SettingInboundOutbound
    offPlain RTP. An encrypted-only offer is refused (488).Plain RTP.
    optionalSRTP when the offer has usable keys, otherwise plain.Offers keys; SRTP if the answer has them.
    requiredRefused (488) without usable keys.Encrypted only; an answer without keys is hung up.

    SDES keys travel in the SIP signalling, so SRTP is only as private as the signalling: use it with TLS. Media that fails authentication is dropped. Each call's record says whether it used SRTP.

Requires a certificate and public exposure

TLS needs a certificate your carrier trusts for the gateway's public name, and both TLS and SRTP need the gateway reachable from the carrier. That is infrastructure work outside the chart. See Configuration.

Not available yet​

Coming
  • Attended transfer, and dial-out-and-bridge when a carrier refuses REFER. The agent says the transfer failed.
  • Codecs beyond G.711 (G.722, Opus), and DTLS-SRTP. SDES SRTP is available.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →