All pages

Docs

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.

View as Markdown

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
<?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.

js
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.

js
// 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.

  • tenant or secret is 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 as time_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).

  1. Create a SIP credential for the tenant (POST /v1/tenants/{id}/sip-credentials; create_sip_credential in MCP). username and password are returned only at this point.
  2. 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 sends REFER, and the PBX transfers the call there. Without a target, or if the PBX can't transfer, voicast hangs up with BYE.
  • 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 BYE after the closing words (or sends REFER to 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.