agent.sms

Interface

Read and send SMS messages on the device. Requires SMS permissions.

AgentSMS Interface

interface AgentSMS {
  readSMS(options?: ReadSMSOptions): Promise<SmsMessage[]>;
  sendSMS(phoneNumber: string, message: string): Promise<boolean>;
}

interface ReadSMSOptions {
  phoneNumber?: string;        // Filter by phone number (partial match)
  limit?: number;              // Max messages (default: 20)
  skip?: number;               // Pagination offset (default: 0)
  sortOrder?: "asc" | "desc";  // Sort by date (default: "desc")
  type?: number;               // 1=inbox, 2=sent, 3=draft
  minDate?: number;            // After this timestamp (ms)
  maxDate?: number;            // Before this timestamp (ms)
}

readSMS

since 2.138 (150)

Signature

readSMS(options?: ReadSMSOptions): Promise<SmsMessage[]>

Reads SMS messages from the device. Useful for automations that need to read verification codes or other SMS content. All options are optional - calling with no arguments returns the 20 most recent messages.

Parameter	Type	Description
`options?`	ReadSMSOptions	Optional filtering and pagination options

Returns Promise<SmsMessage[]> — Array of SMS messages

Read latest SMS messages

const messages = await agent.sms.readSMS();

for (const msg of messages) {
  console.log("From:", msg.address);
  console.log("Body:", msg.body);
  console.log("Date:", new Date(msg.date).toLocaleString());
  console.log("---");
}

Find OTP/verification code

// Get recent inbox messages from the last 5 minutes
const fiveMinAgo = Date.now() - 5 * 60 * 1000;
const messages = await agent.sms.readSMS({
  type: 1,       // inbox only
  minDate: fiveMinAgo,
  limit: 10,
});

// Find message with OTP code
const otpMsg = messages.find(m =>
  m.body.includes("code") || m.body.includes("OTP")
);

if (otpMsg) {
  const codeMatch = otpMsg.body.match(/\b\d{4,6}\b/);
  if (codeMatch) {
    console.log("OTP code:", codeMatch[0]);
  }
}

Filter by phone number

const messages = await agent.sms.readSMS({
  phoneNumber: "+1234567890",
  limit: 5,
});

console.log("Messages from +1234567890:", messages.length);

Paginate through messages

// First page
const page1 = await agent.sms.readSMS({ limit: 10, skip: 0 });

// Second page
const page2 = await agent.sms.readSMS({ limit: 10, skip: 10 });

Read sent messages (oldest first)

const sentMessages = await agent.sms.readSMS({
  type: 2,            // sent messages
  sortOrder: "asc",   // oldest first
  limit: 20,
});

sendSMS

since 2.138 (150)

Signature

sendSMS(phoneNumber: string, message: string): Promise<boolean>

Sends an SMS message from the device. Long messages are automatically split into multiple parts. Requires SEND_SMS permission.

Parameter	Type	Description
`phoneNumber`	string	Recipient phone number
`message`	string	Text message to send

Returns Promise<boolean> — Resolves to true if the message was sent successfully

Send a simple SMS

const success = await agent.sms.sendSMS("+1234567890", "Hello from automation!");
console.log("SMS sent:", success);

Send SMS with error handling

try {
  await agent.sms.sendSMS("+1234567890", "Your verification code is 1234");
  console.log("SMS sent successfully");
} catch (error) {
  console.error("Failed to send SMS:", error.message);
}

Send SMS using job variables

const { phoneNumber, messageTemplate } = agent.arguments.jobVariables;
await agent.sms.sendSMS(phoneNumber, messageTemplate);

ReadSMSOptions

Options for filtering and paginating SMS messages.

ReadSMSOptions

interface ReadSMSOptions {
  phoneNumber?: string;        // Filter by phone number (partial match)
  limit?: number;              // Max messages to return (default: 20)
  skip?: number;               // Messages to skip (default: 0)
  sortOrder?: "asc" | "desc";  // Sort by date (default: "desc")
  type?: number;               // SMS type: 1=inbox, 2=sent, 3=draft
  minDate?: number;            // Only after this timestamp (Unix ms)
  maxDate?: number;            // Only before this timestamp (Unix ms)
}

ReadSMSOptions Properties

Name	Type	Description
`phoneNumber?`	string	Filter messages by phone number. Uses partial matching so both full and partial numbers work.
`limit?`	number	Maximum number of messages to return. Defaults to 20.
`skip?`	number	Number of messages to skip for pagination. Defaults to 0.
`sortOrder?`	"asc" \| "desc"	Sort order by date. "desc" returns newest first (default), "asc" returns oldest first.
`type?`	number	Filter by SMS type: 1 = inbox (received), 2 = sent, 3 = draft. Omit to include all types.
`minDate?`	number	Only return messages after this timestamp (Unix milliseconds).
`maxDate?`	number	Only return messages before this timestamp (Unix milliseconds).

SmsMessage

Represents an SMS message.

SmsMessage

interface SmsMessage {
  id: string;       // Unique message ID
  address: string;  // Phone number
  body: string;     // Message text content
  date: number;     // Timestamp (Unix ms)
  type: number;     // 1=inbox, 2=sent, 3=draft
  read: boolean;    // Has been read
  seen: boolean;    // Has been seen
}

SmsMessage Properties

Name	Type	Description
`id`	string	Unique identifier for the SMS message
`address`	string	Phone number - sender for inbox messages, recipient for sent messages
`body`	string	The text content of the message
`date`	number	Message timestamp in Unix milliseconds
`type`	number	Message type: 1 = inbox (received), 2 = sent, 3 = draft
`read`	boolean	Whether the message has been read
`seen`	boolean	Whether the message has been seen by the user

SMS operations require the READ_SMS and SEND_SMS permissions to be granted on the device. The app requests these automatically during setup. If permissions are denied, the corresponding methods return an error.