Documentation

Make a call

Create outbound calls to PSTN numbers, SIP addresses, or agent extensions via the REST API. You control what the callee hears with TwiML.

Prerequisites

A carrier account with a purchased phone number to use as From.
Your Account SID and Auth Token.

Call with inline TwiML

The simplest path: pass the TwiML directly in the request body. No server URL needed.

Examplets


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

const client = new RuutVoice({
  accountSid: process.env.RUUT_ACCOUNT_SID,
  authToken: process.env.RUUT_AUTH_TOKEN,
  baseUrl: "https://voice.ruut.chat",
});

const call = await client.calls.create({
  to: "+2348000000001",
  from: "+2348000000002",
  twiml: new VoiceResponse()
    .say("Hello! This call was placed with the Ruut Voice API.")
    .toXml(),
});

Call with a TwiML URL

Point Ruut Voice at a URL that returns TwiML. The URL is fetched with Method (GET or POST) when the call connects — ideal when your call flow depends on data you compute at answer time.

Examplets


const call = await client.calls.create({
  to: "+2348000000001",
  from: "+2348000000002",
  url: "https://app.example.com/twiml/welcome",
  method: "POST",
});

curl

curlbash


curl -X POST "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/Calls" \
  -u "$RUUT_ACCOUNT_SID:$RUUT_AUTH_TOKEN" \
  --data-urlencode "To=+2348000000001" \
  --data-urlencode "From=+2348000000002" \
  --data-urlencode "Url=https://app.example.com/twiml/welcome" \
  --data-urlencode "Method=POST" \
  --data-urlencode "StatusCallback=https://app.example.com/calls/status"

Call a SIP address or agent extension

Dial a SIP URI directly, or dial a provisioned agent extension by username (routed through your configured SIP domain):

Direct SIPts


// Direct SIP
await client.calls.createSipCall({
  sipUri: "sip:trunk@pbx.example.com",
  from: "+2348000000002",
  twiml: new VoiceResponse().say("Connecting you.").toXml(),
});

// Agent extension (username)
await client.calls.createAgentCall({
  agentUsername: "agent-1001",
  sipDomain: "sip.ruut.chat",
  from: "+2348000000002",
  twiml: new VoiceResponse().say("You are being connected to an agent.").toXml(),
});

Track call status

Set a statusCallback URL to receive asynchronous updates as the call progresses: queued → ringing → in-progress → completed (or a terminal failure). Each update is a signed webhook you can verify. See the call status webhook reference.

Outbound calls are rate-limited per account by Calls Per Second (CPS). Requests beyond the limit are queued automatically.

The response

Creating a call returns a Call resource with a sid and an initial status of queued:

Responsejson


{
  "sid": "CA2e9f6b3c4d5e6f7a8b9c0d1e2f3a4b5c",
  "status": "queued",
  "to": "+2348000000001",
  "from": "+2348000000002",
  "direction": "outbound-api",
  "uri": "/2010-04-01/Accounts/AC…/Calls/CA2e9f6b…"
}

See the Calls API reference for every parameter, or jump to receiving calls.