Setting it up

Getting live calls from your phone system into Callens takes four steps, done by three people: the Callens team, your Callens admin, and whoever builds the bridge from your phone system. The last step is each agent's, once.

The protocol itself — every message, frame and error — is on the Live Connect page. This page is the order to do things in.

1. Callens turns Live Connect on for your organization

Live Connect is off until your plan includes live streams. Ask Callens to turn it on; you will be told how many live streams your organization may hold at once.

A live stream is one transcribed channel of one call. A call with the customer and the agent on separate channels normally uses two, so a limit of 20 streams is about 10 calls at once. Until it is turned on, every call is refused with not_in_plan.

2. Your admin creates a live source

In Callens, go to Settings → Live sources → New live source and name it after the system that will connect, for example "Main PBX". Choose what it transcribes:

• Customer and agent — both channels. Each call uses two live streams.
• Customer only — the agent's audio is still received, just not transcribed or counted. Each call uses one.

Callens shows the source's credential (clkl_…) once. Give it to whoever builds the bridge, and keep it like a password: it is the only thing a bridge needs to stream calls into your organization. The same screen shows the address the bridge connects to:

wss://live.callens.io/v1/connect

3. Your developers build the bridge

The bridge sits between your phone system and Callens. It can be a SIPREC receiver, an Asterisk or FreeSWITCH application, a Twilio or Genesys media-stream consumer — anything that can see a call's audio and its events. Callens does not ship these bridges; your team builds the one your phone system needs, against the Live Connect protocol.

For every call, the bridge:

1. Connects one WebSocket to wss://live.callens.io/v1/connect, with Authorization: Bearer clkl_….
2. Starts the call within 10 seconds with a start message: an id that is unique for all time, and the audio format — mulaw, alaw or pcm16, at 8 or 16 kHz, with the customer and the agent on separate channels whenever your phone system can provide them. It may also say who is calling: a phone number, an email address or your own system's id for the customer.
3. Streams audio at real-time pace, one channel byte and then the audio in each binary frame.
4. Reports what happens: agent_joined when a person picks up (with your id for them — an extension or an agent id), transferred, hold and resume, and stop when the call ends.
5. Reconnects if the socket drops, by sending the same start again within 30 seconds. The call carries on where it was.

4. Each agent claims their seat, once

An agent opens the Live page in Callens and claims their seat: the same agent id or extension your bridge sends in agent_joined. From then on, a call they are on appears on their Live page as it happens — the conversation line by line, labelled customer and agent, with Assist for a suggested answer drawn from your organization's library.

A call whose agent has not claimed a seat is still transcribed and kept; it simply appears on no one's Live page.

Check it works

Before real traffic, make one test call through the bridge:

• The bridge receives started within a second or two of sending start. An error instead names what to fix — see Errors.
• The call appears on the Live page of the agent who claimed the seat your bridge sent, and its lines are labelled with the right speaker. Swapped labels mean the channel roles in start are the wrong way round.
• stop is answered with ended, and the agent's Live page says the call has ended.
• Pull the network mid-call and let the bridge reconnect: the same call should carry on, with resumed: true in started.