Phone
Connecting phone calls to voicast: Twilio Media Streams (TwiML), systems other than Twilio such as Telnyx, Plivo, Vonage, Exotel, Genesys and Asterisk, sending calls from a PBX over SIP, and handing calls off to a person.
You own the phone number and the carrier (Twilio, for example). Partway through an incoming call, return <Connect><Stream> TwiML and the call audio streams to the voicast voice server, where the AI takes the call. When the AI finishes, the audio stream closes and Twilio requests your action URL; there you look at the outcome and decide whether to transfer the call to a person or hang up.
Incoming call → your TwiML (<Connect><Stream>) → the voicast AI talks
→ the AI finishes → Twilio requests action → you return <Dial> or <Hangup/>TwiML#
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Connect action="https://saas.example.com/twilio/after">
<Stream url="wss://voice.voicast.jp/ws">
<Parameter name="tenant" value="ten_…" />
<Parameter name="secret" value="vts_…" />
<Parameter name="from" value="+819012345678" />
</Stream>
</Connect>
</Response>| Parameter | Required | Description |
|---|---|---|
tenant |
yes | Tenant ID (ten_…) |
secret |
yes | The tenant's connection secret (vts_…, returned when the tenant was created) |
agent |
Agent ID (agt_…). Defaults to the tenant's agent |
|
from |
The caller's number. Stored as the call's from and available to tools to look up the customer |
Twilio sends <Parameter> values as they are, so fill in from and the rest when your server builds the TwiML.
Node.js example#
Set the number's "A call comes in" webhook to https://saas.example.com/twilio/voice.
import express from 'express';
const app = express();
app.use(express.urlencoded({ extended: false }));
const xml = (s) => String(s).replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`);
// Incoming call: find your customer and its voicast tenant from the dialed number (To)
app.post('/twilio/voice', async (req, res) => {
const t = await findTenantByNumber(req.body.To); // { voicastTenantId, voicastSecret }
res.type('text/xml').send(`<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Connect action="https://saas.example.com/twilio/after">
<Stream url="wss://voice.voicast.jp/ws">
<Parameter name="tenant" value="${xml(t.voicastTenantId)}" />
<Parameter name="secret" value="${xml(t.voicastSecret)}" />
<Parameter name="from" value="${xml(req.body.From)}" />
</Stream>
</Connect>
</Response>`);
});Handoff#
When the AI ends the conversation, voicast writes the outcome before it closes the audio stream. Twilio then requests the <Connect> action with the CallSid, so look the call up with GET /v1/calls/by-provider/{CallSid} and return the next TwiML.
// After the AI: transfer to a person or hang up, depending on the outcome
app.post('/twilio/after', async (req, res) => {
const r = await fetch(`https://api.voicast.jp/v1/calls/by-provider/${req.body.CallSid}`, {
headers: { Authorization: `Bearer ${process.env.VOICAST_API_KEY}` },
});
const call = r.ok ? await r.json() : null;
// No record (the stream was refused), a handoff, or a failure: connect a person
const toHuman = !call || call.outcome === 'handoff' || call.outcome === 'error';
res.type('text/xml').send(
toHuman
? '<Response><Say language="ja-JP">担当者におつなぎします。</Say><Dial>+81312345678</Dial></Response>'
: '<Response><Hangup/></Response>',
);
});outcome |
What to do next, for example |
|---|---|
handoff |
<Dial> staff or a ring group |
completed, answered |
<Hangup/> (call back using the call's fields and summary) |
error |
Transfer to a person (the AI was cut off) |
hangup |
Nothing (the caller has already hung up) |
time_limit |
Transfer to a person, or <Hangup/> (the AI ended the call with a closing) |
| No record (404) | Transfer to a person (see "Refused calls" below) |
The reason for the handoff is in reason, and whatever was collected so far is in fields. Show them to the person taking over so the caller is not asked again. The call.handoff_requested webhook carries the same information, but webhook delivery order is not guaranteed, so base the transfer on the call you look up in action.
Refused calls#
In these cases the voice server closes the stream immediately and no call record is created. Twilio moves on to action, where the example above transfers to a person.
tenantorsecretis wrong, or the tenant is disabled (status: disabled)- New calls are being refused because the balance is zero or below (Pricing and billing)
- The voice server is busy and has reached its limit of concurrent calls (Errors and limits)
A call that has started is never cut off because the balance runs out.
Rotating the secret#
POST /v1/tenants/{id}/secret issues a new connection secret. The old one keeps working for 24 hours, so you have time to update your side.
Audio and behavior#
- Audio is Twilio Media Streams (8 kHz μ-law). voicast never hangs up calls through Twilio's REST API; call control stays with your Twilio account.
- When the caller starts talking, the AI stops mid-sentence and listens.
- If the caller is silent for a while, the AI asks again; if there is still no answer, it ends the call as
hangup. - Shortly before the maximum length (the agent's
max_call_minutes, 30 minutes by default), the AI ends the call with a fixed closing astime_limit. - If the audio stream reconnects with the same
CallSid(for example, after a voice server restart), the same call record is reused.
Cloud PBX and contact-center systems#
A cloud phone system, contact-center system or IVR built on Twilio can hand calls to voicast by returning the same <Connect><Stream> at the point where the AI should take over. A convenient pattern is to treat "AI reception" as one IVR step and use action to return to your own flow (ring group, voicemail and so on) when it ends.
- You can switch tenants or agents (
agent) per number or by time of day, for example to let the AI answer only after hours. - If you cannot use
action, put the verbs to run next (such as<Dial>) after</Connect>. When the stream closes, Twilio continues with the next verb. - To connect from a phone system other than Twilio, see "From systems other than Twilio" below.
From systems other than Twilio#
Besides Twilio, these phone systems can send call audio to voicast over WebSocket. In every case the phone number, the line, and call control stay with your service, and voicast never hangs up the call (when the AI finishes, it closes the audio connection and your service's flow continues).
| Sender | Endpoint | How to pass the tenant |
|---|---|---|
Telnyx (streaming_start, TeXML <Stream>) |
wss://voice.voicast.jp/ws/telnyx |
tenant (and agent, from) in custom_parameters; the connect secret in stream_auth_token |
Plivo (<Stream bidirectional="true">) |
wss://voice.voicast.jp/ws/plivo |
tenant=…;secret=… in extraHeaders (alphanumeric only, so you can drop the ten_ and vts_ prefixes) |
Vonage (NCCO connect, endpoint type websocket) |
wss://voice.voicast.jp/ws/vonage |
tenant (and agent, from, uuid) in the endpoint headers; authorization with type: custom and the connect secret as the value |
| Exotel (Voicebot applet) | wss://voice.voicast.jp/ws/exotel?tenant=…&secret=… |
The URL query (it arrives in custom_parameters) |
| Genesys Cloud (Audio Connector) | wss://voice.voicast.jp/ws/genesys/ plus the tenant ID as the connector ID |
The connect secret as the API key (X-API-KEY) |
| A PBX or similar (Twilio format) | wss://voice.voicast.jp/ws |
tenant and secret in customParameters of the start message (same as Twilio above) |
| Asterisk (chan_websocket, 20.18, 22.8, 23.2 or later) | wss://voice.voicast.jp/ws/asterisk |
Dial(WebSocket/<connection>/c(ulaw)f(json)v(tenant=…,secret=…)) |
- With any sender you can pass the values in the URL query instead (
?tenant=…&secret=…&agent=…&from=…). If both are present, the sender's own method wins. - Audio is taken in each sender's own format (Telnyx and Plivo 8 kHz μ-law, Vonage 16 kHz L16, Exotel 8 kHz PCM, Genesys 8 kHz μ-law, Asterisk
c(ulaw)). - Keep sending silent audio while the caller is quiet. If audio stops, voicast can't tell that the caller has finished speaking. Normal phone calls keep sending audio.
- With Plivo, set
keepCallAlive="true"so the next XML element runs after the connection closes. - voicast doesn't make calls (outbound). It also doesn't register to your line (SIP REGISTER). To send calls from a PBX over SIP, see "Over SIP" below.
Over SIP (from a PBX or cloud PBX)#
If your PBX or cloud PBX can send calls out over SIP, it can send them to voicast (sip.voicast.jp). The phone number and the line stay with the PBX; send only the calls you want the AI to take (after hours, overflow, the main number, and so on).
- Create a SIP credential for the tenant (
POST /v1/tenants/{id}/sip-credentials;create_sip_credentialin MCP).usernameandpasswordare returned only at this point. - Set up an outbound SIP trunk on the PBX as below, and route the calls for the AI to it.
| Setting | Value |
|---|---|
| Destination | sip.voicast.jp (UDP and TCP 5060, TLS 5061) |
| Authentication | Digest. Username is username (sipc_…), password is password, realm is voicast |
| Audio | G.711 (μ-law, A-law), 20 ms |
| Audio encryption | SRTP, with either key exchange: SDES (RTP/SAVP and a=crypto in the SDP; the keys travel in the SDP, so use it with TLS) or DTLS-SRTP (UDP/TLS/RTP/SAVP with a=fingerprint (sha-256) and a=setup in the SDP; the keys are exchanged over DTLS on the audio port). Suites: AES_CM_128_HMAC_SHA1_80 or _32 |
| TLS | Port 5061. The certificate is for sip.voicast.jp (Let's Encrypt). Devices that don't send SNI are accepted too |
| Registration (REGISTER) | Not needed (calls are also accepted if the PBX registers first) |
| Caller number | The number in From is kept in the call record as the caller |
- Each credential can pick an agent (
agent_id). If omitted, the tenant's agent answers. - If the credential has a transfer target (
transfer_to: an extension number or a SIP URI), when the AI hands the call to a person (outcome: handoff) voicast finishes the closing words and sendsREFER, and the PBX transfers the call there. Without a target, or if the PBX can't transfer, voicast hangs up withBYE. - When busy, voicast returns
486 Busy Here; when the tenant is disabled or the balance is empty,403 Forbidden. Route the call to the next destination (a person, voicemail, and so on) on the PBX side. - If authentication fails many times in a short period from the same address, voicast stops accepting SIP from that address for a while (it does not reply). If calls still fail after you fix the password, wait a while and try again.
- When the AI finishes, voicast hangs up with
BYEafter the closing words (or sendsREFERto transfer, as above). - Keep sending audio while the caller is quiet (normal calls do).
- voicast doesn't register to your line (SIP REGISTER).
Trying it out#
Use a tenant in the test environment with a Twilio trial number. Test calls are counted too. To check an agent without placing a call, talking to it from the Web is quicker.