Receive calls with TwiML

When someone calls one of your numbers, Ruut Voice answers and executes a set of TwiML instructions — XML that tells the platform what to say, play, gather, or dial next.

How inbound call handling works

A caller dials a number assigned to your account.
Ruut Voice sends an HTTP request to the number's Voice URL (GET or POST).
Your server returns TwiML.
Ruut Voice executes the TwiML: speaks, plays audio, gathers input, or dials out.

Configure the Voice URL

Set the Voice URL in the dashboard for the incoming number, or via the IncomingPhoneNumbers API:

1234curl -X POST "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/IncomingPhoneNumbers/$NUMBER_SID" \
  -u "$RUUT_ACCOUNT_SID:$RUUT_AUTH_TOKEN" \
  --data-urlencode "VoiceUrl=https://app.example.com/twiml/inbound" \
  --data-urlencode "VoiceMethod=POST"

A simple greeting

Your endpoint returns XML. Here's a greeting that also plays a tone:

123<Response>
  <Say voice="alice" language="en-NG">Thanks for calling!</Say>
</Response>

Build it with the SDK instead of hand-writing XML:

12345import { VoiceResponse } from "@ruut/voice-sdk";

const xml = new VoiceResponse()
  .say("Thanks for calling!", { voice: "alice", language: "en-NG" })
  .toXml();

Combine <Gather> and <Say> to collect a digit and route the caller:

123456<Response>
  <Gather numDigits="1" action="/twiml/menu" method="POST">
    <Say>Press 1 for sales. Press 2 for support.</Say>
  </Gather>
  <Say>We did not receive any input. Goodbye.</Say>
</Response>

The action URL is requested with the gathered digits (as Digits) when the caller finishes. Route on them however you like.

Dial a number or agent

Forward the call to a phone number, a SIP URI, a client, or a conference:

123<Response>
  <Dial>+2348000000009</Dial>
</Response>

12345<Response>
  <Dial record="record-from-answer-dual">
    <Conference startConferenceOnEnter="true">support-room</Conference>
  </Dial>
</Response>

Record the call

Use <Record> to capture a message, or record a bridged call with <Dial record="…">. See the recording guide for full details.

TwiML reference

Every verb and attribute is documented in the TwiML verbs reference.

The root element must always be <Response>. When building with the SDK, call .toXml() on the VoiceResponse object (not on a sub-builder like dial), or the response will be rejected.