Phone — Ravi Docs

An identity can own a real phone number for both SMS and voice. Your agent can text from it, read what arrives, block until a one-time code lands, and place calls — the same number works over the CLI, the Python SDK, and the TypeScript SDK.

Every example below runs against one identity. Grab it once (or set it as the active identity in the CLI) and the rest follow. Need one first? See Identities.

Select the identity to work with

ravi identity use <identity-uuid>

from ravi import Ravi

ravi = Ravi(api_key="ravi_id_...")
identity = ravi.identities.get("<identity-uuid>")

import { Ravi } from "@ravi-hq/sdk";

const ravi = new Ravi({ apiKey: process.env.RAVI_API_KEY! });
const identity = await ravi.identities.get("<identity-uuid>");

The phone is optional — identity.phone may be null until you provision one. Add a number with provision_phone (see Identities). In TypeScript the field is nullable, so the examples use identity.phone?.….

Send an SMS

Text any number from the identity’s own line.

ravi sms send --to +15551234567 --body "Hi from my agent"

sms = identity.phone.send(
  to="+15551234567",
  body="Hi from my agent",
)

const sms = await identity.phone?.send(
"+15551234567",
"Hi from my agent",
);

Read the SMS inbox

List messages as a flat feed — filter to unread to see only what needs attention.

ravi message sms --unread

inbox = identity.phone.inbox(unread=True)
for sms in inbox:
  print(sms.from_number, sms.body)

const inbox = await identity.phone?.inbox({ unread: true });
for (const sms of inbox) {
console.log(sms.from_number, sms.body);
}

List conversations

Prefer messages grouped by the other party? List conversations instead.

ravi inbox sms

conversations = identity.phone.conversations()

const conversations = await identity.phone?.conversations();

Read one message

Fetch a single message by id to see its full body and sender.

ravi message sms <message-id>

sms = identity.phone.get("<message-id>")
print(sms.from_number)
print(sms.body)

const sms = await identity.phone?.get("<message-id>");
console.log(sms.from_number);
console.log(sms.body);

Wait for a one-time code

The move that makes agents work: trigger a login somewhere, then block until the SMS code arrives. wait_for polls the inbox and returns the first message that matches.

# Kick off a login elsewhere, then wait for the code to land.
sms = identity.phone.wait_for(
  lambda m: "code" in m.body.lower(),
  timeout=120,
)
print(sms.body)

// Kick off a login elsewhere, then wait for the code to land.
const sms = await identity.phone?.waitFor(
(m) => m.body.toLowerCase().includes("code"),
{ timeoutMs: 120_000 },
);
console.log(sms.body);

Reply to an SMS

Messages carry their own actions — reply straight to the sender.

sms = identity.phone.get("<message-id>")
sms.reply(body="Got it, thanks!")

const sms = await identity.phone?.get("<message-id>");
await sms.reply("Got it, thanks!");

Place a voice call

Dial any number from the identity’s line.

ravi call --to +15551234567

call = identity.phone.call(to="+15551234567")
print(call.uuid, call.status)

const call = await identity.phone?.call("+15551234567");
console.log(call.uuid, call.status);

Get a call transcript

Pull the transcript once a call has ended.

ravi call transcript <call-id>

call = identity.phone.call(to="+15551234567")
transcript = call.transcript()

const call = await identity.phone?.call("+15551234567");
const transcript = await call.transcript();

Hang up a call

End a call that’s still in progress.

ravi call hangup <call-id>

call.hangup()

await call.hangup();

Looking for exact request and response fields? See the full API reference.